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

\[01/20\]List Threads

| Method | Path | Summary |
| --- | --- | --- |
| `GET` | `/v0/inboxes/{inbox_id}/threads` | [List Threads](/content/docs/reference/api/threads#list-threads/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/threads/search` | [Search Threads](/content/docs/reference/api/threads#search-threads/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/threads/{thread_id}` | [Get Thread](/content/docs/reference/api/threads#get-thread/index.html) |
| `PATCH` | `/v0/inboxes/{inbox_id}/threads/{thread_id}` | [Update Thread](/content/docs/reference/api/threads#update-thread/index.html) |
| `DELETE` | `/v0/inboxes/{inbox_id}/threads/{thread_id}` | [Delete Thread](/content/docs/reference/api/threads#delete-thread/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/threads` | [List Threads in Pod](/content/docs/reference/api/threads#list-threads-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/threads/search` | [Search Threads in Pod](/content/docs/reference/api/threads#search-threads-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/threads/{thread_id}` | [Get Thread in Pod](/content/docs/reference/api/threads#get-thread-in-pod/index.html) |
| `PATCH` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/threads/{thread_id}` | [Update Thread in Pod](/content/docs/reference/api/threads#update-thread-in-pod/index.html) |
| `DELETE` | `/v0/pods/{pod_id}/inboxes/{inbox_id}/threads/{thread_id}` | [Delete Thread in Pod](/content/docs/reference/api/threads#delete-thread-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/threads` | [List Threads in Pod](/content/docs/reference/api/threads#list-threads-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/threads/search` | [Search Threads in Pod](/content/docs/reference/api/threads#search-threads-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/threads/{thread_id}` | [Get Thread in Pod](/content/docs/reference/api/threads#get-thread-in-pod/index.html) |
| `PATCH` | `/v0/pods/{pod_id}/threads/{thread_id}` | [Update Thread in Pod](/content/docs/reference/api/threads#update-thread-in-pod/index.html) |
| `DELETE` | `/v0/pods/{pod_id}/threads/{thread_id}` | [Delete Thread in Pod](/content/docs/reference/api/threads#delete-thread-in-pod/index.html) |
| `GET` | `/v0/threads` | [List Threads](/content/docs/reference/api/threads#list-threads/index.html) |
| `GET` | `/v0/threads/search` | [Search Threads](/content/docs/reference/api/threads#search-threads/index.html) |
| `GET` | `/v0/threads/{thread_id}` | [Get Thread](/content/docs/reference/api/threads#get-thread/index.html) |
| `PATCH` | `/v0/threads/{thread_id}` | [Update Thread](/content/docs/reference/api/threads#update-thread/index.html) |
| `DELETE` | `/v0/threads/{thread_id}` | [Delete Thread](/content/docs/reference/api/threads#delete-thread/index.html) |

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

http

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

Threads, most recently active first. Pass `q` to keep only threads with a message matching the words.

Threads with a spam, blocked, trash, quarantined or unauthenticated message are hidden unless you pass the matching `include_*` flag or ask for the label in `labels`.

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

#### [Path parameters](/content/docs/reference/api/threads\#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/threads\#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 threads that have a quarantined message.

`q``string`

Full-text filter: threads with a message whose subject, sender, recipients, body or attachment file names contain the words. Scans the newest 500 matching messages.

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

**200** A page of threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

#### [Errors](/content/docs/reference/api/threads\#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/threads\#example/index.html)

Request

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

Response 200

```
{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "threads": [\
    {\
      "inbox_id": "agent@machinemail.dev",\
      "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",\
      "labels": ["UNREAD"],\
      "timestamp": "2026-10-01T12:00:00.000Z",\
      "received_timestamp": "2026-10-01T12:00:00.000Z",\
      "sent_timestamp": "2026-10-01T12:00:00.000Z",\
      "senders": ["customer@example.com"],\
      "recipients": ["agent@machinemail.dev"],\
      "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"\
        }\
      ],\
      "last_message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "message_count": 1,\
      "size": 2048,\
      "updated_at": "2026-10-01T12:00:00.000Z",\
      "created_at": "2026-10-01T12:00:00.000Z",\
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f"\
    }\
  ],
  "truncated": true
}
```

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

http

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

Threads with a message whose subject, sender, recipients, body or attachment file names contain every word of `q`, ordered by thread activity (not ranked by relevance). Scans the newest 500 matching messages; the response has `truncated: true` when it hit that cap.

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

#### [Path parameters](/content/docs/reference/api/threads\#path-parameters-1/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/threads\#query-parameters-1/index.html)

FieldDescription

`q``string`Required

Full-text filter: threads with a message whose subject, sender, recipients, body or attachment file names contain the words. Scans the newest 500 matching messages. (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 items with a timestamp before this time.

`after``string (date-time)`

Only items with a timestamp after this time.

`ascending``boolean`

Sort oldest first.

`labels``string[]`

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

`include_spam``boolean`

Include threads with spam (needs label\_spam\_read; ignored without it).

`include_blocked``boolean`

Include threads with blocked mail (needs label\_blocked\_read; ignored without it).

`include_unauthenticated``boolean`

Include threads with unauthenticated mail (needs label\_unauthenticated\_read; ignored without it).

`include_trash``boolean`

Include threads with trash (needs label\_trash\_read; ignored without it).

`include_quarantine``boolean`

Include threads that have a quarantined message.

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

**200** A page of matching threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Matching threads, ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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

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

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

Request

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

Response 200

## [Get Thread](/content/docs/reference/api/threads\#get-thread/index.html)

http

```
GET /v0/inboxes/{inbox_id}/threads/{thread_id}
```

The thread with its messages, which carry their bodies and trust reports. Messages come in pages of `limit` (default and maximum 500): the first page has the newest messages, oldest first within the page; follow `next_page_token` for older ones.

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

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

FieldDescription

`inbox_id``string`Required

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

`thread_id``string`Required

ID of the thread.

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

FieldDescription

`limit``integer`

Maximum number of messages to return. Default and maximum 500.

`page_token``string`

next\_page\_token from the previous response: the next, older page of messages.

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

**200** The thread with a page of its messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

`count``integer`Required

Number of messages in this page.

`limit``integer`

Maximum number of messages requested for this page.

`next_page_token``string`

Token for the next, older page of messages. Absent when this page completes the thread.

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

Messages in this page, oldest first. The first page has the newest messages; follow next\_page\_token for older ones.

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.

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)

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.

`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/threads\#errors-2/index.html)

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

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

Request

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

Response 200

```
{
  "inbox_id": "agent@machinemail.dev",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "labels": ["UNREAD"],
  "timestamp": "2026-10-01T12:00:00.000Z",
  "received_timestamp": "2026-10-01T12:00:00.000Z",
  "sent_timestamp": "2026-10-01T12:00:00.000Z",
  "senders": ["customer@example.com"],
  "recipients": ["agent@machinemail.dev"],
  "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"\
    }\
  ],
  "last_message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "message_count": 1,
  "size": 2048,
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "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",\
      "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"\
      }\
    }\
  ]
}
```

## [Update Thread](/content/docs/reference/api/threads\#update-thread/index.html)

http

```
PATCH /v0/inboxes/{inbox_id}/threads/{thread_id}
```

Adds and removes labels on every message in the thread (up to 500 messages); the thread labels are their union. Labels are free strings, system labels included. Returns the updated thread without messages.

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

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

FieldDescription

`inbox_id``string`Required

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

`thread_id``string`Required

ID of the thread.

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

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add to every message in the thread.

`remove_labels``string | string[]`

Label or labels to remove from every message in the thread. Applied after add\_labels.

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

**200** The updated thread, without messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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.

#### [Errors](/content/docs/reference/api/threads\#errors-3/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/threads\#example-3/index.html)

Request

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

Response 200

## [Delete Thread](/content/docs/reference/api/threads\#delete-thread/index.html)

http

```
DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}
```

Permanently deletes the thread and its messages (up to 500).

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

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

FieldDescription

`inbox_id``string`Required

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

`thread_id``string`Required

ID of the thread.

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

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

FieldDescription

`ok``true`Required

#### [Errors](/content/docs/reference/api/threads\#errors-4/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/threads\#example-4/index.html)

Request

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

Response 200

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

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

http

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

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

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

#### [Path parameters](/content/docs/reference/api/threads\#path-parameters-5/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/threads\#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 threads that have a quarantined message.

`q``string`

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

**200** A page of threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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

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

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

Request

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

Response 200

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

http

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

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

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

#### [Path parameters](/content/docs/reference/api/threads\#path-parameters-6/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/threads\#query-parameters-4/index.html)

FieldDescription

`q``string`Required

`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 items with a timestamp before this time.

`after``string (date-time)`

Only items with a timestamp after this time.

`ascending``boolean`

Sort oldest first.

`labels``string[]`

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

`include_spam``boolean`

Include threads with spam (needs label\_spam\_read; ignored without it).

`include_blocked``boolean`

Include threads with blocked mail (needs label\_blocked\_read; ignored without it).

`include_unauthenticated``boolean`

Include threads with unauthenticated mail (needs label\_unauthenticated\_read; ignored without it).

`include_trash``boolean`

Include threads with trash (needs label\_trash\_read; ignored without it).

`include_quarantine``boolean`

Include threads that have a quarantined message.

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

**200** A page of matching threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Matching threads, ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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

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

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

Request

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

Response 200

## [Get Thread in Pod](/content/docs/reference/api/threads\#get-thread-in-pod/index.html)

http

```
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/threads/{thread_id}
```

Same as Get Thread (`GET /v0/inboxes/{inbox_id}/threads/{thread_id}`), limited to the pod.

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

#### [Path parameters](/content/docs/reference/api/threads\#path-parameters-7/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).

`thread_id``string`Required

ID of the thread.

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

FieldDescription

`limit``integer`

Maximum number of messages to return. Default and maximum 500.

`page_token``string`

next\_page\_token from the previous response: the next, older page of messages.

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

**200** The thread with a page of its messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

`count``integer`Required

Number of messages in this page.

`limit``integer`

Maximum number of messages requested for this page.

`next_page_token``string`

Token for the next, older page of messages. Absent when this page completes the thread.

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

Messages in this page, oldest first. The first page has the newest messages; follow next\_page\_token for older ones.

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.

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/threads\#errors-7/index.html)

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

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

Request

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

Response 200

## [Update Thread in Pod](/content/docs/reference/api/threads\#update-thread-in-pod/index.html)

http

```
PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}/threads/{thread_id}
```

Same as Update Thread (`PATCH /v0/inboxes/{inbox_id}/threads/{thread_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/threads\#path-parameters-8/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).

`thread_id``string`Required

ID of the thread.

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

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add to every message in the thread.

`remove_labels``string | string[]`

Label or labels to remove from every message in the thread. Applied after add\_labels.

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

**200** The updated thread, without messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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.

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

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

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

Request

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

Response 200

## [Delete Thread in Pod](/content/docs/reference/api/threads\#delete-thread-in-pod/index.html)

http

```
DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/threads/{thread_id}
```

Same as Delete Thread (`DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}`), limited to the pod.

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

#### [Path parameters](/content/docs/reference/api/threads\#path-parameters-9/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).

`thread_id``string`Required

ID of the thread.

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

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

FieldDescription

`ok``true`Required

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

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

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

Request

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

Response 200

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

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

http

```
GET /v0/pods/{pod_id}/threads
```

Same as List Threads (`GET /v0/threads`), limited to the pod.

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

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

FieldDescription

`pod_id``string`Required

ID of the pod.

#### [Query parameters](/content/docs/reference/api/threads\#query-parameters-6/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 threads that have a quarantined message.

`q``string`

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

**200** A page of threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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

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

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

Request

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

Response 200

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

http

```
GET /v0/pods/{pod_id}/threads/search
```

Same as Search Threads (`GET /v0/threads/search`), limited to the pod.

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

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

FieldDescription

`pod_id``string`Required

ID of the pod.

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

FieldDescription

`q``string`Required

`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 items with a timestamp before this time.

`after``string (date-time)`

Only items with a timestamp after this time.

`ascending``boolean`

Sort oldest first.

`labels``string[]`

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

`include_spam``boolean`

Include threads with spam (needs label\_spam\_read; ignored without it).

`include_blocked``boolean`

Include threads with blocked mail (needs label\_blocked\_read; ignored without it).

`include_unauthenticated``boolean`

Include threads with unauthenticated mail (needs label\_unauthenticated\_read; ignored without it).

`include_trash``boolean`

Include threads with trash (needs label\_trash\_read; ignored without it).

`include_quarantine``boolean`

Include threads that have a quarantined message.

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

**200** A page of matching threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Matching threads, ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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

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

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

Request

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

Response 200

## [Get Thread in Pod](/content/docs/reference/api/threads\#get-thread-in-pod-1/index.html)

http

```
GET /v0/pods/{pod_id}/threads/{thread_id}
```

Same as Get Thread (`GET /v0/threads/{thread_id}`), limited to the pod.

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

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

FieldDescription

`pod_id``string`Required

ID of the pod.

`thread_id``string`Required

ID of the thread.

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

FieldDescription

`limit``integer`

Maximum number of messages to return. Default and maximum 500.

`page_token``string`

next\_page\_token from the previous response: the next, older page of messages.

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

**200** The thread with a page of its messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

`count``integer`Required

Number of messages in this page.

`limit``integer`

Maximum number of messages requested for this page.

`next_page_token``string`

Token for the next, older page of messages. Absent when this page completes the thread.

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

Messages in this page, oldest first. The first page has the newest messages; follow next\_page\_token for older ones.

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.

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/threads\#errors-12/index.html)

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

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

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/threads/thd_01k6x3a1fz0000c9k5ns1x4e6g" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Update Thread in Pod](/content/docs/reference/api/threads\#update-thread-in-pod-1/index.html)

http

```
PATCH /v0/pods/{pod_id}/threads/{thread_id}
```

Same as Update Thread (`PATCH /v0/threads/{thread_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/threads\#path-parameters-13/index.html)

FieldDescription

`pod_id``string`Required

ID of the pod.

`thread_id``string`Required

ID of the thread.

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

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add to every message in the thread.

`remove_labels``string | string[]`

Label or labels to remove from every message in the thread. Applied after add\_labels.

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

**200** The updated thread, without messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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.

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

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

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

Request

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

Response 200

## [Delete Thread in Pod](/content/docs/reference/api/threads\#delete-thread-in-pod-1/index.html)

http

```
DELETE /v0/pods/{pod_id}/threads/{thread_id}
```

Same as Delete Thread (`DELETE /v0/threads/{thread_id}`), limited to the pod.

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

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

FieldDescription

`pod_id``string`Required

ID of the pod.

`thread_id``string`Required

ID of the thread.

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

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

FieldDescription

`ok``true`Required

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

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

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

Request

```
curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/threads/thd_01k6x3a1fz0000c9k5ns1x4e6g" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

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

## [List Threads](/content/docs/reference/api/threads\#list-threads-1/index.html)

http

```
GET /v0/threads
```

Threads, most recently active first. Pass `q` to keep only threads with a message matching the words.

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

#### [Query parameters](/content/docs/reference/api/threads\#query-parameters-9/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 threads that have a quarantined message.

`q``string`

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

**200** A page of threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

#### [Errors](/content/docs/reference/api/threads\#errors-15/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). |
| `500` | Unexpected server error. |

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

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

Request

```
curl "https://api.machinemail.dev/v0/threads" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Search Threads](/content/docs/reference/api/threads\#search-threads-1/index.html)

http

```
GET /v0/threads/search
```

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

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

FieldDescription

`q``string`Required

`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 items with a timestamp before this time.

`after``string (date-time)`

Only items with a timestamp after this time.

`ascending``boolean`

Sort oldest first.

`labels``string[]`

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

`include_spam``boolean`

Include threads with spam (needs label\_spam\_read; ignored without it).

`include_blocked``boolean`

Include threads with blocked mail (needs label\_blocked\_read; ignored without it).

`include_unauthenticated``boolean`

Include threads with unauthenticated mail (needs label\_unauthenticated\_read; ignored without it).

`include_trash``boolean`

Include threads with trash (needs label\_trash\_read; ignored without it).

`include_quarantine``boolean`

Include threads that have a quarantined message.

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

**200** A page of matching threads (`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.

`threads` [ThreadItem\[\]](/content/docs/reference/api/objects#threaditem/index.html) Required

Matching threads, ordered by timestamp, newest first unless ascending is set.

`truncated``true`

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Each item of `threads` is a [ThreadItem](/content/docs/reference/api/objects#threaditem/index.html):

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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

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

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

Request

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

Response 200

## [Get Thread](/content/docs/reference/api/threads\#get-thread-1/index.html)

http

```
GET /v0/threads/{thread_id}
```

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

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

FieldDescription

`thread_id``string`Required

ID of the thread.

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

FieldDescription

`limit``integer`

Maximum number of messages to return. Default and maximum 500.

`page_token``string`

next\_page\_token from the previous response: the next, older page of messages.

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

**200** The thread with a page of its messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

`count``integer`Required

Number of messages in this page.

`limit``integer`

Maximum number of messages requested for this page.

`next_page_token``string`

Token for the next, older page of messages. Absent when this page completes the thread.

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

Messages in this page, oldest first. The first page has the newest messages; follow next\_page\_token for older ones.

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.

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/threads\#errors-17/index.html)

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

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

Request

```
curl "https://api.machinemail.dev/v0/threads/thd_01k6x3a1fz0000c9k5ns1x4e6g" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

## [Update Thread](/content/docs/reference/api/threads\#update-thread-1/index.html)

http

```
PATCH /v0/threads/{thread_id}
```

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

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

FieldDescription

`thread_id``string`Required

ID of the thread.

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

Content type: `application/json`.

FieldDescription

`add_labels``string | string[]`

Label or labels to add to every message in the thread.

`remove_labels``string | string[]`

Label or labels to remove from every message in the thread. Applied after add\_labels.

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

**200** The updated thread, without messages (`application/json`)

FieldDescription

`inbox_id``string`Required

ID of the inbox.

`thread_id``string`Required

ID of the thread.

`labels``string[]`Required

Labels of the thread: the union of the labels of its messages.

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

Timestamp of the last sent or received message.

`received_timestamp``string (date-time)`

Timestamp of the last received message.

`sent_timestamp``string (date-time)`

Timestamp of the last sent message.

`senders``string[]`Required

Senders in the thread. In format username@domain.com.

`recipients``string[]`Required

Recipients (to and cc) in the thread. In format username@domain.com.

`subject``string`

Subject of the thread.

`preview``string`

Text preview of the last message in the thread.

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

Attachments in the thread.

`last_message_id``string`Required

ID of the last message in the thread.

`message_count``integer`Required

Number of messages in the thread.

`size``integer`Required

Size of the thread in bytes.

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

Time at which the thread was last updated.

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

Time at which the thread was created.

`pod_id``string`Required

ID of the pod.

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.

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

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

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

Request

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

Response 200

## [Delete Thread](/content/docs/reference/api/threads\#delete-thread-1/index.html)

http

```
DELETE /v0/threads/{thread_id}
```

Permanently deletes the thread and its messages (up to 500).

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

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

FieldDescription

`thread_id``string`Required

ID of the thread.

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

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

FieldDescription

`ok``true`Required

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

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

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

Request

```
curl -X DELETE "https://api.machinemail.dev/v0/threads/thd_01k6x3a1fz0000c9k5ns1x4e6g" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

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

On this page

[List Threads](/content/docs/reference/api/threads#list-threads/index.html) [Search Threads](/content/docs/reference/api/threads#search-threads/index.html) [Get Thread](/content/docs/reference/api/threads#get-thread/index.html) [Update Thread](/content/docs/reference/api/threads#update-thread/index.html) [Delete Thread](/content/docs/reference/api/threads#delete-thread/index.html) [List Threads in Pod](/content/docs/reference/api/threads#list-threads-in-pod/index.html) [Search Threads in Pod](/content/docs/reference/api/threads#search-threads-in-pod/index.html) [Get Thread in Pod](/content/docs/reference/api/threads#get-thread-in-pod/index.html) [Update Thread in Pod](/content/docs/reference/api/threads#update-thread-in-pod/index.html) [Delete Thread in Pod](/content/docs/reference/api/threads#delete-thread-in-pod/index.html) [List Threads in Pod](/content/docs/reference/api/threads#list-threads-in-pod-1/index.html) [Search Threads in Pod](/content/docs/reference/api/threads#search-threads-in-pod-1/index.html) [Get Thread in Pod](/content/docs/reference/api/threads#get-thread-in-pod-1/index.html) [Update Thread in Pod](/content/docs/reference/api/threads#update-thread-in-pod-1/index.html) [Delete Thread in Pod](/content/docs/reference/api/threads#delete-thread-in-pod-1/index.html) [List Threads](/content/docs/reference/api/threads#list-threads-1/index.html) [Search Threads](/content/docs/reference/api/threads#search-threads-1/index.html) [Get Thread](/content/docs/reference/api/threads#get-thread-1/index.html) [Update Thread](/content/docs/reference/api/threads#update-thread-1/index.html) [Delete Thread](/content/docs/reference/api/threads#delete-thread-1/index.html)

100% readTop