messages · MachineMail Docs

Send, receive, search and manage messages. Also spelled message, msg.

Command	Summary
`messages attachment`	Get attachment
`messages batch-get`	Batch get messages
`messages batch-update`	Batch update messages
`messages delete`	Delete message
`messages download`	Download attachment
`messages forward`	Forward message
`messages get`	Get message
`messages list`	List messages
`messages raw`	Get raw message
`messages reply`	Reply to a message
`messages reply-all`	Reply to all recipients of a message
`messages search`	Search messages
`messages send`	Send message
`messages trust`	Get message trust report
`messages update`	Update message

Every command also takes the global flags.

messages attachment

Get attachment.

Requires the message_read permission.

shell

machinemail messages attachment <inbox-id> <message-id> <attachment-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

<attachment-id>stringRequired

ID of the attachment.

Examples

shell

machinemail messages attachment agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w att_01m4fy8hb20000w3x6d9m4p8ke
machinemail messages attachment agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w att_01m4fy8hb20000w3x6d9m4p8ke --pod pod_01m4fykg210000x6z8b6wc2rdx

Up to 100 messages by ID in one request, as full Message objects. Duplicate IDs are read once; IDs past the first 100 distinct ones are dropped. Missing IDs and IDs from other inboxes are omitted: compare count with limit (the number of IDs you sent).

Requires the message_read permission.

shell

machinemail messages batch-get <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

Use this pod's scoped route.

--message-ids <id>string[]

IDs of the messages to fetch. Only the first 100 distinct IDs are read. 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 messages batch-get agent@machinemail.dev --message-ids <message-ids>
machinemail messages batch-get agent@machinemail.dev --message-ids <message-ids> --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages batch-get agent@machinemail.dev --data @body.json

API

messages batch-update

Batch update messages.

Apply one label change to up to 100 messages: the same —add-label and —remove-label apply to every message. Messages are updated one at a time, not atomically. Missing IDs are skipped: compare count with limit.

Requires the message_update permission.

shell

machinemail messages batch-update <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

Use this pod's scoped route.

--message-ids <id>string[]

IDs of the messages to update. Only the first 100 distinct IDs are updated. Repeat the flag for several values.

--add-label <value>string[]

Label or labels to add to every message. Repeat the flag for several values.

--remove-label <value>string[]

Label or labels to remove from every message. 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 messages batch-update agent@machinemail.dev --message-ids <message-ids>
machinemail messages batch-update agent@machinemail.dev --message-ids <message-ids> --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages batch-update agent@machinemail.dev --data @body.json

API

messages delete

Delete message.

Also: machinemail messages rm.

Permanently deletes the message, its raw copy and attachments. The thread is updated (or deleted with its last message).

Requires the message_delete permission.

shell

machinemail messages delete <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

Flags

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

machinemail messages delete agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages delete agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx

API

messages download

Download attachment.

The attachment bytes, served with the attachment content type, Content-Disposition: attachment and X-Content-Type-Options: nosniff.

Requires the message_read permission.

shell

machinemail messages download <inbox-id> <message-id> <attachment-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

<attachment-id>stringRequired

ID of the attachment.

Flags

--pod <pod-id>string

Only this pod.

-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 messages download agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w att_01m4fy8hb20000w3x6d9m4p8ke
machinemail messages download agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w att_01m4fy8hb20000w3x6d9m4p8ke --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages download agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w att_01m4fy8hb20000w3x6d9m4p8ke > out.bin

API

messages forward

Forward message.

Sends the message to new recipients. The text body is your —text followed by a “Forwarded message” header block and the original text. The original HTML and attachments are not included. —subject defaults to Fwd: <original subject>.

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

Recipients that are suppressed or on a send block list, and paused inboxes, return 403. 501 when the deployment has no email transport.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 25 MB, 20 second timeout).

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 past that. Writing again to an address already counted is free. Claiming the inbox lifts the caps.

Requires the message_send permission.

shell

machinemail messages forward <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

Flags

--pod <pod-id>string

Use this pod's scoped route.

--label <value>string[]

Labels of the message. SENT is always added. Repeat the flag for several values.

