# Messages Commands

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

| Command | Summary |
| --- | --- |
| [`messages attachment`](/content/docs/cli/commands/messages#messages-attachment/index.html) | Get attachment |
| [`messages batch-get`](/content/docs/cli/commands/messages#messages-batch-get/index.html) | Batch get messages |
| [`messages batch-update`](/content/docs/cli/commands/messages#messages-batch-update/index.html) | Batch update messages |
| [`messages delete`](/content/docs/cli/commands/messages#messages-delete/index.html) | Delete message |
| [`messages download`](/content/docs/cli/commands/messages#messages-download/index.html) | Download attachment |
| [`messages forward`](/content/docs/cli/commands/messages#messages-forward/index.html) | Forward message |
| [`messages get`](/content/docs/cli/commands/messages#messages-get/index.html) | Get message |
| [`messages list`](/content/docs/cli/commands/messages#messages-list/index.html) | List messages |
| [`messages raw`](/content/docs/cli/commands/messages#messages-raw/index.html) | Get raw message |
| [`messages reply`](/content/docs/cli/commands/messages#messages-reply/index.html) | Reply to a message |
| [`messages reply-all`](/content/docs/cli/commands/messages#messages-reply-all/index.html) | Reply to all recipients of a message |
| [`messages search`](/content/docs/cli/commands/messages#messages-search/index.html) | Search messages |
| [`messages send`](/content/docs/cli/commands/messages#messages-send/index.html) | Send message |
| [`messages trust`](/content/docs/cli/commands/messages#messages-trust/index.html) | Get message trust report |
| [`messages update`](/content/docs/cli/commands/messages#messages-update/index.html) | Update message |

---

### Messages Attachment

Get attachment.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages attachment <inbox-id> <message-id> <attachment-id> [flags]
```

#### Arguments
| Field | 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 | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Only this pod. |

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

### API
- [`GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`](/content/docs/reference/api/messages#get-attachment/index.html)  
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`](/content/docs/reference/api/messages#get-attachment-in-pod/index.html) 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.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages batch-get <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`; Use this pod's scoped route. |
| `--message-ids <id>` | `string[]`; IDs of the messages to fetch. Only the first 100 distinct IDs are read. |
| `-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 --data @body.json
```

### API
- [`POST /v0/inboxes/{inbox_id}/messages/batch-get`](/content/docs/reference/api/messages#batch-get-messages/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-get`](/content/docs/reference/api/messages#batch-get-messages-in-pod/index.html) with `--pod`

---

### Messages Batch-Update

Batch update messages.

Apply one label change to up to 100 messages. Missing IDs are skipped.

Requires the `message_update` permission.

#### Shell Command
```shell
machinemail messages batch-update <inbox-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Use this pod's scoped route. |
| `--message-ids <id>` | `string[]`; IDs of the messages to update. |
| `--add-label <value>` | `string[]`; Label or labels to add. |
| `--remove-label <value>` | `string[]`; Label or labels to remove. |
| `-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 --data @body.json
```

### API
- [`POST /v0/inboxes/{inbox_id}/messages/batch-update`](/content/docs/reference/api/messages#batch-update-messages/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-update`](/content/docs/reference/api/messages#batch-update-messages-in-pod/index.html) with `--pod`

---

### Messages Delete

Delete message.

Permanently deletes the message, its raw copy, and attachments.

Requires the `message_delete` permission.

#### Shell Command
```shell
machinemail messages delete <inbox-id> <message-id> [flags]
```

#### Arguments
| Field | 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 | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Use this pod's scoped route. |

#### Examples
```shell
machinemail messages delete agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
```

### API
- [`DELETE /v0/inboxes/{inbox_id}/messages/{message_id}`](/content/docs/reference/api/messages#delete-message/index.html)
- [`DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`](/content/docs/reference/api/messages#delete-message-in-pod/index.html) with `--pod`

---

### Messages Download

Download attachment.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages download <inbox-id> <message-id> <attachment-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Only this pod. |
| `--disposition` | `attachment | inline`; Define how to serve the attachment. |
| `-o, --output <file|dir|->` | `string`; Write the body to this file. |

#### Examples
```shell
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`](/content/docs/reference/api/messages#download-attachment/index.html)  
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download`](/content/docs/reference/api/messages#download-attachment-in-pod/index.html) with `--pod`

---

### Messages Forward

Forward message.

Requires the `message_send` permission.

#### Shell Command
```shell
machinemail messages forward <inbox-id> <message-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Use this pod's scoped route. |
| `--to <value>` | `string[]`; Recipient address. Repeat the flag for several values. |
| `--subject <value>` | `string`; Subject of the message. |
| `--text <value>` | `string`; Plain text body. |
| `--html <value>` | `string`; HTML body. |
| `-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 --to recipient@example.com
```

### API
- [`POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward`](/content/docs/reference/api/messages#forward-message/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/forward`](/content/docs/reference/api/messages#forward-message-in-pod/index.html) with `--pod`

---

### Messages Get

Get message.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages get <inbox-id> <message-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Only this pod. |

#### Examples
```shell
machinemail messages get agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
```

### API
- [`GET /v0/inboxes/{inbox_id}/messages/{message_id}`](/content/docs/reference/api/messages#get-message/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`](/content/docs/reference/api/messages#get-message-in-pod/index.html) with `--pod`

---

### Messages List

List messages.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages list <inbox-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Only this pod. |
| `--limit <n>` | `integer`; Maximum number of items to return. Default 50. |
| `--sort <value>` | `string`; Sort order. |

#### Examples
```shell
machinemail messages list agent@machinemail.dev --limit 20
```

### API
- [`GET /v0/inboxes/{inbox_id}/messages`](/content/docs/reference/api/messages#list-messages/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages`](/content/docs/reference/api/messages#list-messages-in-pod/index.html) with `--pod`

---

### Messages Raw

Get raw message.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages raw <inbox-id> <message-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Only this pod. |

#### Examples
```shell
machinemail messages raw agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
```

### API
- [`GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw`](/content/docs/reference/api/messages#get-raw-message/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/raw`](/content/docs/reference/api/messages#get-raw-message-in-pod/index.html) with `--pod`

---

### Messages Reply

Reply to a message.

Requires the `message_reply` or `message_send` permission.

#### Shell Command
```shell
machinemail messages reply <inbox-id> <message-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Use this pod's scoped route. |
| `--to <value>` | `string[]`; Recipient address. Repeat the flag. |
| `--text <value>` | `string`; Plain text body. |
| `--html <value>` | `string`; HTML body. |
| `-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 --to sender@example.com
```

### API
- [`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply`](/content/docs/reference/api/messages/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply`](/content/docs/reference/api/messages#reply-to-message-in-pod/index.html) with `--pod`

---

### Messages Reply-All

Reply to all recipients of a message.

Requires the `message_reply` or `message_send` permission.

#### Shell Command
```shell
machinemail messages reply-all <inbox-id> <message-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Use this pod's scoped route. |
| `--to <value>` | `string[]`; More recipients. Repeat the flag. |
| `--text <value>` | `string`; Plain text body. |
| `--html <value>` | `string`; HTML body. |
| `-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
```

### API
- [`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all`](/content/docs/reference/api/messages/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply-all`](/content/docs/reference/api/messages#reply-all-message-in-pod/index.html) with `--pod`

---

### Messages Search

Search messages.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages search <inbox-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Only this pod. |
| `--q <value>` | `string` Required; Words to find in the messages. |
| `--limit <n>` | `integer`; Maximum number of items to return. Default 50. |

#### Examples
```shell
machinemail messages search agent@machinemail.dev --q invoice
```

### API
- [`GET /v0/inboxes/{inbox_id}/messages/search`](/content/docs/reference/api/messages#search-messages/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/search`](/content/docs/reference/api/messages#search-messages-in-pod/index.html) with `--pod`

---

### Messages Send

Send message.

Requires the `message_send` permission.

#### Shell Command
```shell
machinemail messages send <inbox-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Use this pod's scoped route. |
| `--to <value>` | `string[]`; 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. |
| `-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."
```

### API
- [`POST /v0/inboxes/{inbox_id}/messages/send`](/content/docs/reference/api/messages#send-message/index.html)
- [`POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/send`](/content/docs/reference/api/messages#send-message-in-pod/index.html) with `--pod`

---

### Messages Trust

Get message trust report.

Requires the `message_read` permission.

#### Shell Command
```shell
machinemail messages trust <inbox-id> <message-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Only this pod. |

#### Examples
```shell
machinemail messages trust agent@machinemail.dev msg_01m4fy8han0000y3ge3m73vw3w
```

### API
- [`GET /v0/inboxes/{inbox_id}/messages/{message_id}/trust`](/content/docs/reference/api/trust#get-message-trust-report/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/trust`](/content/docs/reference/api/trust#get-message-trust-report-in-pod/index.html) with `--pod`

---

### Messages Update

Update message.

Requires the `message_update` permission.

#### Shell Command
```shell
machinemail messages update <inbox-id> <message-id> [flags]
```

#### Flags
| Field | Description |
| --- | --- |
| `--pod <pod-id>` | `string`; Use this pod's scoped route. |
| `--add-label <value>` | `string[]`; Label or labels to add. |
| `--remove-label <value>` | `string[]`; Label or labels to remove. |
| `-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
```

### API
- [`PATCH /v0/inboxes/{inbox_id}/messages/{message_id}`](/content/docs/reference/api/messages#update-message/index.html)
- [`PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`](/content/docs/reference/api/messages#update-message-in-pod/index.html) with `--pod`