[Skip to content](/content/docs/reference/api/messages#nd-page/index.html) [Skip to content](/content/docs/reference/api/messages#nd-page/index.html)

\[01/28\]List Messages

| Method | Path | Summary |
| --- | --- | --- |
| `GET` | `/v0/inboxes/{inbox_id}/messages` | [List Messages](/content/docs/reference/api/messages#list-messages/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/messages/batch-get` | [Batch Get Messages](/content/docs/reference/api/messages#batch-get-messages/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/messages/batch-update` | [Batch Update Messages](/content/docs/reference/api/messages#batch-update-messages/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/messages/search` | [Search Messages](/content/docs/reference/api/messages#search-messages/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/messages/send` | [Send Message](/content/docs/reference/api/messages#send-message/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/messages/{message_id}` | [Get Message](/content/docs/reference/api/messages#get-message/index.html) |
| `PATCH` | `/v0/inboxes/{inbox_id}/messages/{message_id}` | [Update Message](/content/docs/reference/api/messages#update-message/index.html) |
| `DELETE` | `/v0/inboxes/{inbox_id}/messages/{message_id}` | [Delete Message](/content/docs/reference/api/messages#delete-message/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}` | [Get Attachment](/content/docs/reference/api/messages#get-attachment/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download` | [Download Attachment](/content/docs/reference/api/messages#download-attachment/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/messages/{message_id}/forward` | [Forward Message](/content/docs/reference/api/messages#forward-message/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/messages/{message_id}/raw` | [Get Raw Message](/content/docs/reference/api/messages#get-raw-message/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/messages/{message_id}/reply` | [Reply To Message](/content/docs/reference/api/messages#reply-to-message/index.html) |
| `POST` | `/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all` | [Reply All Message](/content/docs/reference/api/messages#reply-all-message/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages` | [List Messages in Pod](/content/docs/reference/api/messages#list-messages-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-get` | [Batch Get Messages in Pod](/content/docs/reference/api/messages#batch-get-messages-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-update` | [Batch Update Messages in Pod](/content/docs/reference/api/messages#batch-update-messages-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/search` | [Search Messages in Pod](/content/docs/reference/api/messages#search-messages-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/send` | [Send Message in Pod](/content/docs/reference/api/messages#send-message-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}` | [Get Message in Pod](/content/docs/reference/api/messages#get-message-in-pod/index.html) |
| `PATCH` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}` | [Update Message in Pod](/content/docs/reference/api/messages#update-message-in-pod/index.html) |
| `DELETE` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}` | [Delete Message in Pod](/content/docs/reference/api/messages#delete-message-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}` | [Get Attachment in Pod](/content/docs/reference/api/messages#get-attachment-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download` | [Download Attachment in Pod](/content/docs/reference/api/messages#download-attachment-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/forward` | [Forward Message in Pod](/content/docs/reference/api/messages#forward-message-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/raw` | [Get Raw Message in Pod](/content/docs/reference/api/messages#get-raw-message-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply` | [Reply To Message in Pod](/content/docs/reference/api/messages#reply-to-message-in-pod/index.html) |
| `POST` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply-all` | [Reply All Message in Pod](/content/docs/reference/api/messages#reply-all-message-in-pod/index.html) |

## [List Messages](/content/docs/reference/api/messages\#list-messages/index.html)

http

```
GET /v0/inboxes/{inbox_id}/messages
```

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 `labels`. Spam, blocked, trash and unauthenticated also need the matching `label_*_read` permission; without it the flag is ignored.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters/index.html)

FieldDescription

`inbox_id``string`Required

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

#### [Query parameters](/content/docs/reference/api/messages\#query-parameters/index.html)

FieldDescription

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`ascending``boolean`

Sort oldest first.

`labels``string[]`

Only items with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them.

`before``string (date-time)`

Only items with a timestamp before this time.

`after``string (date-time)`

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

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

#### [Response](/content/docs/reference/api/messages\#response/index.html)

**200** A page of messages (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`messages` [MessageItem\[\]](/content/docs/reference/api/objects#messageitem/index.html) Required

Ordered by timestamp, newest first unless ascending is set.

Each item of `messages` is a [MessageItem](/content/docs/reference/api/objects#messageitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

SPF, DKIM and DMARC verdicts for a received message, each with the domain it is about, as recorded when the message reached MachineMail: by the receiving mail provider (for example Amazon SES), or by the Authentication-Results header of the server that delivered it to MachineMail. A mechanism that was not evaluated is absent. The whole field is absent on sent messages, on messages injected through POST /inbound/raw (their headers are not believed), when nothing was evaluated, and on messages received before the field was introduced. As in AgentMail, only verdicts that speak for the sender are kept. spf is present only when spf\_domain is aligned with the sender (shares an organizational domain with the From domain, or with the Sender domain when From spans several domains): an unaligned SPF result is withheld whatever its value. dkim and dmarc are withheld when From spans more than one domain or could not be parsed. Unlike the trust report (trust.authentication), which collapses each result to the values MachineMail scores on and adds aligned, these are the uncollapsed results: permerror and temperror stay as they are. dkim\_domain is the signing domain as written: compare it with the From domain before treating a DKIM pass as proof of the sender, and use trust.level (or the UNAUTHENTICATED label) to decide whether to act on the message. Do not reject mail on dmarc: fail alone: forwarding breaks it.

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

#### [Errors](/content/docs/reference/api/messages\#errors/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "messages": [\
    {\
      "inbox_id": "agent@machinemail.dev",\
      "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"],\
      "timestamp": "2026-10-01T12:00:00.000Z",\
      "from": "Support Agent <agent@machinemail.dev>",\
      "to": ["customer@example.com"],\
      "cc": ["team@example.com"],\
      "bcc": ["audit@example.com"],\
      "subject": "Order #1042",\
      "preview": "Thanks for the quick reply.",\
      "attachments": [\
        {\
          "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
          "filename": "invoice.pdf",\
          "size": 2048,\
          "content_type": "application/pdf",\
          "content_disposition": "string",\
          "content_id": "string"\
        }\
      ],\
      "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "references": ["string"],\
      "headers": {\
        "key": "value"\
      },\
      "authentication_results": {\
        "spf": "pass",\
        "dkim": "pass",\
        "dmarc": "pass",\
        "spf_domain": "string",\
        "dkim_domain": "string",\
        "dmarc_domain": "string",\
        "arc_sealer": "string"\
      },\
      "size": 2048,\
      "updated_at": "2026-10-01T12:00:00.000Z",\
      "created_at": "2026-10-01T12:00:00.000Z",\
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\
      "direction": "inbound",\
      "delivery_status": "sent",\
      "trust_level": "verified"\
    }\
  ]
}
```

## [Batch Get Messages](/content/docs/reference/api/messages\#batch-get-messages/index.html)

http

```
POST /v0/inboxes/{inbox_id}/messages/batch-get
```

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-1/index.html)

FieldDescription

`inbox_id``string`Required

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

#### [Request body](/content/docs/reference/api/messages\#request-body/index.html)

Content type: `application/json`.

FieldDescription

`message_ids``string[]`Required

IDs of the messages to fetch. Only the first 100 distinct IDs are read.

#### [Response](/content/docs/reference/api/messages\#response-1/index.html)

**200** The messages found (`application/json`)

FieldDescription

`limit``integer`Required

Number of IDs in the request.

`count``integer`Required

Number of messages returned.

`messages` [Message\[\]](/content/docs/reference/api/objects#message/index.html) Required

Found messages, in request order. IDs not found in the inbox are omitted.

Each item of `messages` is a [Message](/content/docs/reference/api/objects#message/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

`reply_to``string[]`

Reply-to addresses. In format username@domain.com or Display Name <username@domain.com>.

`text``string`

Plain text body. Untrusted: agents should read trust.content.text or extracted\_text.

`html``string`

HTML body. Untrusted.

`extracted_text``string`

New text content, without quoted replies.

`extracted_html``string`

New HTML content, without quoted replies.

`received_via``"raw"`

raw when the message was injected with POST /inbound/raw (authentication not verified).

`held_at``string (date-time)`

When the message arrived, for inbound mail that was held because the organization reached a Free plan limit. created\_at is then when it was delivered (released).

`trust` [TrustReport](/content/docs/reference/api/objects#trustreport/index.html)

Trust report of an inbound message.

#### [Errors](/content/docs/reference/api/messages\#errors-1/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-1/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/batch-get" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ]
}'
```

Response 200

```
{
  "limit": 50,
  "count": 1,
  "messages": [\
    {\
      "inbox_id": "agent@machinemail.dev",\
      "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"],\
      "timestamp": "2026-10-01T12:00:00.000Z",\
      "from": "Support Agent <agent@machinemail.dev>",\
      "to": ["customer@example.com"],\
      "cc": ["team@example.com"],\
      "bcc": ["audit@example.com"],\
      "subject": "Order #1042",\
      "preview": "Thanks for the quick reply.",\
      "attachments": [\
        {\
          "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
          "filename": "invoice.pdf",\
          "size": 2048,\
          "content_type": "application/pdf",\
          "content_disposition": "string",\
          "content_id": "string"\
        }\
      ],\
      "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "references": ["string"],\
      "headers": {\
        "key": "value"\
      },\
      "authentication_results": {\
        "spf": "pass",\
        "dkim": "pass",\
        "dmarc": "pass",\
        "spf_domain": "string",\
        "dkim_domain": "string",\
        "dmarc_domain": "string",\
        "arc_sealer": "string"\
      },\
      "size": 2048,\
      "updated_at": "2026-10-01T12:00:00.000Z",\
      "created_at": "2026-10-01T12:00:00.000Z",\
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\
      "direction": "inbound",\
      "delivery_status": "sent",\
      "trust_level": "verified",\
      "reply_to": ["agent@machinemail.dev"],\
      "text": "Thanks for the quick reply.",\
      "html": "<p>Thanks for the quick reply.</p>",\
      "extracted_text": "Thanks for the quick reply.",\
      "extracted_html": "<p>Thanks for the quick reply.</p>",\
      "received_via": "raw",\
      "held_at": "2026-10-01T12:00:00.000Z",\
      "trust": {\
        "level": "verified",\
        "score": 0.8,\
        "basis": "trusted_domain",\
        "authentication": {\
          "spf": "pass",\
          "dkim": "pass",\
          "dmarc": "pass",\
          "aligned": false\
        },\
        "sender": {\
          "address": "agent@machinemail.dev",\
          "domain": "example.com",\
          "prior_correspondence": false,\
          "on_allow_list": false,\
          "on_block_list": false,\
          "free_mail_provider": false,\
          "trusted_domain": {\
            "id": "string",\
            "domain": "example.com",\
            "scope": "org"\
          },\
          "trusted_domain_shadowed_by": "block"\
        },\
        "content": {\
          "text": "Thanks for the quick reply.",\
          "html": "<p>Thanks for the quick reply.</p>",\
          "segments": [{}],\
          "hidden_text_found": false,\
          "zero_width_found": false,\
          "tracking_pixels": 1,\
          "agent_instructions_detected": false,\
          "warnings": ["string"]\
        },\
        "links": [\
          {\
            "href": "string",\
            "text": "Thanks for the quick reply.",\
            "final_url": "https://example.com",\
            "domain": "example.com",\
            "display_mismatch": false,\
            "shortener": false,\
            "suspicious": false,\
            "reasons": []\
          }\
        ],\
        "attachments": [\
          {\
            "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
            "filename": "invoice.pdf",\
            "content_type": "application/pdf",\
            "risk": "low",\
            "reasons": [],\
            "extracted_text": "Thanks for the quick reply."\
          }\
        ],\
        "classification": {\
          "is_spam": 0.8,\
          "is_phishing": 0.8,\
          "contains_instructions_to_agent": 0.8,\
          "requests_credentials_or_payment": 0.8,\
          "urgency": 0.8,\
          "category": "transactional",\
          "language": "string",\
          "backend": "string",\
          "input_hash": "string",\
          "cached": false\
        },\
        "provider_verdicts": {\
          "spam": "pass",\
          "virus": "pass",\
          "source": "string"\
        },\
        "reasons": ["string"],\
        "computed_at": "2026-10-01T12:00:00.000Z"\
      }\
    }\
  ]
}
```

## [Batch Update Messages](/content/docs/reference/api/messages\#batch-update-messages/index.html)

http

```
POST /v0/inboxes/{inbox_id}/messages/batch-update
```

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_update`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-2/index.html)

FieldDescription

`inbox_id``string`Required

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

#### [Request body](/content/docs/reference/api/messages\#request-body-1/index.html)

Content type: `application/json`.

FieldDescription

`message_ids``string[]`Required

IDs of the messages to update. Only the first 100 distinct IDs are updated.

`add_labels``string | string[]`

Label or labels to add to every message.

`remove_labels``string | string[]`

Label or labels to remove from every message.

#### [Response](/content/docs/reference/api/messages\#response-2/index.html)

**200** The updated messages (`application/json`)

FieldDescription

`limit``integer`Required

Number of IDs in the request.

`count``integer`Required

Number of messages updated.

`updates` [UpdateMessageResponse\[\]](/content/docs/reference/api/objects#updatemessageresponse/index.html) Required

Updated messages with their new labels, in request order. IDs not found are omitted.

Each item of `updates` is a [UpdateMessageResponse](/content/docs/reference/api/objects#updatemessageresponse/index.html):

FieldDescription

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message after the update.

#### [Errors](/content/docs/reference/api/messages\#errors-2/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `402` | Free plan: removing SPAM or QUARANTINE makes the message count toward the messages cap and storage from now on, and the organization is over one (limit\_key messages\_per\_month, messages\_per\_day or storage\_bytes). The labels are unchanged. Paid plans are never refused. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `409` | Conflicts with an existing resource. |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-2/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/batch-update" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ],
  "add_labels": "string"
}'
```

Response 200

```
{
  "limit": 50,
  "count": 1,
  "updates": [\
    {\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"]\
    }\
  ]
}
```

## [Search Messages](/content/docs/reference/api/messages\#search-messages/index.html)

http

```
GET /v0/inboxes/{inbox_id}/messages/search
```

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.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-3/index.html)

FieldDescription

`inbox_id``string`Required

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

#### [Query parameters](/content/docs/reference/api/messages\#query-parameters-1/index.html)

FieldDescription

`q``string`Required

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

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`before``string (date-time)`

Only messages before this time.

`after``string (date-time)`

Only messages after this time.

`ascending``boolean`

Sort oldest first.

#### [Response](/content/docs/reference/api/messages\#response-3/index.html)

**200** A page of matching messages (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`messages` [MessageItem\[\]](/content/docs/reference/api/objects#messageitem/index.html) Required

Matching messages, newest first unless ascending is set.

Each item of `messages` is a [MessageItem](/content/docs/reference/api/objects#messageitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

#### [Errors](/content/docs/reference/api/messages\#errors-3/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-3/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/search?q=invoice" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Send Message](/content/docs/reference/api/messages\#send-message/index.html)

http

```
POST /v0/inboxes/{inbox_id}/messages/send
```

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

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`).

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-4/index.html)

FieldDescription

`inbox_id``string`Required

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

#### [Request body](/content/docs/reference/api/messages\#request-body-2/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`to``string | string[]`

Recipient address or addresses.

`cc``string | string[]`

CC recipient address or addresses.

`bcc``string | string[]`

BCC recipient address or addresses.

`subject``string`

Subject of the message.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-4/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-4/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request: error.type is validation and error.param names the field. |
| `401` | Missing, invalid, expired or revoked credential. |
| `402` | Free plan over its messages cap: 3,000 a month or 100 a day, inbound messages and outbound recipients together (each recipient counts once). error.limit\_key is messages\_per\_month or messages\_per\_day; resets\_at and Retry-After say when the allowance resets (absent when this message has more recipients than the cap itself). Paid plans are never refused. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `409` | Conflicts with an existing resource. |
| `429` | Unclaimed sandbox agent over a send cap: at most 10 messages to at most 10 different recipients per rolling 24 hours. Retry-After says when the next send fits. Claiming the inbox lifts the caps. Also returned when a Free organization goes over its daily number of different recipients. |
| `500` | Unexpected server error. |
| `501` | Not implemented. |
| `502` | The email provider refused or failed the send (error.type is upstream\_error). Nothing was sent and no message was stored. error.message says why: a rejected message or recipient is final, and so is a used-up sending quota until it resets; a throttled or unavailable provider can be retried later. A scheduled draft whose send fails this way is marked send\_status: failed, unless the provider could not take mail for now (throttled, sending paused, quota used up, or unavailable): it stays scheduled and is retried. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-4/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/send" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [Get Message](/content/docs/reference/api/messages\#get-message/index.html)

http

```
GET /v0/inboxes/{inbox_id}/messages/{message_id}
```

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-5/index.html)

FieldDescription

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

#### [Response](/content/docs/reference/api/messages\#response-5/index.html)

**200** The message (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

`reply_to``string[]`

Reply-to addresses. In format username@domain.com or Display Name <username@domain.com>.

`text``string`

Plain text body. Untrusted: agents should read trust.content.text or extracted\_text.

`html``string`

HTML body. Untrusted.

`extracted_text``string`

New text content, without quoted replies.

`extracted_html``string`

New HTML content, without quoted replies.

`received_via``"raw"`

raw when the message was injected with POST /inbound/raw (authentication not verified).

`held_at``string (date-time)`

`trust` [TrustReport](/content/docs/reference/api/objects#trustreport/index.html)

Trust report of an inbound message.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

`authentication_results` is a [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html):

FieldDescription

`spf``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

Result of one authentication mechanism, in the vocabulary of the Authentication-Results header (RFC 8601). none: there was nothing to evaluate (no SPF record for the envelope sender domain, no DKIM signature, or no DMARC record for the From domain). temperror: the check could not complete, for example a DNS timeout.

`dkim``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`dmarc``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`spf_domain``string`

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

`dkim_domain``string`

Signing domain (d=) of the signature the dkim verdict is about: for pass, a signature that passed, preferring one aligned with the From domain. Present only when dkim is pass or fail. It is the domain as signed: compare it with the From domain before relying on it.

`dmarc_domain``string`

From domain the dmarc verdict is about (header.from).

`arc_sealer``string`

Domain of the forwarder whose ARC seal the verdicts were read from (for example google.com): they then describe the message as that forwarder received it. Present only on forwarded mail, and only beside at least one verdict. MachineMail does not validate ARC chains, so it reads verdicts from ARC only when its trust layer is set to believe any results header; by default it believes only its own receiving server and does not send this key.

`trust` is a [TrustReport](/content/docs/reference/api/objects#trustreport/index.html):

FieldDescription

`level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

`score``number`Required

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

`basis``"trusted_domain"`

trusted\_domain: the sender is a trusted domain of the organization, pod or inbox (sender.trusted\_domain) and the message carries that domain's own DKIM signature. It is verified, or known when it contains instructions to an AI agent, a phishing signal or malware (content.warnings), and never suspicious or quarantined. Agents get its text and attachments, except attachments the virus scan flags. Absent otherwise.

`authentication``object`Required

`sender``object`Required

`content``object`Required

`links``object[]`Required

`attachments``object[]`Required

`classification``object`Required

`provider_verdicts``object`

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

`reasons``string[]`Required

Human-readable reasons for the verdict.

`computed_at``string (date-time)`Required

When the report was computed.

#### [Errors](/content/docs/reference/api/messages\#errors-5/index.html)

| Status | Meaning |
| --- | --- |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-5/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "inbox_id": "agent@machinemail.dev",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "labels": ["UNREAD"],
  "timestamp": "2026-10-01T12:00:00.000Z",
  "from": "Support Agent <agent@machinemail.dev>",
  "to": ["customer@example.com"],
  "cc": ["team@example.com"],
  "bcc": ["audit@example.com"],
  "subject": "Order #1042",
  "preview": "Thanks for the quick reply.",
  "attachments": [\
    {\
      "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
      "filename": "invoice.pdf",\
      "size": 2048,\
      "content_type": "application/pdf",\
      "content_disposition": "string",\
      "content_id": "string"\
    }\
  ],
  "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "references": ["string"],
  "headers": {
    "key": "value"
  },
  "authentication_results": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass",
    "spf_domain": "string",
    "dkim_domain": "string",
    "dmarc_domain": "string",
    "arc_sealer": "string"
  },
  "size": 2048,
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "direction": "inbound",
  "delivery_status": "sent",
  "trust_level": "verified",
  "reply_to": ["agent@machinemail.dev"],
  "text": "Thanks for the quick reply.",
  "html": "<p>Thanks for the quick reply.</p>",
  "extracted_text": "Thanks for the quick reply.",
  "extracted_html": "<p>Thanks for the quick reply.</p>",
  "received_via": "raw",
  "held_at": "2026-10-01T12:00:00.000Z",
  "trust": {
    "level": "verified",
    "score": 0.8,
    "basis": "trusted_domain",
    "authentication": {
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass",
      "aligned": false
    },
    "sender": {
      "address": "agent@machinemail.dev",
      "domain": "example.com",
      "prior_correspondence": false,
      "on_allow_list": false,
      "on_block_list": false,
      "free_mail_provider": false,
      "trusted_domain": {
        "id": "string",
        "domain": "example.com",
        "scope": "org"
      },
      "trusted_domain_shadowed_by": "block"
    },
    "content": {
      "text": "Thanks for the quick reply.",
      "html": "<p>Thanks for the quick reply.</p>",
      "segments": [\
        {\
          "kind": "body",\
          "text": "Thanks for the quick reply."\
        }\
      ],
      "hidden_text_found": false,
      "zero_width_found": false,
      "tracking_pixels": 1,
      "agent_instructions_detected": false,
      "warnings": ["string"]
    },
    "links": [\
      {\
        "href": "string",\
        "text": "Thanks for the quick reply.",\
        "final_url": "https://example.com",\
        "domain": "example.com",\
        "display_mismatch": false,\
        "shortener": false,\
        "suspicious": false,\
        "reasons": ["string"]\
      }\
    ],
    "attachments": [\
      {\
        "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
        "filename": "invoice.pdf",\
        "content_type": "application/pdf",\
        "risk": "low",\
        "reasons": ["string"],\
        "extracted_text": "Thanks for the quick reply."\
      }\
    ],
    "classification": {
      "is_spam": 0.8,
      "is_phishing": 0.8,
      "contains_instructions_to_agent": 0.8,
      "requests_credentials_or_payment": 0.8,
      "urgency": 0.8,
      "category": "transactional",
      "language": "string",
      "backend": "string",
      "input_hash": "string",
      "cached": false
    },
    "provider_verdicts": {
      "spam": "pass",
      "virus": "pass",
      "source": "string"
    },
    "reasons": ["string"],
    "computed_at": "2026-10-01T12:00:00.000Z"
  }
}
```

## [Update Message](/content/docs/reference/api/messages\#update-message/index.html)

http

```
PATCH /v0/inboxes/{inbox_id}/messages/{message_id}
```

Adds and removes labels. Returns the whole updated message.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_update`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-6/index.html)

