--- 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`](#messages-attachment) | Get attachment | | [`messages batch-get`](#messages-batch-get) | Batch get messages | | [`messages batch-update`](#messages-batch-update) | Batch update messages | | [`messages delete`](#messages-delete) | Delete message | | [`messages download`](#messages-download) | Download attachment | | [`messages forward`](#messages-forward) | Forward message | | [`messages get`](#messages-get) | Get message | | [`messages list`](#messages-list) | List messages | | [`messages raw`](#messages-raw) | Get raw message | | [`messages reply`](#messages-reply) | Reply to a message | | [`messages reply-all`](#messages-reply-all) | Reply to all recipients of a message | | [`messages search`](#messages-search) | Search messages | | [`messages send`](#messages-send) | Send message | | [`messages trust`](#messages-trust) | Get message trust report | | [`messages update`](#messages-update) | Update message | Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags). ## messages attachment Get attachment. Requires the message\_read permission. ```bash machinemail messages attachment [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | | `` | `string` | required | ID of the message. | | `` | `string` | required | ID of the attachment. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Only this pod. | #### Examples ```bash machinemail messages attachment agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w att_01m4fy8hb20000w3x6d9m4p8ke machinemail messages attachment agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w att_01m4fy8hb20000w3x6d9m4p8ke --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`](https://machinemail.dev/docs/reference/api/messages#get-attachment) - [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`](https://machinemail.dev/docs/reference/api/messages#get-attachment-in-pod) with `--pod` ## 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. ```bash machinemail messages batch-get [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Use this pod's scoped route. | | `--message-ids ` | `string[]` | | IDs of the messages to fetch. Only the first 100 distinct IDs are read. Repeat the flag for several values. | | `-d, --data ` | `string` | | Request body as JSON, @file or - for stdin; field flags override its keys. | #### Examples ```bash machinemail messages batch-get agent@machinemail.dev --message-ids machinemail messages batch-get agent@machinemail.dev --message-ids --pod pod_01m4fykg210000x6z8b6wc2rdx machinemail messages batch-get agent@machinemail.dev --data @body.json ``` #### API - [`POST /v0/inboxes/{inbox_id}/messages/batch-get`](https://machinemail.dev/docs/reference/api/messages#batch-get-messages) - [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-get`](https://machinemail.dev/docs/reference/api/messages#batch-get-messages-in-pod) with `--pod` ## 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. ```bash machinemail messages batch-update [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Use this pod's scoped route. | | `--message-ids ` | `string[]` | | IDs of the messages to update. Only the first 100 distinct IDs are updated. Repeat the flag for several values. | | `--add-label ` | `string[]` | | Label or labels to add to every message. Repeat the flag for several values. | | `--remove-label ` | `string[]` | | Label or labels to remove from every message. Repeat the flag for several values. | | `-d, --data ` | `string` | | Request body as JSON, @file or - for stdin; field flags override its keys. | #### Examples ```bash machinemail messages batch-update agent@machinemail.dev --message-ids machinemail messages batch-update agent@machinemail.dev --message-ids --pod pod_01m4fykg210000x6z8b6wc2rdx machinemail messages batch-update agent@machinemail.dev --data @body.json ``` #### API - [`POST /v0/inboxes/{inbox_id}/messages/batch-update`](https://machinemail.dev/docs/reference/api/messages#batch-update-messages) - [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-update`](https://machinemail.dev/docs/reference/api/messages#batch-update-messages-in-pod) with `--pod` ## 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. ```bash machinemail messages delete [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | | `` | `string` | required | ID of the message. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Use this pod's scoped route. | #### Examples ```bash machinemail messages delete agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w machinemail messages delete agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`DELETE /v0/inboxes/{inbox_id}/messages/{message_id}`](https://machinemail.dev/docs/reference/api/messages#delete-message) - [`DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`](https://machinemail.dev/docs/reference/api/messages#delete-message-in-pod) with `--pod` ## 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. ```bash machinemail messages download [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | | `` | `string` | required | ID of the message. | | `` | `string` | required | ID of the attachment. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `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 ` | `string` | | Write the body to this file (a directory keeps the server's filename; - is stdout) and report the path. | #### Examples ```bash 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 - [`GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download`](https://machinemail.dev/docs/reference/api/messages#download-attachment) - [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download`](https://machinemail.dev/docs/reference/api/messages#download-attachment-in-pod) with `--pod` ## 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. ```bash machinemail messages forward [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | | `` | `string` | required | ID of the message. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Use this pod's scoped route. | | `--label ` | `string[]` | | Labels of the message. SENT is always added. Repeat the flag for several values. | | `--reply-to ` | `string[]` | | Reply-to address or addresses. Repeat the flag for several values. | | `--to ` | `string[]` | | Recipient address or addresses. Repeat the flag for several values. | | `--cc ` | `string[]` | | CC recipient address or addresses. Repeat the flag for several values. | | `--bcc ` | `string[]` | | BCC recipient address or addresses. Repeat the flag for several values. | | `--subject ` | `string` | | Subject of the message. | | `--text ` | `string` | | Plain text body. | | `--html ` | `string` | | HTML body. | | `--attachments ` | `JSON[]` | | Attachments to include. Repeat the flag for several values. | | `--headers ` | `JSON` | | Headers to include. In-Reply-To and References also thread the message. | | `-d, --data ` | `string` | | Request body as JSON, @file or - for stdin; field flags override its keys. | #### Examples ```bash 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 - [`POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward`](https://machinemail.dev/docs/reference/api/messages#forward-message) - [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/forward`](https://machinemail.dev/docs/reference/api/messages#forward-message-in-pod) with `--pod` ## 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. ```bash machinemail messages get [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | | `` | `string` | required | ID of the message. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Only this pod. | #### Examples ```bash machinemail messages get agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w machinemail messages get agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`GET /v0/inboxes/{inbox_id}/messages/{message_id}`](https://machinemail.dev/docs/reference/api/messages#get-message) - [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`](https://machinemail.dev/docs/reference/api/messages#get-message-in-pod) with `--pod` ## 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. ```bash machinemail messages list [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Only this pod. | | `--limit ` | `integer` | | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. | | `--page-token ` | `string` | | next_page_token from the previous page. | | `--ascending` | `boolean` | | Sort oldest first. | | `--label ` | `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