> For the complete documentation index, see [llms.txt](https://docs.mailtrap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailtrap.io/developers/inbound/threads.md).
# Threads
A thread groups the inbound and sent messages that belong to the same conversation. Use these endpoints to page through an inbox's threads, fetch a single thread with its messages embedded, or delete a thread.
## List threads
> Returns the inbox's conversation threads, ordered by most recent\
> activity first.\
> \
> Only threads and messages within your plan's retention window are\
> included; the per-thread aggregates (message count, size, senders,\
> recipients, attachments) are computed over those accessible messages.\
> \
> Results use cursor pagination. When more results are available the\
> response includes a \`last\_id\`; pass it back as the \`last\_id\` query\
> parameter to get the next page. When \`last\_id\` is \`null\` you have\
> reached the end.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"threads","description":"A thread groups the inbound and sent messages that belong to the\nsame conversation. Use these endpoints to page through an inbox's\nthreads, fetch a single thread with its messages embedded, or delete a\nthread.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"inbox_id":{"name":"inbox_id","in":"path","required":true,"description":"Inbound inbox ID","schema":{"type":"integer"}}},"schemas":{"ThreadsListResponse":{"type":"object","required":["data","total_count","last_id"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ThreadSummary"}},"total_count":{"type":"integer","description":"Total number of threads matching the query."},"last_id":{"type":["string","null"],"description":"Cursor for the next page. `null` when there are no more results.\n"}}},"ThreadSummary":{"type":"object","description":"Summary of a thread. All aggregates are computed over the messages you\ncan still access (those within the plan's retention window).\n","properties":{"id":{"type":"string"},"subject":{"type":["string","null"],"description":"Subject of the thread's root message."},"message_count":{"type":"integer","description":"Number of accessible messages in the thread. Messages sent together\n(reply-all fan-out) count once.\n"},"size":{"type":"integer","description":"Combined size of the accessible messages, in bytes."},"first_message_at":{"type":"string","format":"date-time"},"last_received_at":{"type":["string","null"],"format":"date-time","description":"When the most recent inbound message arrived, if any."},"last_sent_at":{"type":["string","null"],"format":"date-time","description":"When the most recent message was sent, if any."},"last_activity_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent message in either direction."},"last_message_id":{"type":["string","null"],"description":"ID of the most recent accessible message in the thread."},"senders":{"type":"array","description":"Distinct `from` addresses across the accessible messages.","items":{"type":"string"}},"recipients":{"type":"array","description":"Distinct `to`/`cc`/`bcc` addresses across the accessible messages.","items":{"type":"string"}},"attachments":{"type":"array","description":"Attachments across the accessible messages, with download URLs.","items":{"$ref":"#/components/schemas/AttachmentWithDownloadUrl"}}}},"AttachmentWithDownloadUrl":{"allOf":[{"$ref":"#/components/schemas/Attachment"},{"type":"object","properties":{"download_url":{"type":["string","null"],"format":"uri","description":"URL to download the attachment. Expires after one hour."},"download_url_expires_at":{"type":["string","null"],"format":"date-time"}}}]},"Attachment":{"type":"object","properties":{"attachment_id":{"type":"string"},"size":{"type":["integer","null"]},"filename":{"type":["string","null"]},"content_type":{"type":["string","null"]},"content_disposition":{"type":["string","null"],"enum":["attachment","inline",null]},"content_id":{"type":["string","null"],"description":"`Content-ID` header value, used to reference inline attachments\nfrom the HTML body.\n"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/inbound/inboxes/{inbox_id}/threads":{"get":{"operationId":"listInboundThreads","summary":"List threads","description":"Returns the inbox's conversation threads, ordered by most recent\nactivity first.\n\nOnly threads and messages within your plan's retention window are\nincluded; the per-thread aggregates (message count, size, senders,\nrecipients, attachments) are computed over those accessible messages.\n\nResults use cursor pagination. When more results are available the\nresponse includes a `last_id`; pass it back as the `last_id` query\nparameter to get the next page. When `last_id` is `null` you have\nreached the end.\n","tags":["threads"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"name":"last_id","in":"query","required":false,"description":"Cursor from the previous response's `last_id`. Omit on the first\nrequest.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"List of threads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadsListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Get a thread
> Returns a single thread with its messages embedded, ordered oldest\
> first.\
> \
> Each message carries a \`visibility\_status\`:\
> \
> \- \`available\` — the message is within your plan's retention window. The\
> full envelope, subject, RFC headers, decoded bodies, and attachment\
> download URLs are included; sent messages also carry their\
> delivery lifecycle (\`delivery\_status\`, \`delivered\_at\`, \`bounced\_at\`).\
> \- \`placeholder\` — the message is outside the retention window. Only\
> \`visibility\_status\` and \`direction\` are returned; every other field is\
> omitted and no attachment download URLs are issued.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"threads","description":"A thread groups the inbound and sent messages that belong to the\nsame conversation. Use these endpoints to page through an inbox's\nthreads, fetch a single thread with its messages embedded, or delete a\nthread.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"inbox_id":{"name":"inbox_id","in":"path","required":true,"description":"Inbound inbox ID","schema":{"type":"integer"}},"thread_id":{"name":"id","in":"path","required":true,"description":"Inbound thread ID","schema":{"type":"string"}}},"schemas":{"Thread":{"allOf":[{"$ref":"#/components/schemas/ThreadSummary"},{"type":"object","properties":{"messages":{"type":"array","description":"The thread's messages, ordered oldest first.","items":{"$ref":"#/components/schemas/ThreadMessage"}}}}]},"ThreadSummary":{"type":"object","description":"Summary of a thread. All aggregates are computed over the messages you\ncan still access (those within the plan's retention window).\n","properties":{"id":{"type":"string"},"subject":{"type":["string","null"],"description":"Subject of the thread's root message."},"message_count":{"type":"integer","description":"Number of accessible messages in the thread. Messages sent together\n(reply-all fan-out) count once.\n"},"size":{"type":"integer","description":"Combined size of the accessible messages, in bytes."},"first_message_at":{"type":"string","format":"date-time"},"last_received_at":{"type":["string","null"],"format":"date-time","description":"When the most recent inbound message arrived, if any."},"last_sent_at":{"type":["string","null"],"format":"date-time","description":"When the most recent message was sent, if any."},"last_activity_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent message in either direction."},"last_message_id":{"type":["string","null"],"description":"ID of the most recent accessible message in the thread."},"senders":{"type":"array","description":"Distinct `from` addresses across the accessible messages.","items":{"type":"string"}},"recipients":{"type":"array","description":"Distinct `to`/`cc`/`bcc` addresses across the accessible messages.","items":{"type":"string"}},"attachments":{"type":"array","description":"Attachments across the accessible messages, with download URLs.","items":{"$ref":"#/components/schemas/AttachmentWithDownloadUrl"}}}},"AttachmentWithDownloadUrl":{"allOf":[{"$ref":"#/components/schemas/Attachment"},{"type":"object","properties":{"download_url":{"type":["string","null"],"format":"uri","description":"URL to download the attachment. Expires after one hour."},"download_url_expires_at":{"type":["string","null"],"format":"date-time"}}}]},"Attachment":{"type":"object","properties":{"attachment_id":{"type":"string"},"size":{"type":["integer","null"]},"filename":{"type":["string","null"]},"content_type":{"type":["string","null"]},"content_disposition":{"type":["string","null"],"enum":["attachment","inline",null]},"content_id":{"type":["string","null"],"description":"`Content-ID` header value, used to reference inline attachments\nfrom the HTML body.\n"}}},"ThreadMessage":{"type":"object","description":"A message in a thread. `placeholder` entries (outside the retention\nwindow) carry only `visibility_status` and `direction`. `available`\nentries add the full envelope, subject, RFC headers, bodies, and\nattachments; `available` sent entries additionally carry the\ndelivery lifecycle.\n","required":["visibility_status","direction"],"properties":{"visibility_status":{"type":"string","enum":["available","placeholder"]},"direction":{"type":"string","enum":["inbound","outbound"]},"id":{"type":"string","description":"For inbound messages, the Mailtrap object ID. For sent messages,\nthe Email API message UUID.\n"},"message_group_id":{"type":["string","null"],"description":"Groups the copies of one logical message that was fanned out to\nmultiple recipients (e.g. a reply-all). Messages sharing a\n`message_group_id` count once toward the thread's `message_count`.\n`null` for a standalone message.\n"},"subject":{"type":["string","null"]},"rfc_message_id":{"type":["string","null"],"description":"Value of the `Message-ID` header."},"in_reply_to":{"type":["string","null"]},"references":{"type":"array","items":{"type":"string"}},"from":{"type":["string","null"]},"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"reply_to":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"email_size":{"type":"integer","description":"Size of the message in bytes."},"text_body":{"type":["string","null"],"description":"Decoded plain-text body. `null` when the message has no text part."},"html_body":{"type":["string","null"],"description":"Decoded HTML body. `null` when the message has no HTML part."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentWithDownloadUrl"}},"delivery_status":{"type":["string","null"],"description":"Delivery status. Sent messages only."},"delivered_at":{"type":["string","null"],"format":"date-time","description":"When the message was delivered. Sent messages only."},"bounced_at":{"type":["string","null"],"format":"date-time","description":"When the message hard-bounced, if it did. Sent messages only."}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/inbound/inboxes/{inbox_id}/threads/{id}":{"get":{"operationId":"getInboundThread","summary":"Get a thread","description":"Returns a single thread with its messages embedded, ordered oldest\nfirst.\n\nEach message carries a `visibility_status`:\n\n- `available` — the message is within your plan's retention window. The\n full envelope, subject, RFC headers, decoded bodies, and attachment\n download URLs are included; sent messages also carry their\n delivery lifecycle (`delivery_status`, `delivered_at`, `bounced_at`).\n- `placeholder` — the message is outside the retention window. Only\n `visibility_status` and `direction` are returned; every other field is\n omitted and no attachment download URLs are issued.\n","tags":["threads"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"$ref":"#/components/parameters/thread_id"}],"responses":{"200":{"description":"Thread details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Thread"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Delete a thread
> Delete a thread. Inbound messages in the thread are removed; sent\
> messages are preserved.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"threads","description":"A thread groups the inbound and sent messages that belong to the\nsame conversation. Use these endpoints to page through an inbox's\nthreads, fetch a single thread with its messages embedded, or delete a\nthread.\n"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"inbox_id":{"name":"inbox_id","in":"path","required":true,"description":"Inbound inbox ID","schema":{"type":"integer"}},"thread_id":{"name":"id","in":"path","required":true,"description":"Inbound thread ID","schema":{"type":"string"}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"string"}}}}},"paths":{"/api/inbound/inboxes/{inbox_id}/threads/{id}":{"delete":{"operationId":"deleteInboundThread","summary":"Delete a thread","description":"Delete a thread. Inbound messages in the thread are removed; sent\nmessages are preserved.\n","tags":["threads"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"$ref":"#/components/parameters/thread_id"}],"responses":{"204":{"description":"Thread deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.mailtrap.io/developers/inbound/threads.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.