FieldDescription

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

#### [Request body](/content/docs/reference/api/messages\#request-body-3/index.html)

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add.

`remove_labels``string | string[]`

Label or labels to remove.

#### [Response](/content/docs/reference/api/messages\#response-6/index.html)

**200** The updated message (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

`reply_to``string[]`

Reply-to addresses. In format username@domain.com or Display Name <username@domain.com>.

`text``string`

Plain text body. Untrusted: agents should read trust.content.text or extracted\_text.

`html``string`

HTML body. Untrusted.

`extracted_text``string`

New text content, without quoted replies.

`extracted_html``string`

New HTML content, without quoted replies.

`received_via``"raw"`

raw when the message was injected with POST /inbound/raw (authentication not verified).

`held_at``string (date-time)`

`trust` [TrustReport](/content/docs/reference/api/objects#trustreport/index.html)

Trust report of an inbound message.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

`authentication_results` is a [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html):

FieldDescription

`spf``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`dkim``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`dmarc``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`spf_domain``string`

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

`dkim_domain``string`

`dmarc_domain``string`

From domain the dmarc verdict is about (header.from).

`arc_sealer``string`

`trust` is a [TrustReport](/content/docs/reference/api/objects#trustreport/index.html):

FieldDescription

`level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

`score``number`Required

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

`basis``"trusted_domain"`

`authentication``object`Required

`sender``object`Required

`content``object`Required

`links``object[]`Required

`attachments``object[]`Required

`classification``object`Required

`provider_verdicts``object`

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

`reasons``string[]`Required

Human-readable reasons for the verdict.

`computed_at``string (date-time)`Required

When the report was computed.

#### [Errors](/content/docs/reference/api/messages\#errors-6/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-6/index.html)

Request

```
curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add_labels": "string"
}'
```

Response 200

## [Delete Message](/content/docs/reference/api/messages\#delete-message/index.html)

http

```
DELETE /v0/inboxes/{inbox_id}/messages/{message_id}
```

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_delete`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-7/index.html)

FieldDescription

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

#### [Response](/content/docs/reference/api/messages\#response-7/index.html)

**200** Deleted (`application/json`)

FieldDescription

`ok``true`Required

#### [Errors](/content/docs/reference/api/messages\#errors-7/index.html)

| Status | Meaning |
| --- | --- |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404` | Not found. Also returned for resources outside the credential scope. |
| `409` | Conflicts with an existing resource. |
| `500` | Unexpected server error. |

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-7/index.html)

Request

```
curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "ok": true
}
```

## [Get Attachment](/content/docs/reference/api/messages\#get-attachment/index.html)

http

```
GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}
```

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-8/index.html)

