> 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, reply to or forward a message, or delete one 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, reply to or forward a message, or delete one you no longer\nneed.\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"]},"rfc_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"},"thread_id":{"type":["string","null"],"description":"ID of the thread this message belongs to. Use it with the Threads\nendpoints to fetch the full conversation.\n"},"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, reply to or forward a message, or delete one you no longer\nneed.\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":"URL to download the raw `.eml` file. Expires after one 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"]},"rfc_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"},"thread_id":{"type":["string","null"],"description":"ID of the thread this message belongs to. Use it with the Threads\nendpoints to fetch the full conversation.\n"},"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":"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, reply to or forward a message, or delete one you no longer\nneed.\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"}}}}}}
```
## Reply to a message
> Send a reply to an inbound message. The reply is threaded to the\
> original and its subject is prefixed with \`Re:\` (unless it already\
> starts with one).\
> \
> By default the reply is addressed to the original sender (its\
> \`Reply-To\`, or \`From\` when absent). Pass \`to\` to override the\
> recipients — an explicit empty array sends to \`cc\`/\`bcc\` only — or add\
> \`cc\`/\`bcc\`.\
> \
> The sender depends on the inbox type:\
> \
> \- \*\*Mailtrap-hosted inbox\*\* — always sends from the inbox's own\
> generated address. Supplying \`from\` is rejected with \`400\`.\
> \- \*\*Custom-domain inbox\*\* — you supply \`from\`, whose address must\
> belong to the inbox's domain.
```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, reply to or forward a message, or delete one you no longer\nneed.\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":{"SendMessageInput":{"type":"object","description":"Options for the sent message. All fields are optional. `reply` and\n`reply_all` must carry a body (`text` and/or `html`); `forward` may omit\nit, since the original message is quoted automatically. `forward` also\nrequires at least one recipient in `to`. Addresses use the Email\nSending API `{ email, name }` shape.\n","properties":{"from":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Sender address. Rejected for Mailtrap-hosted inboxes (they always\nsend from their own address); required for custom-domain inboxes,\nwhere the address must belong to the inbox's domain.\n"},"to":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"cc":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"bcc":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"reply_to":{"$ref":"#/components/schemas/Address"},"text":{"type":"string","description":"Plain-text body."},"html":{"type":"string","description":"HTML body."},"category":{"type":"string","maxLength":255,"description":"Email API category for the sent message."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/EmailAttachment"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom headers to add to the sent message."},"custom_variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Email API custom variables for the sent message."}}},"Address":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"EmailAttachment":{"type":"object","required":["content","filename"],"properties":{"content":{"type":"string","description":"Base64-encoded attachment content."},"filename":{"type":"string"},"type":{"type":"string","description":"MIME type of the attachment."},"disposition":{"type":"string","enum":["attachment","inline"],"default":"attachment"},"content_id":{"type":"string","description":"`Content-ID` used to reference an inline attachment from the HTML\nbody. Only relevant when `disposition` is `inline`.\n"}}},"SendMessageResult":{"type":"object","required":["message_ids"],"properties":{"message_ids":{"type":"array","description":"UUIDs assigned by the Email API to the sent message, one per\nrecipient. These are the sent message's UUIDs — not the inbound\nmessage ID acted on, nor an RFC `Message-ID` header value.\n","items":{"type":"string"}}}},"SendMessageError":{"type":"object","properties":{"errors":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"SendMessageAccepted":{"description":"Message queued for delivery. Returns the UUID(s) the Email API\nassigned to the sent message, one per recipient.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResult"}}}},"SendMessageBadRequest":{"description":"The message could not be sent. Returned for an invalid sender (for\nexample a `from` on a Mailtrap-hosted inbox, or one outside the inbox's\ndomain) and for validation errors rejected by the Email API.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SendMessageForbidden":{"description":"The caller lacks permission on the inbox, or the inbox's monthly sending\nlimit has been reached.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PayloadTooLarge":{"description":"The message exceeds the maximum allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"TooManyRequests":{"description":"Too many requests. Retry after a short delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}}}},"paths":{"/api/inbound/inboxes/{inbox_id}/messages/{id}/reply":{"post":{"operationId":"replyToInboundMessage","summary":"Reply to a message","description":"Send a reply to an inbound message. The reply is threaded to the\noriginal and its subject is prefixed with `Re:` (unless it already\nstarts with one).\n\nBy default the reply is addressed to the original sender (its\n`Reply-To`, or `From` when absent). Pass `to` to override the\nrecipients — an explicit empty array sends to `cc`/`bcc` only — or add\n`cc`/`bcc`.\n\nThe sender depends on the inbox type:\n\n- **Mailtrap-hosted inbox** — always sends from the inbox's own\n generated address. Supplying `from` is rejected with `400`.\n- **Custom-domain inbox** — you supply `from`, whose address must\n belong to the inbox's domain.\n","tags":["messages"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"$ref":"#/components/parameters/message_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageInput"}}}},"responses":{"201":{"$ref":"#/components/responses/SendMessageAccepted"},"400":{"$ref":"#/components/responses/SendMessageBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SendMessageForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```
## Reply all to a message
> Send a reply to an inbound message and copy the original's other\
> recipients. Behaves exactly like the Reply to a message operation,\
> except \`cc\` defaults to the original's \`To\` + \`Cc\` — minus the inbox's\
> own addresses and the sender (already in \`To\`).\
> \
> Pass \`to\`, \`cc\`, or \`bcc\` to override the computed recipients. As with a\
> plain reply, the subject is prefixed with \`Re:\`.
```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, reply to or forward a message, or delete one you no longer\nneed.\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":{"SendMessageInput":{"type":"object","description":"Options for the sent message. All fields are optional. `reply` and\n`reply_all` must carry a body (`text` and/or `html`); `forward` may omit\nit, since the original message is quoted automatically. `forward` also\nrequires at least one recipient in `to`. Addresses use the Email\nSending API `{ email, name }` shape.\n","properties":{"from":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Sender address. Rejected for Mailtrap-hosted inboxes (they always\nsend from their own address); required for custom-domain inboxes,\nwhere the address must belong to the inbox's domain.\n"},"to":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"cc":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"bcc":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"reply_to":{"$ref":"#/components/schemas/Address"},"text":{"type":"string","description":"Plain-text body."},"html":{"type":"string","description":"HTML body."},"category":{"type":"string","maxLength":255,"description":"Email API category for the sent message."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/EmailAttachment"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom headers to add to the sent message."},"custom_variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Email API custom variables for the sent message."}}},"Address":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"EmailAttachment":{"type":"object","required":["content","filename"],"properties":{"content":{"type":"string","description":"Base64-encoded attachment content."},"filename":{"type":"string"},"type":{"type":"string","description":"MIME type of the attachment."},"disposition":{"type":"string","enum":["attachment","inline"],"default":"attachment"},"content_id":{"type":"string","description":"`Content-ID` used to reference an inline attachment from the HTML\nbody. Only relevant when `disposition` is `inline`.\n"}}},"SendMessageResult":{"type":"object","required":["message_ids"],"properties":{"message_ids":{"type":"array","description":"UUIDs assigned by the Email API to the sent message, one per\nrecipient. These are the sent message's UUIDs — not the inbound\nmessage ID acted on, nor an RFC `Message-ID` header value.\n","items":{"type":"string"}}}},"SendMessageError":{"type":"object","properties":{"errors":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"SendMessageAccepted":{"description":"Message queued for delivery. Returns the UUID(s) the Email API\nassigned to the sent message, one per recipient.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResult"}}}},"SendMessageBadRequest":{"description":"The message could not be sent. Returned for an invalid sender (for\nexample a `from` on a Mailtrap-hosted inbox, or one outside the inbox's\ndomain) and for validation errors rejected by the Email API.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SendMessageForbidden":{"description":"The caller lacks permission on the inbox, or the inbox's monthly sending\nlimit has been reached.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PayloadTooLarge":{"description":"The message exceeds the maximum allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"TooManyRequests":{"description":"Too many requests. Retry after a short delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}}}},"paths":{"/api/inbound/inboxes/{inbox_id}/messages/{id}/reply_all":{"post":{"operationId":"replyAllToInboundMessage","summary":"Reply all to a message","description":"Send a reply to an inbound message and copy the original's other\nrecipients. Behaves exactly like the Reply to a message operation,\nexcept `cc` defaults to the original's `To` + `Cc` — minus the inbox's\nown addresses and the sender (already in `To`).\n\nPass `to`, `cc`, or `bcc` to override the computed recipients. As with a\nplain reply, the subject is prefixed with `Re:`.\n","tags":["messages"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"$ref":"#/components/parameters/message_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageInput"}}}},"responses":{"201":{"$ref":"#/components/responses/SendMessageAccepted"},"400":{"$ref":"#/components/responses/SendMessageBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SendMessageForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```
## Forward a message
> Forward an inbound message to new recipients. The subject is prefixed\
> with \`Fwd:\` (unless it already starts with one). The original message is\
> always carried along: its rendered body is quoted below your optional\
> note and its attachments are re-attached (any attachments you supply are\
> added on top).\
> \
> A forward has no implicit recipient — you must address it with \`to\`\
> (and optionally \`cc\`/\`bcc\`). The \`from\` rules match those of the Reply operation:\
> rejected for Mailtrap-hosted inboxes, required-and-domain-bound for\
> custom-domain inboxes.
```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, reply to or forward a message, or delete one you no longer\nneed.\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":{"SendMessageInput":{"type":"object","description":"Options for the sent message. All fields are optional. `reply` and\n`reply_all` must carry a body (`text` and/or `html`); `forward` may omit\nit, since the original message is quoted automatically. `forward` also\nrequires at least one recipient in `to`. Addresses use the Email\nSending API `{ email, name }` shape.\n","properties":{"from":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Sender address. Rejected for Mailtrap-hosted inboxes (they always\nsend from their own address); required for custom-domain inboxes,\nwhere the address must belong to the inbox's domain.\n"},"to":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"cc":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"bcc":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"reply_to":{"$ref":"#/components/schemas/Address"},"text":{"type":"string","description":"Plain-text body."},"html":{"type":"string","description":"HTML body."},"category":{"type":"string","maxLength":255,"description":"Email API category for the sent message."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/EmailAttachment"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom headers to add to the sent message."},"custom_variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Email API custom variables for the sent message."}}},"Address":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"EmailAttachment":{"type":"object","required":["content","filename"],"properties":{"content":{"type":"string","description":"Base64-encoded attachment content."},"filename":{"type":"string"},"type":{"type":"string","description":"MIME type of the attachment."},"disposition":{"type":"string","enum":["attachment","inline"],"default":"attachment"},"content_id":{"type":"string","description":"`Content-ID` used to reference an inline attachment from the HTML\nbody. Only relevant when `disposition` is `inline`.\n"}}},"SendMessageResult":{"type":"object","required":["message_ids"],"properties":{"message_ids":{"type":"array","description":"UUIDs assigned by the Email API to the sent message, one per\nrecipient. These are the sent message's UUIDs — not the inbound\nmessage ID acted on, nor an RFC `Message-ID` header value.\n","items":{"type":"string"}}}},"SendMessageError":{"type":"object","properties":{"errors":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"SendMessageAccepted":{"description":"Message queued for delivery. Returns the UUID(s) the Email API\nassigned to the sent message, one per recipient.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResult"}}}},"SendMessageBadRequest":{"description":"The message could not be sent. Returned for an invalid sender (for\nexample a `from` on a Mailtrap-hosted inbox, or one outside the inbox's\ndomain) and for validation errors rejected by the Email API.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SendMessageForbidden":{"description":"The caller lacks permission on the inbox, or the inbox's monthly sending\nlimit has been reached.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PayloadTooLarge":{"description":"The message exceeds the maximum allowed size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}},"TooManyRequests":{"description":"Too many requests. Retry after a short delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageError"}}}}}},"paths":{"/api/inbound/inboxes/{inbox_id}/messages/{id}/forward":{"post":{"operationId":"forwardInboundMessage","summary":"Forward a message","description":"Forward an inbound message to new recipients. The subject is prefixed\nwith `Fwd:` (unless it already starts with one). The original message is\nalways carried along: its rendered body is quoted below your optional\nnote and its attachments are re-attached (any attachments you supply are\nadded on top).\n\nA forward has no implicit recipient — you must address it with `to`\n(and optionally `cc`/`bcc`). The `from` rules match those of the Reply operation:\nrejected for Mailtrap-hosted inboxes, required-and-domain-bound for\ncustom-domain inboxes.\n","tags":["messages"],"parameters":[{"$ref":"#/components/parameters/inbox_id"},{"$ref":"#/components/parameters/message_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageInput"}}}},"responses":{"201":{"$ref":"#/components/responses/SendMessageAccepted"},"400":{"$ref":"#/components/responses/SendMessageBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SendMessageForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```
---
# 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/messages.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.