# DocuSign Bulk Send — Demo Guide

## What is Bulk Send?
Bulk Send lets you send one template to **many recipients at once** — each gets their own unique envelope, personalized with their name, email, and custom field values.

## Files in This Directory

| File | Purpose |
|------|---------|
| `bulk_send.py` | Main script — creates bulk list, envelope, and sends |
| `recipients.csv` | Sample recipient list (5 demo contacts) |

---

## CSV Format

```csv
Name,Email,Company,Title,CustomField1
Alice Johnson,alice.johnson@example.com,Acme Corp,CEO,CONTRACT-001
```

| Column | Maps To |
|--------|---------|
| Name | Recipient display name |
| Email | Recipient email address |
| Company | Tab value in template (`Company` tab) |
| Title | Tab value in template (`Title` tab) |
| CustomField1 | Envelope custom field (tracking/reference) |

---

## How to Run

### Dry Run (safe — no emails sent)
```bash
source venv/bin/activate
python3 bulk-send/bulk_send.py \
  --template-id <YOUR_TEMPLATE_ID> \
  --csv bulk-send/recipients.csv \
  --dry-run
```

### Live Send
```bash
python3 bulk-send/bulk_send.py \
  --template-id <YOUR_TEMPLATE_ID> \
  --csv bulk-send/recipients.csv
```

---

## How It Works (3 API Calls)

```
1. POST /bulk_send_lists        → Upload recipient list → get bulk_list_id
2. POST /envelopes              → Create draft envelope from template → get envelope_id
3. POST /bulk_send_lists/{id}/send → Trigger send → get batch_id
```

Each recipient gets:
- Their own envelope
- Pre-filled tabs (name, company, title)
- Unique signing link via email

---

## DocuSign API Docs
- [Bulk Send Concept](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/envelopes/bulk-send/)
- [How-To: Bulk Send Envelopes](https://developers.docusign.com/docs/esign-rest-api/how-to/bulk-send-envelopes/)

---

## Notes for Customer Demo
- Uses **demo environment** (demo.docusign.net) — no real emails sent
- Template must have a signer role named **"Signer"**
- Tabs in template must be named `Company` and `Title` to auto-fill from CSV
- Batch status can be checked via: `GET /bulk_send_batch/{batchId}`