FieldDescription

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

#### [Response](/content/docs/reference/api/messages\#response-8/index.html)

**200** The attachment with a download URL (`application/json`)

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

`download_url``string`Required

URL of the attachment bytes. Depending on the storage backend: a signed storage URL, the API URL GET .../attachments/{attachment\_id}/download (send your API key), or a data: URI.

`expires_at``string (date-time)`Required

When download\_url expires: one hour from the request unless the signed URL sets its own expiry.

#### [Errors](/content/docs/reference/api/messages\#errors-8/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-8/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",
  "filename": "invoice.pdf",
  "size": 2048,
  "content_type": "application/pdf",
  "content_disposition": "string",
  "content_id": "string",
  "download_url": "https://example.com",
  "expires_at": "2026-10-01T12:00:00.000Z"
}
```

## [Download Attachment](/content/docs/reference/api/messages\#download-attachment/index.html)

http

```
GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download
```

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.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-9/index.html)

FieldDescription

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

#### [Query parameters](/content/docs/reference/api/messages\#query-parameters-2/index.html)

FieldDescription

`disposition``"attachment" | "inline"`

inline previews raster images, PDF and plain text in the browser; every other type downloads regardless.

Default`"attachment"`

#### [Response](/content/docs/reference/api/messages\#response-9/index.html)

**200** The attachment bytes (`application/octet-stream`)

Headers:

FieldDescription

`Content-Disposition``string`

attachment; filename="<ascii name>"; filename\*=UTF-8''<encoded name> (or inline; … for a preview).

#### [Errors](/content/docs/reference/api/messages\#errors-9/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-9/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r/download" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

## [Forward Message](/content/docs/reference/api/messages\#forward-message/index.html)

http

```
POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward
```

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

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-10/index.html)

FieldDescription

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

#### [Request body](/content/docs/reference/api/messages\#request-body-4/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`to``string | string[]`

Recipient address or addresses.

`cc``string | string[]`

CC recipient address or addresses.

`bcc``string | string[]`

BCC recipient address or addresses.

`subject``string`

Subject of the message.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-10/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-10/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-10/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/forward" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [Get Raw Message](/content/docs/reference/api/messages\#get-raw-message/index.html)

http

```
GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw
```

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-11/index.html)

FieldDescription

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

#### [Response](/content/docs/reference/api/messages\#response-11/index.html)

**200** The raw message (`message/rfc822`)

#### [Errors](/content/docs/reference/api/messages\#errors-11/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-11/index.html)

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/raw" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

## [Reply To Message](/content/docs/reference/api/messages\#reply-to-message/index.html)

http

```
POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply
```

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_reply` or `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-12/index.html)

FieldDescription

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

#### [Request body](/content/docs/reference/api/messages\#request-body-5/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`to``string | string[]`

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

`cc``string | string[]`

CC recipient address or addresses.

`bcc``string | string[]`

BCC recipient address or addresses.

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

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

`subject``string`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-12/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-12/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-12/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "text": "Thanks for the quick reply.",
  "subject": "Order #1042"
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [Reply All Message](/content/docs/reference/api/messages\#reply-all-message/index.html)

http

```
POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all
```

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

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_reply` or `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-13/index.html)

FieldDescription

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

#### [Request body](/content/docs/reference/api/messages\#request-body-6/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

`to``string | string[]`

More recipients, added to the sender and recipients of the original.

`cc``string | string[]`

More CC recipients, added to the CC recipients of the original.

`bcc``string | string[]`

BCC recipient address or addresses.

`subject``string`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-13/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-13/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-13/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply-all" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Thanks for the quick reply.",
  "to": "customer@example.com",
  "subject": "Order #1042"
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [List Messages in Pod](/content/docs/reference/api/messages\#list-messages-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages
```

