---
title: "drafts"
description: "Drafts, and sends scheduled for later. The `machinemail drafts` commands: arguments, flags, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands/drafts"
---

# drafts

> Drafts, and sends scheduled for later. The `machinemail drafts` commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/drafts

Drafts, and sends scheduled for later. Also spelled `draft`.

| Command                                                     | Summary                   |
| ----------------------------------------------------------- | ------------------------- |
| [`drafts create`](#drafts-create)                           | Create draft              |
| [`drafts delete`](#drafts-delete)                           | Delete draft              |
| [`drafts download-attachment`](#drafts-download-attachment) | Download draft attachment |
| [`drafts get`](#drafts-get)                                 | Get draft                 |
| [`drafts list`](#drafts-list)                               | List drafts               |
| [`drafts send`](#drafts-send)                               | Send draft                |
| [`drafts update`](#drafts-update)                           | Update draft              |

Every command also takes the [global flags](/content/docs/cli/commands#global-flags/index.html).

## drafts create

Create draft.

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.

Requires the draft_create permission.

```bash
machinemail drafts create <inbox-id> [flags]
```

#### Arguments

| Field        | Type       |      | Description                                          |
| ------------ | ---------- | ---- | ---------------------------------------------------- |
| `<inbox-id>` | `string`   | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). |

#### Flags

| Field                        | Type           |      | Description                                              |
| ---------------------------- | -------------- | ---- | -------------------------------------------------------- |
| `--pod <pod-id>`            | `string`       |      | Create it in this pod.                                   |
| `--label <value>`           | `string[]`     |      | Labels of the draft. Repeat the flag for several values. |
| `--reply-to <value>`        | `string[]`     |      | Reply-to addresses: one address or a list. Repeat the flag for several values. |
| `--to <value>`              | `string[]`     |      | Recipient addresses: one address or a list. Repeat the flag for several values. |
| `--cc <value>`              | `string[]`     |      | CC addresses: one address or a list. Repeat the flag for several values. |
| `--bcc <value>`             | `string[]`     |      | BCC addresses: one address or a list. Repeat the flag for several values. |
| `--subject <value>`         | `string`       |      | Subject.                                                |
| `--text <value>`            | `string`       |      | Plain text body.                                       |
| `--html <value>`            | `string`       |      | HTML body.                                            |
| `--attachments <json>`      | `JSON[]`       |      | Attachments, sent with the draft. Each needs content or url; a url is fetched when the draft is sent. Repeat the flag for several values. |
| `--in-reply-to <value>`     | `string`       |      | ID of a message in this inbox to reply to: the sent message gets its In-Reply-To and References headers. |
| `--send-at <time>`          | `string | null` |      | Schedule the draft: it is sent automatically at this time (send_status: scheduled). null or absent: not scheduled. |
| `--client-id <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. |
| `-d, --data <json|@file|->` | `string`       |      | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail drafts create agent@machinemail.dev
machinemail drafts create agent@machinemail.dev --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail drafts create agent@machinemail.dev --data @body.json
```

#### API

- [`POST /v0/inboxes/{inbox_id}/drafts`](/content/docs/reference/api/drafts#create-draft/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts`](/content/docs/reference/api/drafts#create-draft-in-pod/index.html) with `--pod`

## drafts delete

Delete draft.

Also: `machinemail drafts rm`.

Requires the draft_delete permission.

```bash
machinemail drafts delete <inbox-id> <draft-id> [flags]
```

#### Arguments

| Field        | Type       |      | Description                                                          |
| ------------ | ---------- | ---- | -------------------------------------------------------------------- |
| `<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.                                                    |

#### Flags

| Field                        | Type           |      | Description                                              |
| ---------------------------- | -------------- | ---- | -------------------------------------------------------- |
| `--pod <pod-id>`            | `string`       |      | Use this pod's scoped route.                                   |

#### Examples

```bash
machinemail drafts delete agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe
machinemail drafts delete agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe --pod pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`DELETE /v0/inboxes/{inbox_id}/drafts/{draft_id}`](/content/docs/reference/api/drafts#delete-draft/index.html)
- [`DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}`](/content/docs/reference/api/drafts#delete-draft-in-pod/index.html) with `--pod`

## drafts download-attachment

Download draft attachment.

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.

Requires the draft_read permission.

```bash
machinemail drafts download-attachment <inbox-id> <draft-id> <attachment-id> [flags]
```

#### Arguments

| Field                | Type       |      | Description                                                          |
| --------------------- | ---------- | ---- | -------------------------------------------------------------------- |
| `<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.                                               |

#### Flags

| Field                        | Type           |      | Description                                              |
| ---------------------------- | -------------- | ---- | -------------------------------------------------------- |
| `--pod <pod-id>`            | `string`       |      | Only this pod.                                           |
| `--disposition`             | `attachment | inline` |      | inline previews raster images, PDF and plain text in the browser; every other type downloads regardless. |
| `-o, --output <file|dir|->` | `string`       |      | Write the body to this file (a directory keeps the server's filename; - is stdout) and report the path. |

#### Examples

```bash
machinemail drafts download-attachment agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe att_01m4fy8hb20000w3x6d9m4p8ke
machinemail drafts download-attachment agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe att_01m4fy8hb20000w3x6d9m4p8ke --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail drafts download-attachment agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe att_01m4fy8hb20000w3x6d9m4p8ke > out.bin
```

#### API

- [`GET /v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download`](/content/docs/reference/api/drafts#download-draft-attachment/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download`](/content/docs/reference/api/drafts#download-draft-attachment-in-pod/index.html) with `--pod`

## drafts get

Get draft.

Requires the draft_read permission.

```bash
machinemail drafts get <draft-id> [flags]
```

#### Arguments

| Field                | Type       |      | Description                                         |
| --------------------- | ---------- | ---- | ------------------------------------------------- |
| `<draft-id>`          | `string`   | required | ID of the draft.                                 |

#### Flags

| Field                        | Type           |      | Description                              |
| ----------------------------- | -------------- | ---- | ---------------------------------------- |
| `--inbox <inbox-id>`         | `string`       |      | Only this inbox.                         |
| `--pod <pod-id>`             | `string`       |      | Only this pod.                          |

#### Examples

```bash
machinemail drafts get drf_01m4fz2c1q0000a7m2k9x3v8pe
machinemail drafts get drf_01m4fz2c1q0000a7m2k9x3v8pe --inbox agent@machinemail.dev
```

#### API

- [`GET /v0/drafts/{draft_id}`](/content/docs/reference/api/drafts#get-draft/index.html)
- [`GET /v0/inboxes/{inbox_id}/drafts/{draft_id}`](/content/docs/reference/api/drafts#get-draft/index.html) with `--inbox`
- [`GET /v0/pods/{pod_id}/drafts/{draft_id}`](/content/docs/reference/api/drafts#get-draft-in-pod/index.html) with `--pod`

## drafts list

List drafts.

Also: `machinemail drafts ls`.

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

Requires the draft_read permission.

```bash
machinemail drafts list [flags]
```

#### Flags

| Field                        | Type           |      | Description                                              |
| ----------------------------- | -------------- | ---- | ------------------------------------------------------ |
| `--inbox <inbox-id>`         | `string`       |      | Only this inbox.                                       |
| `--pod <pod-id>`             | `string`       |      | Only this pod.                                         |
| `--limit <n>`                | `integer`      |      | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>`       | `string`       |      | next_page_token from the previous page.               |
| `--before <time>`            | `string`       |      | Only drafts created before this time.                 |
| `--after <time>`             | `string`       |      | Only drafts created after this time.                  |
| `--ascending`                | `boolean`      |      | Sort oldest first.                                    |
| `--all`                      | `boolean`      |      | Follow next_page_token and return every page.         |

#### Examples

```bash
machinemail drafts list
machinemail drafts list --inbox agent@machinemail.dev
machinemail drafts list --all --json | jq '.drafts | length'
```

#### API

- [`GET /v0/drafts`](/content/docs/reference/api/drafts#list-drafts/index.html)
- [`GET /v0/inboxes/{inbox_id}/drafts`](/content/docs/reference/api/drafts#list-drafts/index.html) with `--inbox`
- [`GET /v0/pods/{pod_id}/drafts`](/content/docs/reference/api/drafts#list-drafts-in-pod/index.html) with `--pod`

## drafts send

Send draft.

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-label, minus --remove-label.

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

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".

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

Requires the draft_send permission.

```bash
machinemail drafts send <inbox-id> <draft-id> [flags]
```

#### Arguments

| Field                | Type       |      | Description                                                          |
| --------------------- | ---------- | ---- | -------------------------------------------------------------------- |
| `<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.                                                    |

#### Flags

| Field                        | Type           |      | Description                                              |
| ---------------------------- | -------------- | ---- | -------------------------------------------------------- |
| `--pod <pod-id>`            | `string`       |      | Use this pod's scoped route.                                   |
| `--add-label <value>`       | `string[]`     |      | Label or labels to add. Repeat the flag for several values.       |
| `--remove-label <value>`    | `string[]`     |      | Label or labels to remove. Repeat the flag for several values.     |
| `-d, --data <json|@file|->` | `string`       |      | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail drafts send agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe
machinemail drafts send agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail drafts send agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe --data @body.json
```

#### API

- [`POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send`](/content/docs/reference/api/drafts#send-draft/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/send`](/content/docs/reference/api/drafts#send-draft-in-pod/index.html) with `--pod`

## drafts update

Update draft.

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".

Requires the draft_update permission.

```bash
machinemail drafts update <inbox-id> <draft-id> [flags]
```

#### Arguments

#### Flags

| Field                        | Type           |      | Description                                              |
| ---------------------------- | -------------- | ---- | -------------------------------------------------------- |
| `--pod <pod-id>`            | `string`       |      | Use this pod's scoped route.                                   |
| `--reply-to <value>`        | `string[] | null` |      | Reply-to addresses. null clears them. Repeat the flag for several values. null clears the value. |
| `--to <value>`              | `string[] | null` |      | Recipient addresses. null clears them. Repeat the flag for several values. null clears the value. |
| `--cc <value>`              | `string[] | null` |      | CC addresses. null clears them. Repeat the flag for several values. null clears the value. |
| `--bcc <value>`             | `string[] | null` |      | BCC addresses. null clears them. Repeat the flag for several values. null clears the value. |
| `--subject <value>`         | `string | null` |      | Subject. null clears it. null clears the value.                 |
| `--text <value>`            | `string | null` |      | Plain text body. null clears it. null clears the value.         |
| `--html <value>`            | `string | null` |      | HTML body. null clears it. null clears the value.              |
| `--add-attachments <json>`  | `JSON[]`       |      | Attachments to add. Each needs content or url. Repeat the flag for several values. |
| `--remove-attachments <value>` | `string[]`   |      | IDs of attachments to remove. Unknown IDs are ignored. Repeat the flag for several values. |
| `--add-label <value>`       | `string[]`     |      | Labels to add. Repeat the flag for several values.               |
| `--remove-label <value>`    | `string[]`     |      | Labels to remove (applied after --add-label). Repeat the flag for several values. |
| `--send-at <time>`          | `string | null` |      | Schedule (or reschedule) the draft. null unschedules it. null clears the value. |
| `-d, --data <json|@file|->` | `string`       |      | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail drafts update agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe
machinemail drafts update agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail drafts update agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe --data @body.json
machinemail drafts update agent@machinemail.dev drf_01m4fz2c1q0000a7m2k9x3v8pe --reply-to null   # clears reply-to
```

#### API

- [`PATCH /v0/inboxes/{inbox_id}/drafts/{draft_id}`](/content/docs/reference/api/drafts#update-draft/index.html)
- [`PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}`](/content/docs/reference/api/drafts#update-draft-in-pod/index.html) with `--pod`