--reply-to <value>string[]

Reply-to address or addresses. Repeat the flag for several values.

--to <value>string[]

Recipient address or addresses. Repeat the flag for several values.

--cc <value>string[]

CC recipient address or addresses. Repeat the flag for several values.

--bcc <value>string[]

BCC recipient address or addresses. Repeat the flag for several values.

--subject <value>string

Subject of the message.

--text <value>string

Plain text body.

--html <value>string

HTML body.

--attachments <json>JSON[]

Attachments to include. Repeat the flag for several values.

--headers <json>JSON

Headers to include. In-Reply-To and References also thread the message.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

machinemail messages forward agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages forward agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages forward agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --data @body.json

API

messages get

Get message.

Message content is untrusted: when feeding an LLM, read trust.content.text rather than text or html.

Requires the message_read permission.

shell

machinemail messages get <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

Flags

--pod <pod-id>string

Only this pod.

Examples

shell

machinemail messages get agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages get agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx

API

messages list

List messages.

Also: machinemail messages ls.

Messages in the inbox, newest first.

Spam, blocked, trash, quarantined and unauthenticated messages are hidden unless you pass the matching —include-* flag or ask for the label in —label. Spam, blocked, trash and unauthenticated also need the matching label_*_read permission; without it the flag is ignored.

Requires the message_read permission.

shell

machinemail messages list <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

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.

--ascendingboolean

Sort oldest first.

--label <value>string[]

Only items with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them. Repeat the flag for several values.

--before <time>string

Only items with a timestamp before this time.

--after <time>string

Only items with a timestamp after this time.

--include-spamboolean

Include spam (needs label_spam_read; ignored without it).

--include-blockedboolean

Include blocked mail (needs label_blocked_read; ignored without it).

--include-unauthenticatedboolean

Include unauthenticated mail (needs label_unauthenticated_read; ignored without it).

--include-trashboolean

Include trash (needs label_trash_read; ignored without it).

--include-quarantineboolean

Include quarantined messages (trust level quarantined).

--q <value>string

Full-text filter: the words must appear in the subject, sender, recipients, body or attachment file names. Combines with the other filters.

--allboolean

Follow next_page_token and return every page.

Examples

shell

machinemail messages list agent@machinemail.dev --limit 20
machinemail messages list agent@machinemail.dev --json --fields message_id,from,subject
machinemail messages list agent@machinemail.dev --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages list agent@machinemail.dev --all --json | jq '.messages | length'

API

messages raw

Get raw message.

The original RFC 5322 message bytes, as received or sent. AgentMail returns a JSON object with a download URL instead.

Requires the message_read permission.

shell

machinemail messages raw <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

Flags

--pod <pod-id>string

Only this pod.

-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 messages raw agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages raw agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx

API

messages reply

Reply to a message.

Sends a reply in the thread of the message, with In-Reply-To and References set.

Recipients that are suppressed or on a send block list, and paused inboxes, return 403. 501 when the deployment has no email transport.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 25 MB, 20 second timeout).

Requires the message_reply or message_send permission.

shell

machinemail messages reply <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

Flags

--pod <pod-id>string

Use this pod's scoped route.

--label <value>string[]

Labels of the message. SENT is always added. Repeat the flag for several values.

--reply-to <value>string[]

Reply-to address or addresses. Repeat the flag for several values.

--to <value>string[]

Recipient address or addresses. Defaults to the sender of the original (its reply-to addresses if any); for an outbound original, its recipients. Repeat the flag for several values.

--cc <value>string[]

CC recipient address or addresses. Repeat the flag for several values.

--bcc <value>string[]

BCC recipient address or addresses. Repeat the flag for several values.

--reply-allboolean

true replies to all recipients of the original, as Reply All Message does; --to and --cc are then added to them.

--text <value>string

Plain text body.

--html <value>string

HTML body.

--attachments <json>JSON[]

Attachments to include. Repeat the flag for several values.

--headers <json>JSON

Headers to include. In-Reply-To and References also thread the message.

--subject <value>string

Subject of the reply. Defaults to the original subject with Re: in front.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