Same as List Messages (`GET /v0/inboxes/{inbox_id}/messages`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-14/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

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

#### [Query parameters](/content/docs/reference/api/messages\#query-parameters-3/index.html)

FieldDescription

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`ascending``boolean`

Sort oldest first.

`labels``string[]`

Only items with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them.

`before``string (date-time)`

Only items with a timestamp before this time.

`after``string (date-time)`

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

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

#### [Response](/content/docs/reference/api/messages\#response-14/index.html)

**200** A page of messages (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`messages` [MessageItem\[\]](/content/docs/reference/api/objects#messageitem/index.html) Required

Ordered by timestamp, newest first unless ascending is set.

Each item of `messages` is a [MessageItem](/content/docs/reference/api/objects#messageitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

#### [Errors](/content/docs/reference/api/messages\#errors-14/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-14/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Batch Get Messages in Pod](/content/docs/reference/api/messages\#batch-get-messages-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-get
```

Same as Batch Get Messages (`POST /v0/inboxes/{inbox_id}/messages/batch-get`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-15/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

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

#### [Request body](/content/docs/reference/api/messages\#request-body-7/index.html)

Content type: `application/json`.

FieldDescription

`message_ids``string[]`Required

IDs of the messages to fetch. Only the first 100 distinct IDs are read.

#### [Response](/content/docs/reference/api/messages\#response-15/index.html)

**200** The messages found (`application/json`)

FieldDescription

`limit``integer`Required

Number of IDs in the request.

`count``integer`Required

Number of messages returned.

`messages` [Message\[\]](/content/docs/reference/api/objects#message/index.html) Required

Found messages, in request order. IDs not found in the inbox are omitted.

Each item of `messages` is a [Message](/content/docs/reference/api/objects#message/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

`reply_to``string[]`

Reply-to addresses. In format username@domain.com or Display Name <username@domain.com>.

`text``string`

Plain text body. Untrusted: agents should read trust.content.text or extracted\_text.

`html``string`

HTML body. Untrusted.

`extracted_text``string`

New text content, without quoted replies.

`extracted_html``string`

New HTML content, without quoted replies.

`received_via``"raw"`

raw when the message was injected with POST /inbound/raw (authentication not verified).

`held_at``string (date-time)`

`trust` [TrustReport](/content/docs/reference/api/objects#trustreport/index.html)

Trust report of an inbound message.

#### [Errors](/content/docs/reference/api/messages\#errors-15/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-15/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/batch-get" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ]
}'
```

Response 200

## [Batch Update Messages in Pod](/content/docs/reference/api/messages\#batch-update-messages-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-update
```

Same as Batch Update Messages (`POST /v0/inboxes/{inbox_id}/messages/batch-update`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_update`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-16/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

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

#### [Request body](/content/docs/reference/api/messages\#request-body-8/index.html)

Content type: `application/json`.

FieldDescription

`message_ids``string[]`Required

IDs of the messages to update. Only the first 100 distinct IDs are updated.

`add_labels``string | string[]`

Label or labels to add to every message.

`remove_labels``string | string[]`

Label or labels to remove from every message.

#### [Response](/content/docs/reference/api/messages\#response-16/index.html)

**200** The updated messages (`application/json`)

FieldDescription

`limit``integer`Required

Number of IDs in the request.

`count``integer`Required

Number of messages updated.

`updates` [UpdateMessageResponse\[\]](/content/docs/reference/api/objects#updatemessageresponse/index.html) Required

Updated messages with their new labels, in request order. IDs not found are omitted.

Each item of `updates` is a [UpdateMessageResponse](/content/docs/reference/api/objects#updatemessageresponse/index.html):

FieldDescription

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message after the update.

#### [Errors](/content/docs/reference/api/messages\#errors-16/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-16/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/batch-update" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ],
  "add_labels": "string"
}'
```

Response 200

```
{
  "limit": 50,
  "count": 1,
  "updates": [\
    {\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"]\
    }\
  ]
}
```

## [Search Messages in Pod](/content/docs/reference/api/messages\#search-messages-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/search
```

Same as Search Messages (`GET /v0/inboxes/{inbox_id}/messages/search`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-17/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

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

#### [Query parameters](/content/docs/reference/api/messages\#query-parameters-4/index.html)

FieldDescription

`q``string`Required

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

`limit``integer`

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

`page_token``string`

next\_page\_token from the previous page.

`before``string (date-time)`

Only messages before this time.

`after``string (date-time)`

Only messages after this time.

`ascending``boolean`

Sort oldest first.

#### [Response](/content/docs/reference/api/messages\#response-17/index.html)

**200** A page of matching messages (`application/json`)

FieldDescription

`count``integer`Required

Number of items returned.

`limit``integer`

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

`next_page_token``string`

Page token for pagination. Absent on the last page.

`messages` [MessageItem\[\]](/content/docs/reference/api/objects#messageitem/index.html) Required

Matching messages, newest first unless ascending is set.

Each item of `messages` is a [MessageItem](/content/docs/reference/api/objects#messageitem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

#### [Errors](/content/docs/reference/api/messages\#errors-17/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-17/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/search?q=invoice" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Send Message in Pod](/content/docs/reference/api/messages\#send-message-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/send
```

Same as Send Message (`POST /v0/inboxes/{inbox_id}/messages/send`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-18/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`inbox_id``string`Required

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

#### [Request body](/content/docs/reference/api/messages\#request-body-9/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`to``string | string[]`

Recipient address or addresses.

`cc``string | string[]`

CC recipient address or addresses.

`bcc``string | string[]`

BCC recipient address or addresses.

`subject``string`

Subject of the message.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-18/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-18/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-18/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/send" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [Get Message in Pod](/content/docs/reference/api/messages\#get-message-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}
```

Same as Get Message (`GET /v0/inboxes/{inbox_id}/messages/{message_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-19/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Response](/content/docs/reference/api/messages\#response-19/index.html)

**200** The message (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

`reply_to``string[]`

Reply-to addresses. In format username@domain.com or Display Name <username@domain.com>.

`text``string`

Plain text body. Untrusted: agents should read trust.content.text or extracted\_text.

`html``string`

HTML body. Untrusted.

`extracted_text``string`

New text content, without quoted replies.

`extracted_html``string`

New HTML content, without quoted replies.

`received_via``"raw"`

raw when the message was injected with POST /inbound/raw (authentication not verified).

`held_at``string (date-time)`

`trust` [TrustReport](/content/docs/reference/api/objects#trustreport/index.html)

Trust report of an inbound message.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

`authentication_results` is a [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html):

FieldDescription

`spf``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`dkim``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`dmarc``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`spf_domain``string`

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

`dkim_domain``string`

`dmarc_domain``string`

From domain the dmarc verdict is about (header.from).

`arc_sealer``string`

`trust` is a [TrustReport](/content/docs/reference/api/objects#trustreport/index.html):

FieldDescription

`level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

`score``number`Required

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

`basis``"trusted_domain"`

`authentication``object`Required

`sender``object`Required

`content``object`Required

`links``object[]`Required

`attachments``object[]`Required

`classification``object`Required

`provider_verdicts``object`

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

`reasons``string[]`Required

Human-readable reasons for the verdict.

`computed_at``string (date-time)`Required

When the report was computed.

#### [Errors](/content/docs/reference/api/messages\#errors-19/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-19/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Update Message in Pod](/content/docs/reference/api/messages\#update-message-in-pod/index.html)

http

```
PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}
```

Same as Update Message (`PATCH /v0/inboxes/{inbox_id}/messages/{message_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_update`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-20/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Request body](/content/docs/reference/api/messages\#request-body-10/index.html)

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add.

`remove_labels``string | string[]`

Label or labels to remove.

#### [Response](/content/docs/reference/api/messages\#response-20/index.html)

**200** The updated message (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`message_id``string`Required

ID of the message.

`labels``string[]`Required

Labels of the message.

`timestamp``string (date-time)`Required

Time at which the message was sent or received.

`from``string`Required

Address of the sender. In format username@domain.com or Display Name <username@domain.com>.

`to``string[]`Required

Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.

`cc``string[]`

Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.

`bcc``string[]`

Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.

`subject``string`

Subject of the message.

`preview``string`

Text preview of the message.

`attachments` [Attachment\[\]](/content/docs/reference/api/objects#attachment/index.html)

Attachments of the message.

`in_reply_to``string`

ID of the message being replied to.

`references``string[]`

IDs of previous messages in the thread.

`headers``Record<string, string>`

Headers of the message.

`authentication_results` [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)

`size``integer`Required

Size of the message in bytes.

`updated_at``string (date-time)`Required

Time at which the message was last updated.

`created_at``string (date-time)`Required

Time at which the message was created.

`pod_id``string`Required

ID of the pod.

`direction``"inbound" | "outbound"`Required

Whether the message was received or sent.

`delivery_status``"sent" | "delivered" | "bounced" | "complained"`

Outbound only: last delivery state reported by the transport.

`trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`

Inbound only: trust.level, for list badges.

`reply_to``string[]`

Reply-to addresses. In format username@domain.com or Display Name <username@domain.com>.

`text``string`

Plain text body. Untrusted: agents should read trust.content.text or extracted\_text.

`html``string`

HTML body. Untrusted.

`extracted_text``string`

New text content, without quoted replies.

`extracted_html``string`

New HTML content, without quoted replies.

`received_via``"raw"`

raw when the message was injected with POST /inbound/raw (authentication not verified).

`held_at``string (date-time)`

`trust` [TrustReport](/content/docs/reference/api/objects#trustreport/index.html)

Trust report of an inbound message.

Each item of `attachments` is a [Attachment](/content/docs/reference/api/objects#attachment/index.html):

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

`authentication_results` is a [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html):

FieldDescription

`spf``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`dkim``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`dmarc``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"`

`spf_domain``string`

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

`dkim_domain``string`

`dmarc_domain``string`

From domain the dmarc verdict is about (header.from).

`arc_sealer``string`

`trust` is a [TrustReport](/content/docs/reference/api/objects#trustreport/index.html):

FieldDescription

`level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"`Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

`score``number`Required

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

`basis``"trusted_domain"`

`authentication``object`Required

`sender``object`Required

`content``object`Required

`links``object[]`Required

`attachments``object[]`Required

`classification``object`Required

`provider_verdicts``object`

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

`reasons``string[]`Required

Human-readable reasons for the verdict.

`computed_at``string (date-time)`Required

When the report was computed.

#### [Errors](/content/docs/reference/api/messages\#errors-20/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-20/index.html)

Request

```
curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add_labels": "string"
}'
```

Response 200

## [Delete Message in Pod](/content/docs/reference/api/messages\#delete-message-in-pod/index.html)

http

```
DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}
```

Same as Delete Message (`DELETE /v0/inboxes/{inbox_id}/messages/{message_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_delete`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-21/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Response](/content/docs/reference/api/messages\#response-21/index.html)

**200** Deleted (`application/json`)

FieldDescription

`ok``true`Required

#### [Errors](/content/docs/reference/api/messages\#errors-21/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-21/index.html)

Request

```
curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "ok": true
}
```

## [Get Attachment in Pod](/content/docs/reference/api/messages\#get-attachment-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}
```

Same as Get Attachment (`GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-22/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Response](/content/docs/reference/api/messages\#response-22/index.html)

**200** The attachment with a download URL (`application/json`)

FieldDescription

`attachment_id``string`Required

ID of the attachment.

`filename``string`

Filename of the attachment.

`size``integer`Required

Size of the attachment in bytes.

`content_type``string`

Content type of the attachment.

`content_disposition``string`

Content disposition of the attachment (inline or attachment).

`content_id``string`

Content ID of the attachment.

`download_url``string`Required

`expires_at``string (date-time)`Required

When download\_url expires: one hour from the request unless the signed URL sets its own expiry.

#### [Errors](/content/docs/reference/api/messages\#errors-22/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-22/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Download Attachment in Pod](/content/docs/reference/api/messages\#download-attachment-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download
```

Same as Download Attachment (`GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-23/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Query parameters](/content/docs/reference/api/messages\#query-parameters-5/index.html)

FieldDescription

`disposition``"attachment" | "inline"`

inline previews raster images, PDF and plain text in the browser; every other type downloads regardless.

Default`"attachment"`

#### [Response](/content/docs/reference/api/messages\#response-23/index.html)

**200** The attachment bytes (`application/octet-stream`)

Headers:

FieldDescription

`Content-Disposition``string`

attachment; filename="<ascii name>"; filename\*=UTF-8''<encoded name> (or inline; … for a preview).

#### [Errors](/content/docs/reference/api/messages\#errors-23/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-23/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r/download" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

## [Forward Message in Pod](/content/docs/reference/api/messages\#forward-message-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/forward
```

Same as Forward Message (`POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-24/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Request body](/content/docs/reference/api/messages\#request-body-11/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`to``string | string[]`

Recipient address or addresses.

`cc``string | string[]`

CC recipient address or addresses.

`bcc``string | string[]`

BCC recipient address or addresses.

`subject``string`

Subject of the message.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-24/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-24/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-24/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/forward" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [Get Raw Message in Pod](/content/docs/reference/api/messages\#get-raw-message-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/raw
```

Same as Get Raw Message (`GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-25/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Response](/content/docs/reference/api/messages\#response-25/index.html)

**200** The raw message (`message/rfc822`)

#### [Errors](/content/docs/reference/api/messages\#errors-25/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-25/index.html)

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/raw" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

## [Reply To Message in Pod](/content/docs/reference/api/messages\#reply-to-message-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply
```

Same as Reply To Message (`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_reply` or `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-26/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Request body](/content/docs/reference/api/messages\#request-body-12/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`to``string | string[]`

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

`cc``string | string[]`

CC recipient address or addresses.

`bcc``string | string[]`

BCC recipient address or addresses.

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

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

`subject``string`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-26/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-26/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-26/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "text": "Thanks for the quick reply.",
  "subject": "Order #1042"
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

## [Reply All Message in Pod](/content/docs/reference/api/messages\#reply-all-message-in-pod/index.html)

http

```
POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply-all
```

Same as Reply All Message (`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all`), limited to the pod.

**Authentication:**`Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_reply` or `message_send`.

#### [Path parameters](/content/docs/reference/api/messages\#path-parameters-27/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

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

#### [Request body](/content/docs/reference/api/messages\#request-body-13/index.html)

Content type: `application/json`.

FieldDescription

`labels``string | string[]`

Labels of the message. SENT is always added.

`reply_to``string | string[]`

Reply-to address or addresses.

`text``string`

Plain text body.

`html``string`

HTML body.

`attachments` [SendAttachment\[\]](/content/docs/reference/api/objects#sendattachment/index.html)

Attachments to include.

`headers``Record<string, string>`

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

`to``string | string[]`

More recipients, added to the sender and recipients of the original.

`cc``string | string[]`

More CC recipients, added to the CC recipients of the original.

`bcc``string | string[]`

BCC recipient address or addresses.

`subject``string`

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

Each item of `attachments` is a [SendAttachment](/content/docs/reference/api/objects#sendattachment/index.html):

FieldDescription

`filename``string`

Filename of the attachment. Defaults to the last segment of url.

`content_type``string`

Content type of the attachment. Defaults to the Content-Type of the url response.

`content_disposition``"inline" | "attachment"`

Content disposition of the attachment.

`content_id``string`

Content ID, for inline images referenced as cid: in the HTML body.

`content``string`

Base64 encoded content of the attachment.

`url``string`

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

#### [Response](/content/docs/reference/api/messages\#response-27/index.html)

**201** Sent (`application/json`)

FieldDescription

`message_id``string`Required

ID of the message.

`thread_id``string`Required

ID of the thread.

`timestamp``string (date-time)`Required

When the message was sent.

#### [Errors](/content/docs/reference/api/messages\#errors-27/index.html)

Error bodies use the [error envelope](/content/docs/reference/errors/index.html).

#### [Example](/content/docs/reference/api/messages\#example-27/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply-all" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Thanks for the quick reply.",
  "to": "customer@example.com",
  "subject": "Order #1042"
}'
```

Response 201

```
{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}
```

On this page

[List Messages](/content/docs/reference/api/messages#list-messages/index.html) [Batch Get Messages](/content/docs/reference/api/messages#batch-get-messages/index.html) [Batch Update Messages](/content/docs/reference/api/messages#batch-update-messages/index.html) [Search Messages](/content/docs/reference/api/messages#search-messages/index.html) [Send Message](/content/docs/reference/api/messages#send-message/index.html) [Get Message](/content/docs/reference/api/messages#get-message/index.html) [Update Message](/content/docs/reference/api/messages#update-message/index.html) [Delete Message](/content/docs/reference/api/messages#delete-message/index.html) [Get Attachment](/content/docs/reference/api/messages#get-attachment/index.html) [Download Attachment](/content/docs/reference/api/messages#download-attachment/index.html) [Forward Message](/content/docs/reference/api/messages#forward-message/index.html) [Get Raw Message](/content/docs/reference/api/messages#get-raw-message/index.html) [Reply To Message](/content/docs/reference/api/messages#reply-to-message/index.html) [Reply All Message](/content/docs/reference/api/messages#reply-all-message/index.html) [List Messages in Pod](/content/docs/reference/api/messages#list-messages-in-pod/index.html) [Batch Get Messages in Pod](/content/docs/reference/api/messages#batch-get-messages-in-pod/index.html) [Batch Update Messages in Pod](/content/docs/reference/api/messages#batch-update-messages-in-pod/index.html) [Search Messages in Pod](/content/docs/reference/api/messages#search-messages-in-pod/index.html) [Send Message in Pod](/content/docs/reference/api/messages#send-message-in-pod/index.html) [Get Message in Pod](/content/docs/reference/api/messages#get-message-in-pod/index.html) [Update Message in Pod](/content/docs/reference/api/messages#update-message-in-pod/index.html) [Delete Message in Pod](/content/docs/reference/api/messages#delete-message-in-pod/index.html) [Get Attachment in Pod](/content/docs/reference/api/messages#get-attachment-in-pod/index.html) [Download Attachment in Pod](/content/docs/reference/api/messages#download-attachment-in-pod/index.html) [Forward Message in Pod](/content/docs/reference/api/messages#forward-message-in-pod/index.html) [Get Raw Message in Pod](/content/docs/reference/api/messages#get-raw-message-in-pod/index.html) [Reply To Message in Pod](/content/docs/reference/api/messages#reply-to-message-in-pod/index.html) [Reply All Message in Pod](/content/docs/reference/api/messages#reply-all-message-in-pod/index.html)

100% readTop