drafts · MachineMail Docs

Draft Commands

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

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

drafts delete

Delete draft.

Also: machinemail drafts rm.

Requires the draft_delete permission.

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

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.

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
`-o, --output <file dir

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

drafts get

Get draft.

Requires the draft_read permission.

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

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.

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

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.

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

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

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 Description
--pod <pod-id> string Use this pod's scoped route.
--reply-to <value> `string[]
--to <value> `string[]
--cc <value> `string[]
--bcc <value> `string[]
--subject <value> `string
--text <value> `string
--html <value> `string
--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
`-d, --data <json @file

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