[Skip to content](/content/docs/reference/api/drafts#nd-page/index.html) [Skip to content](/content/docs/reference/api/drafts#nd-page/index.html)

\[01/18\]List Drafts

| Method | Path | Summary |
| --- | --- | --- |
| `GET` | `/v0/drafts` | [List Drafts](/content/docs/reference/api/drafts#list-drafts/index.html) |
| `GET` | `/v0/drafts/{draft_id}` | [Get Draft](/content/docs/reference/api/drafts#get-draft/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/drafts` | [List Drafts](/content/docs/reference/api/drafts#list-drafts/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/drafts` | [Create Draft](/content/docs/reference/api/drafts#create-draft/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/drafts/{draft_id}` | [Get Draft](/content/docs/reference/api/drafts#get-draft/index.html) |
| `PATCH` | `/v0/inboxes/{inbox_id}/drafts/{draft_id}` | [Update Draft](/content/docs/reference/api/drafts#update-draft/index.html) |
| `DELETE` | `/v0/inboxes/{inbox_id}/drafts/{draft_id}` | [Delete Draft](/content/docs/reference/api/drafts#delete-draft/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download` | [Download Draft Attachment](/content/docs/reference/api/drafts#download-draft-attachment/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/drafts/{draft_id}/send` | [Send Draft](/content/docs/reference/api/drafts#send-draft/index.html) |
| `GET` | `/v0/pods/{pod_id}/drafts` | [List Drafts in Pod](/content/docs/reference/api/drafts#list-drafts-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/drafts/{draft_id}` | [Get Draft in Pod](/content/docs/reference/api/drafts#get-draft-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/drafts` | [List Drafts in Pod](/content/docs/reference/api/drafts#list-drafts-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/drafts` | [Create Draft in Pod](/content/docs/reference/api/drafts#create-draft-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}` | [Get Draft in Pod](/content/docs/reference/api/drafts#get-draft-in-pod/index.html) |
| `PATCH` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}` | [Update Draft in Pod](/content/docs/reference/api/drafts#update-draft-in-pod/index.html) |
| `DELETE` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}` | [Delete Draft in Pod](/content/docs/reference/api/drafts#delete-draft-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download` | [Download Draft Attachment in Pod](/content/docs/reference/api/drafts#download-draft-attachment-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/send` | [Send Draft in Pod](/content/docs/reference/api/drafts#send-draft-in-pod/index.html) |

## [List Drafts](/content/docs/reference/api/drafts\#list-drafts/index.html)

http

```
GET /v0/drafts
```

Drafts of every inbox in scope, newest first. The `labels` filter is not supported.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Query parameters](/content/docs/reference/api/drafts\#query-parameters/index.html)

FieldDescription

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`before``string (date-time)`

Only drafts created before this time.

`after``string (date-time)`

Only drafts created after this time.

`ascending``boolean`

Sort oldest first.

#### [Response](/content/docs/reference/api/drafts\#response/index.html)

**200** A page of drafts (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`drafts` [DraftItem\[\]](/content/docs/reference/api/objects#draftitem/index.html) Required

Ordered by created\_at, newest first unless ascending is set.

Each item of `drafts` is a [DraftItem](/content/docs/reference/api/objects#draftitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

scheduled while waiting for send\_at, sending while a sender holds it, failed when a scheduled send failed (it is not retried). Absent on drafts without send\_at.

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation.

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references.

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

#### [Errors](/content/docs/reference/api/drafts\#errors/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example/index.html)

Request

```
curl "https://api.machinemail.dev/v0/drafts" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "drafts": [\
    {\
      "inbox_id": "agent@machinemail.dev",\
      "draft_id": "drf_01k6x3b7hn0000e1n7qv3z6g8j",\
      "labels": ["UNREAD"],\
      "to": ["customer@example.com"],\
      "cc": ["team@example.com"],\
      "bcc": ["audit@example.com"],\
      "subject": "Order #1042",\
      "preview": "Thanks for the quick reply.",\
      "attachments": [\
        {\
          "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
          "filename": "invoice.pdf",\
          "size": 2048,\
          "content_type": "application/pdf",\
          "content_disposition": "string",\
          "content_id": "string"\
        }\
      ],\
      "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "send_status": "scheduled",\
      "send_at": "2026-10-01T12:00:00.000Z",\
      "updated_at": "2026-10-01T12:00:00.000Z",\
      "client_id": "my-client-id",\
      "reply_to": ["agent@machinemail.dev"],\
      "text": "Thanks for the quick reply.",\
      "html": "<p>Thanks for the quick reply.</p>",\
      "references": ["string"],\
      "created_at": "2026-10-01T12:00:00.000Z",\
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f"\
    }\
  ]
}
```

## [Get Draft](/content/docs/reference/api/drafts\#get-draft/index.html)

http

```
GET /v0/drafts/{draft_id}
```

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters/index.html)

FieldDescription

`draft_id``string`Required

ID of the draft.

#### [Response](/content/docs/reference/api/drafts\#response-1/index.html)

**200** The draft (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-1/index.html)

| Status | Meaning |
| --- | --- |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-1/index.html)

Request

```
curl "https://api.machinemail.dev/v0/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "inbox_id": "agent@machinemail.dev",
  "draft_id": "drf_01k6x3b7hn0000e1n7qv3z6g8j",
  "labels": ["UNREAD"],
  "to": ["customer@example.com"],
  "cc": ["team@example.com"],
  "bcc": ["audit@example.com"],
  "subject": "Order #1042",
  "preview": "Thanks for the quick reply.",
  "attachments": [\
    {\
      "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
      "filename": "invoice.pdf",\
      "size": 2048,\
      "content_type": "application/pdf",\
      "content_disposition": "string",\
      "content_id": "string"\
    }\
  ],
  "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "send_status": "scheduled",
  "send_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "client_id": "my-client-id",
  "reply_to": ["agent@machinemail.dev"],
  "text": "Thanks for the quick reply.",
  "html": "<p>Thanks for the quick reply.</p>",
  "references": ["string"],
  "created_at": "2026-10-01T12:00:00.000Z",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f"
}
```

## [List Drafts](/content/docs/reference/api/drafts\#list-drafts-1/index.html)

http

```
GET /v0/inboxes/{inbox_id}/drafts
```

Drafts of the inbox, newest first. The `labels` filter is not supported.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-1/index.html)

FieldDescription

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

#### [Query parameters](/content/docs/reference/api/drafts\#query-parameters-1/index.html)

FieldDescription

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`before``string (date-time)`

Only drafts created before this time.

`after``string (date-time)`

Only drafts created after this time.

`ascending``boolean`

Sort oldest first.

#### [Response](/content/docs/reference/api/drafts\#response-2/index.html)

**200** A page of drafts (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`drafts` [DraftItem\[\]](/content/docs/reference/api/objects#draftitem/index.html) Required

Ordered by created\_at, newest first unless ascending is set.

Each item of `drafts` is a [DraftItem](/content/docs/reference/api/objects#draftitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation.

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references.

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

#### [Errors](/content/docs/reference/api/drafts\#errors-2/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-2/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/drafts" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Create Draft](/content/docs/reference/api/drafts\#create-draft/index.html)

http

```
POST /v0/inboxes/{inbox_id}/drafts
```

With `send_at` the draft is scheduled: a background worker sends it at that time (`send_status: scheduled`). A scheduled send that fails sets `send_status: failed` and is not retried, except when the email provider could not take mail for now (throttled, sending paused, daily quota used up, or unavailable): the draft stays scheduled and a later pass sends it.

Reply drafts: set `in_reply_to` to a message ID in this inbox; recipients are not filled in for you. Forward drafts (`forward_of`) and `reply_all` are not supported.

A message can have at most 50 recipients: `to`, `cc` and `bcc` together, each address counted once. An unclaimed sandbox inbox can have at most 5. More is a `400``validation` error with `param: "to"`. The cap is checked when the draft is created or updated, and again when it is sent: a scheduled draft over the cap at send time gets `send_status: failed`.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_create`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-2/index.html)

FieldDescription

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

#### [Request body](/content/docs/reference/api/drafts\#request-body/index.html)

Content type: `application/json`.

FieldDescription

`labels``string[]`

Labels of the draft.

`reply_to``string | string[]`

Reply-to addresses: one address or a list.

`to``string | string[]`

Recipient addresses: one address or a list.

`cc``string | string[]`

CC addresses: one address or a list.

`bcc``string | string[]`

BCC addresses: one address or a list.

`subject``string`

Subject.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments, sent with the draft. Each needs content or url; a url is fetched when the draft is sent.

`in_reply_to``string`

ID of a message in this inbox to reply to: the sent message gets its In-Reply-To and References headers.

`send_at``string (date-time) | null`

Schedule the draft: it is sent automatically at this time (send\_status: scheduled). null or absent: not scheduled.

`client_id``string`

Idempotency key: a create with a client\_id already used in the organization returns that draft with 200, or 409 when that draft is outside the pod or inbox of the API key or route.

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/drafts\#response-3/index.html)

**200** A draft with this client\_id already exists; it is returned unchanged. (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

**201** Created (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-3/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `402` | Free plan over its storage (1 GB: messages, drafts and held mail): a draft cannot grow past it (limit\_key: “storage\_bytes”). Delete mail or drafts to make room. Paid plans are never refused. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `409` | Conflicts with an existing resource. |
| `500` | Unexpected server error. |
| `503` | The draft sets or moves send\_at and the scheduler is unavailable for a moment: nothing was saved. Retry with backoff. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-3/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/drafts" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'
```

Response 200

## [Get Draft](/content/docs/reference/api/drafts\#get-draft-1/index.html)

http

```
GET /v0/inboxes/{inbox_id}/drafts/{draft_id}
```

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-3/index.html)

FieldDescription

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Response](/content/docs/reference/api/drafts\#response-4/index.html)

**200** The draft (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-4/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-4/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Update Draft](/content/docs/reference/api/drafts\#update-draft/index.html)

http

```
PATCH /v0/inboxes/{inbox_id}/drafts/{draft_id}
```

Fields you omit are unchanged; `null` clears a field. `in_reply_to` cannot be changed.

A message can have at most 50 recipients: `to`, `cc` and `bcc` together, each address counted once. An unclaimed sandbox inbox can have at most 5. More is a `400``validation` error with `param: "to"`.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_update`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-4/index.html)

FieldDescription

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Request body](/content/docs/reference/api/drafts\#request-body-1/index.html)

Content type: `application/json`.

FieldDescription

`reply_to``string | string[] | null`

Reply-to addresses. null clears them.

`to``string | string[] | null`

Recipient addresses. null clears them.

`cc``string | string[] | null`

CC addresses. null clears them.

`bcc``string | string[] | null`

BCC addresses. null clears them.

`subject``string | null`

Subject. null clears it.

`text``string | null`

Plain text body. null clears it.

`html``string | null`

HTML body. null clears it.

`add_attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to add. Each needs content or url.

`remove_attachments``string[]`

IDs of attachments to remove. Unknown IDs are ignored.

`add_labels``string[]`

Labels to add.

`remove_labels``string[]`

Labels to remove (applied after add\_labels).

`send_at``string (date-time) | null`

Schedule (or reschedule) the draft. null unschedules it.

Each item of `add_attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/drafts\#response-5/index.html)

**200** The updated draft (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-5/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-5/index.html)

Request

```
curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply.",
  "add_labels": [\
    "string"\
  ]
}'
```

Response 200

## [Delete Draft](/content/docs/reference/api/drafts\#delete-draft/index.html)

http

```
DELETE /v0/inboxes/{inbox_id}/drafts/{draft_id}
```

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_delete`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-5/index.html)

FieldDescription

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Response](/content/docs/reference/api/drafts\#response-6/index.html)

**200** Deleted (`application/json`)

FieldDescription

`ok``true`Required

#### [Errors](/content/docs/reference/api/drafts\#errors-6/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-6/index.html)

Request

```
curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "ok": true
}
```

## [Download Draft Attachment](/content/docs/reference/api/drafts\#download-draft-attachment/index.html)

http

```
GET /v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download
```

The bytes of a base64 attachment on a draft, served like a message attachment download (`nosniff`, RFC 6266 `Content-Disposition`, `disposition=inline` previews for images, PDF and plain text only). `url` attachments are fetched when the draft is sent, so they return `404` until then.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-6/index.html)

FieldDescription

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

`attachment_id``string`Required

ID of the attachment.

#### [Query parameters](/content/docs/reference/api/drafts\#query-parameters-2/index.html)

FieldDescription

`disposition``"attachment" | "inline"`

inline previews raster images, PDF and plain text in the browser; every other type downloads regardless.

Default`"attachment"`

#### [Response](/content/docs/reference/api/drafts\#response-7/index.html)

**200** The attachment bytes (`application/octet-stream`)

Headers:

FieldDescription

`Content-Disposition``string`

attachment; filename="<ascii name>"; filename\*=UTF-8''<encoded name> (or inline; … for a preview).

#### [Errors](/content/docs/reference/api/drafts\#errors-7/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-7/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r/download" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

## [Send Draft](/content/docs/reference/api/drafts\#send-draft/index.html)

http

```
POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send
```

Sends the draft now and deletes it; a `draft.sent` and a `message.sent` event are emitted. The sent message gets the draft labels plus `add_labels`, minus `remove_labels`.

Suppressed recipients and recipients on a send block list return `403`, a paused inbox `403`. A draft already being sent returns `409`.

An unclaimed sandbox agent can send at most 10 messages to at most 10 different recipients per rolling 24 hours: `429` with `Retry-After`.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_send`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-7/index.html)

FieldDescription

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Request body](/content/docs/reference/api/drafts\#request-body-2/index.html)

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add.

`remove_labels``string | string[]`

Label or labels to remove.

#### [Response](/content/docs/reference/api/drafts\#response-8/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/drafts\#errors-8/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `402` | Free plan over its messages cap: 3,000 a month or 100 a day, inbound messages and outbound recipients together (each recipient counts once). error.limit\_key is messages\_per\_month or messages\_per\_day; resets\_at and Retry-After say when the allowance resets (absent when this message has more recipients than the cap itself). Paid plans are never refused. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `409` | Conflicts with an existing resource. |
| `429` | Unclaimed sandbox agent over a send cap: at most 10 messages to at most 10 different recipients per rolling 24 hours. Retry-After says when the next send fits. Claiming the inbox lifts the caps. Also returned when a Free organization goes over its daily number of different recipients. |
| `500` | Unexpected server error. |
| `501` | Not implemented. |
| `502` | The email provider refused or failed the send (error.type is upstream\_error). Nothing was sent and no message was stored. error.message says why: a rejected message or recipient is final, and so is a used-up sending quota until it resets; a throttled or unavailable provider can be retried later. A scheduled draft whose send fails this way is marked send\_status: failed, unless the provider could not take mail for now (throttled, sending paused, quota used up, or unavailable): it stays scheduled and is retried. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-8/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j/send" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add_labels": "string"
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [List Drafts in Pod](/content/docs/reference/api/drafts\#list-drafts-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/drafts
```

Same as List Drafts (`GET /v0/drafts`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-8/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

#### [Query parameters](/content/docs/reference/api/drafts\#query-parameters-3/index.html)

FieldDescription

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`before``string (date-time)`

Only drafts created before this time.

`after``string (date-time)`

Only drafts created after this time.

`ascending``boolean`

Sort oldest first.

#### [Response](/content/docs/reference/api/drafts\#response-9/index.html)

**200** A page of drafts (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`drafts` [DraftItem\[\]](/content/docs/reference/api/objects#draftitem/index.html) Required

Ordered by created\_at, newest first unless ascending is set.

Each item of `drafts` is a [DraftItem](/content/docs/reference/api/objects#draftitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation.

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references.

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

#### [Errors](/content/docs/reference/api/drafts\#errors-9/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-9/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/drafts" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Get Draft in Pod](/content/docs/reference/api/drafts\#get-draft-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/drafts/{draft_id}
```

Same as Get Draft (`GET /v0/drafts/{draft_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-9/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`draft_id``string`Required

ID of the draft.

#### [Response](/content/docs/reference/api/drafts\#response-10/index.html)

**200** The draft (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-10/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-10/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [List Drafts in Pod](/content/docs/reference/api/drafts\#list-drafts-in-pod-1/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts
```

Same as List Drafts (`GET /v0/inboxes/{inbox_id}/drafts`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-10/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

#### [Query parameters](/content/docs/reference/api/drafts\#query-parameters-4/index.html)

FieldDescription

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`before``string (date-time)`

Only drafts created before this time.

`after``string (date-time)`

Only drafts created after this time.

`ascending``boolean`

Sort oldest first.

#### [Response](/content/docs/reference/api/drafts\#response-11/index.html)

**200** A page of drafts (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`drafts` [DraftItem\[\]](/content/docs/reference/api/objects#draftitem/index.html) Required

Ordered by created\_at, newest first unless ascending is set.

Each item of `drafts` is a [DraftItem](/content/docs/reference/api/objects#draftitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation.

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references.

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

#### [Errors](/content/docs/reference/api/drafts\#errors-11/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-11/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/drafts" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Create Draft in Pod](/content/docs/reference/api/drafts\#create-draft-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts
```

Same as Create Draft (`POST /v0/inboxes/{inbox_id}/drafts`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_create`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-11/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

#### [Request body](/content/docs/reference/api/drafts\#request-body-3/index.html)

Content type: `application/json`.

FieldDescription

`labels``string[]`

Labels of the draft.

`reply_to``string | string[]`

Reply-to addresses: one address or a list.

`to``string | string[]`

Recipient addresses: one address or a list.

`cc``string | string[]`

CC addresses: one address or a list.

`bcc``string | string[]`

BCC addresses: one address or a list.

`subject``string`

Subject.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments, sent with the draft. Each needs content or url; a url is fetched when the draft is sent.

`in_reply_to``string`

ID of a message in this inbox to reply to: the sent message gets its In-Reply-To and References headers.

`send_at``string (date-time) | null`

Schedule the draft: it is sent automatically at this time (send\_status: scheduled). null or absent: not scheduled.

`client_id``string`

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/drafts\#response-12/index.html)

**200** A draft with this client\_id already exists; it is returned unchanged. (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

**201** Created (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-12/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-12/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/drafts" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'
```

Response 200

## [Get Draft in Pod](/content/docs/reference/api/drafts\#get-draft-in-pod-1/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}
```

Same as Get Draft (`GET /v0/inboxes/{inbox_id}/drafts/{draft_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-12/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Response](/content/docs/reference/api/drafts\#response-13/index.html)

**200** The draft (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-13/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-13/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Update Draft in Pod](/content/docs/reference/api/drafts\#update-draft-in-pod/index.html)

http

```
PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}
```

Same as Update Draft (`PATCH /v0/inboxes/{inbox_id}/drafts/{draft_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_update`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-13/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Request body](/content/docs/reference/api/drafts\#request-body-4/index.html)

Content type: `application/json`.

FieldDescription

`reply_to``string | string[] | null`

Reply-to addresses. null clears them.

`to``string | string[] | null`

Recipient addresses. null clears them.

`cc``string | string[] | null`

CC addresses. null clears them.

`bcc``string | string[] | null`

BCC addresses. null clears them.

`subject``string | null`

Subject. null clears it.

`text``string | null`

Plain text body. null clears it.

`html``string | null`

HTML body. null clears it.

`add_attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to add. Each needs content or url.

`remove_attachments``string[]`

IDs of attachments to remove. Unknown IDs are ignored.

`add_labels``string[]`

Labels to add.

`remove_labels``string[]`

Labels to remove (applied after add\_labels).

`send_at``string (date-time) | null`

Schedule (or reschedule) the draft. null unschedules it.

Each item of `add_attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/drafts\#response-14/index.html)

**200** The updated draft (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`draft_id``string`Required

ID of the draft.

`labels``string[]`Required

Labels of the draft. The sent message gets them.

`to``string[]`

Recipient addresses.

`cc``string[]`

CC addresses.

`bcc``string[]`

BCC addresses.

`subject``string`

Subject of the draft.

`preview``string`

Text preview of the draft.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

`in_reply_to``string`

ID of the message being replied to.

`send_status``"scheduled" | "sending" | "failed"`

`send_at``string (date-time)`

Time at which the draft is sent automatically.

`updated_at``string (date-time)`Required

Time at which the draft was last updated.

`client_id``string`

Client ID given at creation (idempotency key).

`reply_to``string[]`

Reply-to addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`references``string[]`

Message IDs the draft references (set from in\_reply\_to).

`created_at``string (date-time)`Required

Time at which the draft was created.

`pod_id``string`Required

ID of the pod.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

#### [Errors](/content/docs/reference/api/drafts\#errors-14/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-14/index.html)

Request

```
curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply.",
  "add_labels": [\
    "string"\
  ]
}'
```

Response 200

## [Delete Draft in Pod](/content/docs/reference/api/drafts\#delete-draft-in-pod/index.html)

http

```
DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}
```

Same as Delete Draft (`DELETE /v0/inboxes/{inbox_id}/drafts/{draft_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_delete`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-14/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Response](/content/docs/reference/api/drafts\#response-15/index.html)

**200** Deleted (`application/json`)

FieldDescription

`ok``true`Required

#### [Errors](/content/docs/reference/api/drafts\#errors-15/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-15/index.html)

Request

```
curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "ok": true
}
```

## [Download Draft Attachment in Pod](/content/docs/reference/api/drafts\#download-draft-attachment-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download
```

Same as Download Draft Attachment (`GET /v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_read`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-15/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

`attachment_id``string`Required

ID of the attachment.

#### [Query parameters](/content/docs/reference/api/drafts\#query-parameters-5/index.html)

FieldDescription

`disposition``"attachment" | "inline"`

inline previews raster images, PDF and plain text in the browser; every other type downloads regardless.

Default`"attachment"`

#### [Response](/content/docs/reference/api/drafts\#response-16/index.html)

**200** The attachment bytes (`application/octet-stream`)

Headers:

FieldDescription

`Content-Disposition``string`

attachment; filename="<ascii name>"; filename\*=UTF-8''<encoded name> (or inline; … for a preview).

#### [Errors](/content/docs/reference/api/drafts\#errors-16/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-16/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r/download" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

## [Send Draft in Pod](/content/docs/reference/api/drafts\#send-draft-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/send
```

Same as Send Draft (`POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `draft_send`.

#### [Path parameters](/content/docs/reference/api/drafts\#path-parameters-16/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

ID of the inbox: its email address, as in AgentMail (inbox\_id == email).

`draft_id``string`Required

ID of the draft.

#### [Request body](/content/docs/reference/api/drafts\#request-body-5/index.html)

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add.

`remove_labels``string | string[]`

Label or labels to remove.

#### [Response](/content/docs/reference/api/drafts\#response-17/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/drafts\#errors-17/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/drafts\#example-17/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/drafts/drf_01k6x3b7hn0000e1n7qv3z6g8j/send" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add_labels": "string"
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

On this page

[List Drafts](/content/docs/reference/api/drafts#list-drafts/index.html) [Get Draft](/content/docs/reference/api/drafts#get-draft/index.html) [List Drafts](/content/docs/reference/api/drafts#list-drafts-1/index.html) [Create Draft](/content/docs/reference/api/drafts#create-draft/index.html) [Get Draft](/content/docs/reference/api/drafts#get-draft-1/index.html) [Update Draft](/content/docs/reference/api/drafts#update-draft/index.html) [Delete Draft](/content/docs/reference/api/drafts#delete-draft/index.html) [Download Draft Attachment](/content/docs/reference/api/drafts#download-draft-attachment/index.html) [Send Draft](/content/docs/reference/api/drafts#send-draft/index.html) [List Drafts in Pod](/content/docs/reference/api/drafts#list-drafts-in-pod/index.html) [Get Draft in Pod](/content/docs/reference/api/drafts#get-draft-in-pod/index.html) [List Drafts in Pod](/content/docs/reference/api/drafts#list-drafts-in-pod-1/index.html) [Create Draft in Pod](/content/docs/reference/api/drafts#create-draft-in-pod/index.html) [Get Draft in Pod](/content/docs/reference/api/drafts#get-draft-in-pod-1/index.html) [Update Draft in Pod](/content/docs/reference/api/drafts#update-draft-in-pod/index.html) [Delete Draft in Pod](/content/docs/reference/api/drafts#delete-draft-in-pod/index.html) [Download Draft Attachment in Pod](/content/docs/reference/api/drafts#download-draft-attachment-in-pod/index.html) [Send Draft in Pod](/content/docs/reference/api/drafts#send-draft-in-pod/index.html)

100% readTop