drafts · MachineMail Docs

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

Command	Summary
`drafts create`	Create draft
`drafts delete`	Delete draft
`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.

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 (deployment default; MachineMail staff can change it, and the error message states the cap in force): —to, —cc and —bcc together, each address counted once. An unclaimed sandbox inbox can have at most 5 (deployment default). 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

<inbox-id>stringRequired

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

Flags

--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. null clears the value.

--client-id <id>string

Idempotency key: a create with a --client-id already used in the organization returns that draft with 200.

-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
machinemail drafts create agent@machinemail.dev --send-at null   # clears send-at

API

drafts delete

Delete draft.

Also: machinemail drafts rm.

Requires the draft_delete permission.

shell

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

Arguments

<inbox-id>stringRequired

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

<draft-id>stringRequired

ID of the draft.

Flags

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

API

drafts get

Get draft.

Requires the draft_read permission.

shell

machinemail drafts get <draft-id> [flags]

Arguments

<draft-id>stringRequired

ID of the draft.

Flags

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

API

GET /v0/drafts/{draft_id}
GET /v0/inboxes/{inbox_id}/drafts/{draft_id} with --inbox
GET /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.

shell

machinemail drafts list [flags]

Flags

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

Default50

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

--ascendingboolean

Sort oldest first.

--allboolean

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'

API

GET /v0/drafts
GET /v0/inboxes/{inbox_id}/drafts with --inbox
GET /v0/pods/{pod_id}/drafts 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; 501 when the deployment has no email transport.

A message can have at most 50 recipients (deployment default; MachineMail staff can change it, and the error message states the cap in force): to, cc and bcc together, each address counted once. An unclaimed sandbox inbox can have at most 5 (deployment default). More is a 400 validation error with param: “to”.

An unclaimed sandbox agent can send a limited number of messages to a limited number of different recipients per rolling 24 hours (deployment defaults 10 and 10): 429 with Retry-After.

Requires the draft_send permission.

shell

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

Arguments

<inbox-id>stringRequired

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

<draft-id>stringRequired

ID of the draft.

Flags

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

API

drafts update

Update draft.

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

Requires the draft_update permission.

shell

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

Arguments

<inbox-id>stringRequired

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

<draft-id>stringRequired

ID of the draft.

Flags

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