> ## Documentation Index
> Fetch the complete documentation index at: https://pigeonpost-developer.27communication.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drafts

> Save drafts in the user's mailbox, edit them, and send them later.

Drafts are stored **at the provider**, in the user's Drafts folder, so the user also sees them in Gmail or their email app.

## Create a draft

Same fields as [sending an email](/emails/send). Recipients are optional, and Bcc recipients are kept with the draft.

```bash theme={null}
curl -X POST "$EE_URL/api/v1/drafts" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
    "to": ["ana@example.com"],
    "bcc": ["archive@example.com"],
    "subject": "Draft proposal",
    "body": "<p>First version</p>"
  }'
```

```json Response 201 theme={null}
{
  "object": "DraftCreated",
  "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
  "draft_id": "drf_r-4419383208612875012",
  "message_id": "5b1c2d3e4f6a47b8@mail-api.example.com",
  "tracking_id": null
}
```

`draft_id` is `drf_` plus the provider's own draft id. When the draft syncs, an `email.draft.new` event is sent.

## Work with drafts

| Request | What it does |
| - | - |
| `GET /api/v1/drafts?account_id=acc_…` | Drafts that have synced, newest first ([paged with a cursor](/reference/pagination)) |
| `GET /api/v1/drafts/{draft_id}` | One draft |
| `PATCH /api/v1/drafts/{draft_id}` | Change it: the fields you send replace the draft's, the rest is kept (recipients, Bcc, body, attachments) |
| `POST /api/v1/drafts/{draft_id}/send` | Send it to its to, cc and bcc recipients |
| `DELETE /api/v1/drafts/{draft_id}` | Delete it. An `email.draft.delete` event follows |

`{draft_id}` is the `drf_…` id, or the synced draft's `email_…` id. A draft takes a moment to sync. Right after creating it, add `?account_id=acc_…` to these calls so the engine knows which mailbox to look in.

A draft is an [email object](/emails/retrieve) with `"object": "Draft"` and a `draft_id`:

```json theme={null}
{
  "object": "Drafts",
  "data": [
    {
      "object": "Draft",
      "id": "email_c2d3e4f5a6b74c8d9e0f1a2b3c4d5e6f",
      "draft_id": "drf_r-4419383208612875012",
      "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
      "subject": "Draft proposal",
      "to_attendees": [{ "display_name": "", "identifier": "ana@example.com" }],
      "role": "DRAFTS",
      "…": "…"
    }
  ],
  "has_more": false,
  "cursor": null
}
```

### Updating returns a new id

```bash theme={null}
curl -X PATCH "$EE_URL/api/v1/drafts/drf_r-4419383208612875012?account_id=acc_ba1fa6938d8548298e8ce62e4b4b4e99" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{ "subject": "Final proposal", "from": { "display_name": "Ana from Sales" } }'
```

```json Response theme={null}
{
  "object": "DraftUpdated",
  "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
  "draft_id": "drf_r-7720519843306512244",
  "previous_draft_id": "drf_r-4419383208612875012",
  "message_id": "6c2d3e4f5a7b48c9@mail-api.example.com",
  "tracking_id": null
}
```

The draft is saved again at the provider, so it gets a new `draft_id`. The previous one no longer works: use the new one from then on.

### Send

```bash theme={null}
curl -X POST "$EE_URL/api/v1/drafts/drf_r-7720519843306512244/send" -H "X-API-KEY: $EE_KEY"
```

```json Response theme={null}
{ "object": "DraftSent", "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99", "draft_id": "drf_r-7720519843306512244", "provider_id": null }
```

The draft leaves the Drafts folder (`email.draft.delete`) and the sent email appears in Sent with `origin: "api"` (`email.new`). Bcc recipients receive it without being listed in the delivered email.

### Delete

```bash theme={null}
curl -X DELETE "$EE_URL/api/v1/drafts/drf_r-7720519843306512244" -H "X-API-KEY: $EE_KEY"
```

```json Response theme={null}
{ "object": "DraftDeleted", "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99", "draft_id": "drf_r-7720519843306512244" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.