---
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](https://machinemail.dev/docs/cli/commands#global-flags).

## 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`](https://machinemail.dev/docs/reference/api/drafts#create-draft)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts`](https://machinemail.dev/docs/reference/api/drafts#create-draft-in-pod) 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}`](https://machinemail.dev/docs/reference/api/drafts#delete-draft)
- [`DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}`](https://machinemail.dev/docs/reference/api/drafts#delete-draft-in-pod) 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`](https://machinemail.dev/docs/reference/api/drafts#download-draft-attachment)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/download`](https://machinemail.dev/docs/reference/api/drafts#download-draft-attachment-in-pod) 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}`](https://machinemail.dev/docs/reference/api/drafts#get-draft)
- [`GET /v0/inboxes/{inbox_id}/drafts/{draft_id}`](https://machinemail.dev/docs/reference/api/drafts#get-draft) with `--inbox`
- [`GET /v0/pods/{pod_id}/drafts/{draft_id}`](https://machinemail.dev/docs/reference/api/drafts#get-draft-in-pod) 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`](https://machinemail.dev/docs/reference/api/drafts#list-drafts)
- [`GET /v0/inboxes/{inbox_id}/drafts`](https://machinemail.dev/docs/reference/api/drafts#list-drafts) with `--inbox`
- [`GET /v0/pods/{pod_id}/drafts`](https://machinemail.dev/docs/reference/api/drafts#list-drafts-in-pod) 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`](https://machinemail.dev/docs/reference/api/drafts#send-draft)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/send`](https://machinemail.dev/docs/reference/api/drafts#send-draft-in-pod) 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

| 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. |
| `--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}`](https://machinemail.dev/docs/reference/api/drafts#update-draft)
- [`PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}`](https://machinemail.dev/docs/reference/api/drafts#update-draft-in-pod) with `--pod`