messages.md

title: "messages" description: "Send, receive, search and manage messages. The machinemail messages commands: arguments, flags, examples and the API routes they call." canonical: "https://machinemail.dev/docs/cli/commands/messages"

messages

Send, receive, search and manage messages. The machinemail messages commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/messages

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.

machinemail messages attachment <inbox-id> <message-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).
<message-id> string required ID of the message.
<attachment-id> string required ID of the attachment.

Flags

Field Type Description
--pod <pod-id> string Only this pod.

Examples

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

API

messages batch-get

Batch get messages.

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.

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

Examples

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.

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

Arguments

Flags

Field Type Description
--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

Examples

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.

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

Arguments

Field Type Description
<inbox-id> string required ID of the inbox: its email address, as in AgentMail (inbox_id == email).
<message-id> string required ID of the message.

Flags

Field Type Description
--pod <pod-id> string Use this pod's scoped route.

Examples

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, with X-Content-Type-Options: nosniff. By default Content-Disposition: attachment (RFC 6266: an ASCII filename plus the exact name in RFC 5987 filename* when it is not plain ASCII). With disposition=inline, raster images, PDF and plain text are served inline for previews, under a locked-down Content-Security-Policy; every other type (HTML, SVG, XML, scripts, archives…) is still served as a download.

Requires the message_read permission.

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

Arguments

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

Examples

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: . A quarantined message (trust level quarantined or the QUARANTINE label) is not forwarded: 409 conflict with param: "message_id"; a person can review it in the dashboard.

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

Recipients that are suppressed or on a send block list, and paused inboxes, return 403. An unclaimed sandbox inbox sending to a disposable email address returns 403 with code: "disposable_email_not_allowed" and param set to the field holding it (--to, --cc or --bcc). 502 upstream_error when the email provider refuses or fails the send: nothing is sent or stored, and error.message says whether retrying can help.

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

An unclaimed sandbox agent can send at most 10 messages to at most 10 different recipients per rolling 24 hours: 429 with Retry-After past that. Writing again to an address already counted is free. Claiming the inbox lifts the caps.

When MachineMail pauses sending (for the platform, a plan, or this organization because of its bounce or complaint rate), the send returns 403 account_suspended and nothing is sent; an organization limited to replies can still reply in its existing threads. Organizations on the Free plan may be limited to sending to people who emailed them first (403) and to a number of different recipients per rolling 24 hours (429). Messages that look like phishing are held and not sent (403).

Requires the message_send permission.

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

Arguments

Flags

Field Type Description
--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

Examples

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.

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

Arguments

Flags

Field Type Description
--pod <pod-id> string Only this pod.

Examples

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.

machinemail messages list <inbox-id> [flags]

Arguments

Flags

Field Type Description
--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.
--ascending boolean 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-spam boolean Include spam (needs label_spam_read; ignored without it).
--include-blocked boolean Include blocked mail (needs label_blocked_read; ignored without it).
--include-unauthenticated boolean Include unauthenticated mail (needs label_unauthenticated_read; ignored without it).
--include-trash boolean Include trash (needs label_trash_read; ignored without it).
--include-quarantine boolean 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.
--all boolean Follow next_page_token and return every page.

Examples

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.

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

Arguments

Flags

Field Type Description
--pod <pod-id> string Only this pod.
`-o, --output <file dir ->` string

Examples

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.

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

Requires the message_reply or message_send permission.

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

Arguments

Flags

Field Type Description
--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-all boolean 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

Examples

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.

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

Requires the message_reply or message_send permission.

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

Arguments

Flags

Field Type Description
--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

Examples

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.

machinemail messages search <inbox-id> [flags]

Arguments

Flags

Field Type Description
--pod <pod-id> string Only this pod.
--q <value> string required 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. Default: 50.
--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.
--ascending boolean Sort oldest first.
--all boolean Follow next_page_token and return every page.

Examples

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.

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

Requires the message_send permission.

machinemail messages send <inbox-id> [flags]

Arguments

Flags

Examples

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.

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

Arguments

Flags

Field Type Description
--pod <pod-id> string Only this pod.

Examples

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.

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

Arguments

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

API