drafts.md
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 draftscommands: 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 |
Create draft |
drafts delete |
Delete draft |
drafts download-attachment |
Download draft attachment |
drafts get |
Get draft |
drafts list |
List drafts |
drafts send |
Send draft |
drafts update |
Update draft |
Every command also takes the 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.
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` | |
--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 |
Examples
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
drafts delete
Delete draft.
Also: machinemail drafts rm.
Requires the draft_delete permission.
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
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}DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}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.
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` | |
| `-o, --output <file | dir | ->` | string |
Examples
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}/downloadGET /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}/downloadwith--pod
drafts get
Get draft.
Requires the draft_read permission.
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
machinemail drafts get drf_01m4fz2c1q0000a7m2k9x3v8pe
machinemail drafts get drf_01m4fz2c1q0000a7m2k9x3v8pe --inbox agent@machinemail.dev
API
GET /v0/drafts/{draft_id}GET /v0/inboxes/{inbox_id}/drafts/{draft_id}with--inboxGET /v0/pods/{pod_id}/drafts/{draft_id}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.
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
machinemail drafts list
machinemail drafts list --inbox agent@machinemail.dev
machinemail drafts list --all --json | jq '.drafts | length'
API
GET /v0/draftsGET /v0/inboxes/{inbox_id}/draftswith--inboxGET /v0/pods/{pod_id}/draftswith--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.
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 |
Examples
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}/sendPOST /v0/pods/{pod_id}/inboxes/{inbox_id}/drafts/{draft_id}/sendwith--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.
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` | |
--to <value> |
`string[] | null` | |
--cc <value> |
`string[] | null` | |
--bcc <value> |
`string[] | null` | |
--subject <value> |
`string | null` | |
--text <value> |
`string | null` | |
--html <value> |
`string | null` | |
--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` | |
| `-d, --data <json | @file | ->` | string |
Examples
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