> 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/get-a-thread.md). # 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 outcome in `delivery`; received messages carry their forward-rule outcomes in `forwards`. * `placeholder` — the message is outside the retention window, or is no longer stored. Only `visibility_status` and `direction` are returned; every other field is omitted and no attachment download URLs are issued. The thread-level aggregates (`message_count`, `size`, `senders`, `recipients`, `attachments`, `last_message_id`) are computed over the `available` messages only. ```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). The\n`subject` and the `*_at` timestamps describe the whole thread,\nincluding messages outside the retention window.\n","required":["id","subject","message_count","size","first_message_at","last_received_at","last_sent_at","last_activity_at","last_message_id","senders","recipients","attachments"],"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, or no longer stored) carry only `visibility_status` and\n`direction`. `available` entries add the full envelope, subject, RFC\nheaders, bodies, and attachments. `available` sent (`outbound`)\nentries additionally carry `delivery`; `available` received\n(`inbound`) entries additionally carry `forwards`.\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":{"$ref":"#/components/schemas/ThreadMessageDelivery"},"forwards":{"type":"array","description":"Outcome of each forward-rule destination this message was\nforwarded to. Received (`inbound`) messages only; an empty array\nwhen no forward rule matched.\n","items":{"$ref":"#/components/schemas/ForwardOutcome"}}}},"ThreadMessageDelivery":{"type":"object","description":"Delivery outcome of a sent message. Sent (`outbound`) messages only.\n","required":["to","status","delivered_at","bounced_at"],"properties":{"to":{"type":"string","description":"Recipient address this copy of the message was sent to."},"status":{"type":"string","enum":["delivered","not_delivered","enqueued","opted_out"],"description":"Delivery status, as shown in Email Logs.\n"},"delivered_at":{"type":["string","null"],"format":"date-time","description":"When the message was delivered. `null` if it was not."},"bounced_at":{"type":["string","null"],"format":"date-time","description":"When the message hard-bounced. `null` if it did not."}}},"ForwardOutcome":{"type":"object","required":["rule_id","rule_name","destination","status","reason","message_id"],"properties":{"rule_id":{"type":"integer","description":"ID of the forward rule that selected this destination."},"rule_name":{"type":["string","null"],"description":"Name of the forward rule at the time of forwarding."},"destination":{"type":"string","description":"Address the message was forwarded to."},"status":{"type":"string","enum":["forwarded","rejected"],"description":"`forwarded` when the copy was accepted for sending; `rejected`\nwhen it could not be sent.\n"},"reason":{"type":["string","null"],"description":"Why the forward was rejected, e.g. `loop_prevention` or\n`fetch_failed`, or the rejection reason returned by the Email API.\n`null` when `status` is `forwarded`.\n"},"message_id":{"type":["string","null"],"description":"Email API UUID of the forwarded (sent) message. `null` when\n`status` is `rejected`.\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. The token lacks the permission required for this operation\n(`Access forbidden`), has no access to the account\n(`Account access forbidden`), or Email API/SMTP is not enabled for the\norganization (empty response body).\n","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 delivery\n outcome in `delivery`; received messages carry their forward-rule\n outcomes in `forwards`.\n- `placeholder` — the message is outside the retention window, or is\n no longer stored. Only `visibility_status` and `direction` are\n returned; every other field is omitted and no attachment download\n URLs are issued.\n\nThe thread-level aggregates (`message_count`, `size`, `senders`,\n`recipients`, `attachments`, `last_message_id`) are computed over the\n`available` messages only.\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"}}}}}} ``` --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.mailtrap.io/developers/inbound/threads/get-a-thread.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.