> 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/messages.md).
# Messages
Inbound messages are the emails delivered to an inbox. Use these endpoints to page through recent messages, fetch the full body and attachments, or delete a message you no longer need.
## List messages
> Returns inbound messages received by the inbox, ordered by\
> \`received\_at\` descending.\
> \
> List responses 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":"messages","description":"Inbound messages are the emails delivered to an inbox. Use these\nendpoints to page through recent messages, fetch the full body and\nattachments, or delete a message you no longer need.\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":{"MessagesListResponse":{"type":"object","required":["data","total_count","last_id"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"total_count":{"type":"integer","description":"Total number of messages within the retention window."},"last_id":{"type":["string","null"],"description":"Cursor for the next page. `null` when there are no more results.\n"}}},"Message":{"type":"object","properties":{"id":{"type":"string","description":"Mailtrap object ID for the message (not the `Message-ID` header value)."},"inbox_id":{"type":"integer"},"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"]},"subject":{"type":["string","null"]},"message_id":{"type":["string","null"],"description":"Value of the original `Message-ID` header."},"in_reply_to":{"type":["string","null"]},"references":{"type":"array","items":{"type":"string"}},"headers":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Selected headers from the original message, lowercased.\n"},"size":{"type":["integer","null"],"description":"Total size of the raw message in bytes."},"html_size":{"type":["integer","null"],"description":"Size of the HTML body in bytes. Zero if the message has no HTML part."},"text_size":{"type":["integer","null"],"description":"Size of the plain-text body in bytes. Zero if the message has no text part."},"received_at":{"type":"string","format":"date-time"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}}}},"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}/messages":{"get":{"operationId":"listInboundMessages","summary":"List messages","description":"Returns inbound messages received by the inbox, ordered by\n`received_at` descending.\n\nList responses use cursor pagination. When more results are available\nthe response 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":["messages"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"name":"last_id","in":"query","required":false,"description":"ID of the last message from the previous page. Pass the `last_id`\nvalue returned by the previous response to fetch the next page.\nOmit on the first request.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"List of messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Get a message
> Returns a single inbound message together with URLs for the\
> raw \`.eml\` file and for each attachment, plus the decoded HTML and\
> plain-text bodies. URLs expire after one hour.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"messages","description":"Inbound messages are the emails delivered to an inbox. Use these\nendpoints to page through recent messages, fetch the full body and\nattachments, or delete a message you no longer need.\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"}},"message_id":{"name":"id","in":"path","required":true,"description":"Inbound message ID","schema":{"type":"string"}}},"schemas":{"MessageDetails":{"allOf":[{"$ref":"#/components/schemas/Message"},{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentWithDownloadUrl"}},"raw_message_url":{"type":["string","null"],"format":"uri","description":"Presigned URL to download the raw `.eml` file. Expires after\none hour.\n"},"raw_message_expires_at":{"type":["string","null"],"format":"date-time"},"html_body":{"type":["string","null"],"description":"Decoded HTML body. `null` when the message has no HTML part."},"text_body":{"type":["string","null"],"description":"Decoded plain-text body. `null` when the message has no text part."}}}]},"Message":{"type":"object","properties":{"id":{"type":"string","description":"Mailtrap object ID for the message (not the `Message-ID` header value)."},"inbox_id":{"type":"integer"},"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"]},"subject":{"type":["string","null"]},"message_id":{"type":["string","null"],"description":"Value of the original `Message-ID` header."},"in_reply_to":{"type":["string","null"]},"references":{"type":"array","items":{"type":"string"}},"headers":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Selected headers from the original message, lowercased.\n"},"size":{"type":["integer","null"],"description":"Total size of the raw message in bytes."},"html_size":{"type":["integer","null"],"description":"Size of the HTML body in bytes. Zero if the message has no HTML part."},"text_size":{"type":["integer","null"],"description":"Size of the plain-text body in bytes. Zero if the message has no text part."},"received_at":{"type":"string","format":"date-time"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}}}},"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"}}},"AttachmentWithDownloadUrl":{"allOf":[{"$ref":"#/components/schemas/Attachment"},{"type":"object","properties":{"download_url":{"type":["string","null"],"format":"uri","description":"Presigned URL to download the attachment. Expires after one hour."},"download_url_expires_at":{"type":["string","null"],"format":"date-time"}}}]},"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}/messages/{id}":{"get":{"operationId":"getInboundMessage","summary":"Get a message","description":"Returns a single inbound message together with URLs for the\nraw `.eml` file and for each attachment, plus the decoded HTML and\nplain-text bodies. URLs expire after one hour.\n","tags":["messages"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"$ref":"#/components/parameters/message_id"}],"responses":{"200":{"description":"Message details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetails"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Delete a message
> Permanently delete an inbound message and its stored body and\
> attachments.
```json
{"openapi":"3.1.0","info":{"title":"Inbound","version":"2.0.0"},"tags":[{"name":"messages","description":"Inbound messages are the emails delivered to an inbox. Use these\nendpoints to page through recent messages, fetch the full body and\nattachments, or delete a message you no longer need.\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"}},"message_id":{"name":"id","in":"path","required":true,"description":"Inbound message 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}/messages/{id}":{"delete":{"operationId":"deleteInboundMessage","summary":"Delete a message","description":"Permanently delete an inbound message and its stored body and\nattachments.\n","tags":["messages"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"$ref":"#/components/parameters/message_id"}],"responses":{"204":{"description":"Message 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:
```
GET https://docs.mailtrap.io/developers/inbound/messages.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.