## Draft Commands

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

| Command | Summary |
| --- | --- |
| [`drafts create`](/content/docs/cli/commands/drafts#drafts-create/index.html) | Create draft |
| [`drafts delete`](/content/docs/cli/commands/drafts#drafts-delete/index.html) | Delete draft |
| [`drafts download-attachment`](/content/docs/cli/commands/drafts#drafts-download-attachment/index.html) | Download draft attachment |
| [`drafts get`](/content/docs/cli/commands/drafts#drafts-get/index.html) | Get draft |
| [`drafts list`](/content/docs/cli/commands/drafts#drafts-list/index.html) | List drafts |
| [`drafts send`](/content/docs/cli/commands/drafts#drafts-send/index.html) | Send draft |
| [`drafts update`](/content/docs/cli/commands/drafts#drafts-update/index.html) | 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.

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

#### Arguments

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

#### Flags

| Field | 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

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

### `drafts delete`

Delete draft.

Also: `machinemail drafts rm`.

Requires the draft_delete permission.

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

#### Arguments

| Field | 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 | Description |
| --- | --- |
| `--pod <pod-id>` | `string` Use this pod's scoped route. |

#### Examples

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

### `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.

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

#### Arguments

| Field | 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 | 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

```shell
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
```

### `drafts get`

Get draft.

Requires the draft_read permission.

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

#### Arguments

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

#### Flags

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

#### Examples

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

### `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.

```shell
machinemail drafts list [flags]
```

#### Flags

| Field | 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

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

### `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.

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

#### Arguments

#### Flags

| Field | 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

```shell
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
```

### `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.

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

#### Arguments

#### Flags

| Field | 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

```shell
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
```