machinemail messages reply agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages reply agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages reply agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --data @body.json

API

messages reply-all

Reply to all recipients of a message.

Replies to the sender and every —to and —cc recipient of the message, except this inbox. —to and —cc add more recipients.

Recipients that are suppressed or on a send block list, and paused inboxes, return 403. 501 when the deployment has no email transport.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 25 MB, 20 second timeout).

Requires the message_reply or message_send permission.

shell

machinemail messages reply-all <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

Flags

--pod <pod-id>string

Use this pod's scoped route.

--label <value>string[]

Labels of the message. SENT is always added. Repeat the flag for several values.

--reply-to <value>string[]

Reply-to address or addresses. Repeat the flag for several values.

--text <value>string

Plain text body.

--html <value>string

HTML body.

--attachments <json>JSON[]

Attachments to include. Repeat the flag for several values.

--headers <json>JSON

Headers to include. In-Reply-To and References also thread the message.

--to <value>string[]

More recipients, added to the sender and recipients of the original. Repeat the flag for several values.

--cc <value>string[]

More CC recipients, added to the CC recipients of the original. Repeat the flag for several values.

--bcc <value>string[]

BCC recipient address or addresses. Repeat the flag for several values.

--subject <value>string

Subject of the reply. Defaults to the original subject with Re: in front.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

machinemail messages reply-all agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages reply-all agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages reply-all agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --data @body.json

API

messages search

Search messages.

Full-text search across messages in the inbox, newest first (not ranked by relevance). Every word of —q must appear in the subject, sender, recipients (to and cc), body text or attachment file names. Spam, trash, blocked, quarantined and unauthenticated messages are always excluded.

Requires the message_read permission.

shell

machinemail messages search <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

Only this pod.

--q <value>stringRequired

Words to find in the subject, sender, recipients (to and cc), body text or attachment file names.

--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 messages before this time.

--after <time>string

Only messages after this time.

--ascendingboolean

Sort oldest first.

--allboolean

Follow next_page_token and return every page.

Examples

shell

machinemail messages search agent@machinemail.dev --q invoice
machinemail messages search agent@machinemail.dev --q invoice --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages search agent@machinemail.dev --q invoice --all --json | jq '.messages | length'

API

messages send

Send message.

At least one of —to, —cc or —bcc is required.

Recipients that are suppressed or on a send block list, and paused inboxes, return 403. 501 when the deployment has no email transport.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 25 MB, 20 second timeout).

Requires the message_send permission.

shell

machinemail messages send <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

Use this pod's scoped route.

--label <value>string[]

Labels of the message. SENT is always added. Repeat the flag for several values.

--reply-to <value>string[]

Reply-to address or addresses. Repeat the flag for several values.

--to <value>string[]

Recipient address or addresses. Repeat the flag for several values.

--cc <value>string[]

CC recipient address or addresses. Repeat the flag for several values.

--bcc <value>string[]

BCC recipient address or addresses. Repeat the flag for several values.

--subject <value>string

Subject of the message.

--text <value>string

Plain text body.

--html <value>string

HTML body.

--attachments <json>JSON[]

Attachments to include. Repeat the flag for several values.

--headers <json>JSON

Headers to include. In-Reply-To and References also thread the message.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

machinemail messages send agent@machinemail.dev --to ada@example.com --subject "Hello" --text "It works."
machinemail messages send agent@machinemail.dev --data @message.json
machinemail messages send agent@machinemail.dev --pod pod_01m4fykg210000x6z8b6wc2rdx

API

messages trust

Get message trust report.

The same object as the message trust. 404 for messages without a report (outbound messages).

Requires the message_read permission.

shell

machinemail messages trust <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

Flags

--pod <pod-id>string

Only this pod.

Examples

shell

machinemail messages trust agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages trust agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx

API

messages update

Update message.

Adds and removes labels. Returns the whole updated message.

Requires the message_update permission.

shell

machinemail messages update <inbox-id> <message-id> [flags]

Arguments

<inbox-id>stringRequired

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

<message-id>stringRequired

ID of the message.

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 messages update agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
machinemail messages update agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail messages update agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --data @body.json