Ctrlk
ProductPricingContact supportOpen app
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Messages

List, inspect, and respond to received 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

get

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.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Path parameters
inbox_idintegerRequired

Inbound inbox ID

Example: 1
Query parameters
last_idstringOptional

ID of the last message from the previous page. Pass the last_id value returned by the previous response to fetch the next page. Omit on the first request.

Example: 1700000000000123
Responses
200

List of messages

application/json
total_countintegerRequired

Total number of messages within the retention window.

Example: 1
last_idstring · nullableRequired

Cursor for the next page. null when there are no more results.

get/api/inbound/inboxes/{inbox_id}/messages
curl -X GET 'https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "1700000000000123",
      "inbox_id": 1,
      "from": "sender@example.com",
      "to": [
        "support-tickets-1a2b3c4d@inbound-mailtrap.io"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": null,
      "subject": "Hello",
      "rfc_message_id": "<abc@sender.example>",
      "in_reply_to": null,
      "references": [],
      "headers": {
        "mime-version": "1.0"
      },
      "size": 4096,
      "html_size": 512,
      "text_size": 128,
      "received_at": "2026-05-08T10:30:00.000Z",
      "thread_id": "1700000000000124",
      "attachments": [
        {
          "attachment_id": "att-1",
          "size": 1024,
          "filename": "logo.png",
          "content_type": "image/png",
          "content_disposition": "inline",
          "content_id": "logo@example.com"
        }
      ]
    }
  ],
  "total_count": 1,
  "last_id": null
}

Get a message

get

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.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Path parameters
inbox_idintegerRequired

Inbound inbox ID

Example: 1
idstringRequired

Inbound message ID

Example: 1700000000000123
Responses
200

Message details

application/json
idstringOptional

Mailtrap object ID for the message (not the Message-ID header value).

Example: 1700000000000123
inbox_idintegerOptionalExample: 1
fromstring · nullableOptionalExample: sender@example.com
tostring[]OptionalExample: ["support-tickets-1a2b3c4d@inbound-mailtrap.io"]
ccstring[]Optional
bccstring[]Optional
reply_tostring · nullableOptional
subjectstring · nullableOptionalExample: Hello
rfc_message_idstring · nullableOptional

Value of the original Message-ID header.

Example: <abc@sender.example>
in_reply_tostring · nullableOptional
referencesstring[]Optional
headersobject · nullableOptional

Selected headers from the original message, lowercased.

Example: {"mime-version":"1.0","return-path":"<sender@example.com>"}
sizeinteger · nullableOptional

Total size of the raw message in bytes.

Example: 4096
html_sizeinteger · nullableOptional

Size of the HTML body in bytes. Zero if the message has no HTML part.

Example: 512
text_sizeinteger · nullableOptional

Size of the plain-text body in bytes. Zero if the message has no text part.

Example: 128
received_atstring · date-timeOptionalExample: 2026-05-08T10:30:00.000Z
thread_idstring · nullableOptional

ID of the thread this message belongs to. Use it with the Threads endpoints to fetch the full conversation.

Example: 1700000000000124
raw_message_urlstring · nullableOptional

URL to download the raw .eml file. Expires after one hour.

Example: https://s3.amazonaws.com/inbound-mail/raw.eml?X-Amz-Signature=...
raw_message_expires_atstring · nullableOptionalExample: 2026-05-08T11:30:00.000Z
html_bodystring · nullableOptional

Decoded HTML body. null when the message has no HTML part.

Example: <html><body>Hello</body></html>
text_bodystring · nullableOptional

Decoded plain-text body. null when the message has no text part.

Example: Hello
get/api/inbound/inboxes/{inbox_id}/messages/{id}
curl -X GET https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "1700000000000123",
  "inbox_id": 1,
  "from": "sender@example.com",
  "to": [
    "support-tickets-1a2b3c4d@inbound-mailtrap.io"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": null,
  "subject": "Hello",
  "rfc_message_id": "<abc@sender.example>",
  "in_reply_to": null,
  "references": [],
  "headers": {
    "mime-version": "1.0",
    "return-path": "<sender@example.com>"
  },
  "size": 4096,
  "html_size": 512,
  "text_size": 128,
  "received_at": "2026-05-08T10:30:00.000Z",
  "thread_id": "1700000000000124",
  "attachments": [
    {
      "attachment_id": "att-1",
      "size": 1024,
      "filename": "logo.png",
      "content_type": "image/png",
      "content_disposition": "inline",
      "content_id": "logo@example.com",
      "download_url": "https://s3.amazonaws.com/inbound-mail/att-1?X-Amz-Signature=...",
      "download_url_expires_at": "2026-05-08T11:30:00.000Z"
    }
  ],
  "raw_message_url": "https://s3.amazonaws.com/inbound-mail/raw.eml?X-Amz-Signature=...",
  "raw_message_expires_at": "2026-05-08T11:30:00.000Z",
  "html_body": "<html><body>Hello</body></html>",
  "text_body": "Hello"
}

Delete a message

delete

Permanently delete an inbound message and its stored body and attachments.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Path parameters
inbox_idintegerRequired

Inbound inbox ID

Example: 1
idstringRequired

Inbound message ID

Example: 1700000000000123
Responses
204

Message deleted

No content
delete/api/inbound/inboxes/{inbox_id}/messages/{id}
curl -X DELETE https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

No content

Reply to a message

post

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.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Path parameters
inbox_idintegerRequired

Inbound inbox ID

Example: 1
idstringRequired

Inbound message ID

Example: 1700000000000123
Body

Options for the sent message. All fields are optional. reply and reply_all must carry a body (text and/or html); forward may omit it, since the original message is quoted automatically. forward also requires at least one recipient in to. Addresses use the Email Sending API { email, name } shape.

textstringOptional

Plain-text body.

Example: Thanks for reaching out. We are looking into it.
htmlstringOptional

HTML body.

Example: <p>Thanks for reaching out. We are looking into it.</p>
categorystring · max: 255Optional

Email API category for the sent message.

Example: Support reply
Responses
201

Message queued for delivery. Returns the UUID(s) the Email API assigned to the sent message, one per recipient.

application/json
message_idsstring[]Required

UUIDs assigned by the Email API to the sent message, one per recipient. These are the sent message's UUIDs — not the inbound message ID acted on, nor an RFC Message-ID header value.

Example: ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"]
post/api/inbound/inboxes/{inbox_id}/messages/{id}/reply
curl -X POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{id}/reply \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "Thanks for reaching out. We are looking into it." }'

{
  "message_ids": [
    "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  ]
}

Reply all to a message

post

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:.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Path parameters
inbox_idintegerRequired

Inbound inbox ID

Example: 1
idstringRequired

Inbound message ID

Example: 1700000000000123
Body

Options for the sent message. All fields are optional. reply and reply_all must carry a body (text and/or html); forward may omit it, since the original message is quoted automatically. forward also requires at least one recipient in to. Addresses use the Email Sending API { email, name } shape.

textstringOptional

Plain-text body.

Example: Thanks for reaching out. We are looking into it.
htmlstringOptional

HTML body.

Example: <p>Thanks for reaching out. We are looking into it.</p>
categorystring · max: 255Optional

Email API category for the sent message.

Example: Support reply
Responses
201

Message queued for delivery. Returns the UUID(s) the Email API assigned to the sent message, one per recipient.

application/json
message_idsstring[]Required

UUIDs assigned by the Email API to the sent message, one per recipient. These are the sent message's UUIDs — not the inbound message ID acted on, nor an RFC Message-ID header value.

Example: ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"]
post/api/inbound/inboxes/{inbox_id}/messages/{id}/reply_all
curl -X POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{id}/reply_all \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "Thanks all. Adding my colleague to the thread." }'

{
  "message_ids": [
    "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  ]
}

Forward a message

post

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.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Path parameters
inbox_idintegerRequired

Inbound inbox ID

Example: 1
idstringRequired

Inbound message ID

Example: 1700000000000123
Body

Options for the sent message. All fields are optional. reply and reply_all must carry a body (text and/or html); forward may omit it, since the original message is quoted automatically. forward also requires at least one recipient in to. Addresses use the Email Sending API { email, name } shape.

textstringOptional

Plain-text body.

Example: Thanks for reaching out. We are looking into it.
htmlstringOptional

HTML body.

Example: <p>Thanks for reaching out. We are looking into it.</p>
categorystring · max: 255Optional

Email API category for the sent message.

Example: Support reply
Responses
201

Message queued for delivery. Returns the UUID(s) the Email API assigned to the sent message, one per recipient.

application/json
message_idsstring[]Required

UUIDs assigned by the Email API to the sent message, one per recipient. These are the sent message's UUIDs — not the inbound message ID acted on, nor an RFC Message-ID header value.

Example: ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"]
post/api/inbound/inboxes/{inbox_id}/messages/{id}/forward
curl -X POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{id}/forward \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": [{ "email": "colleague@example.com" }], "text": "Please take a look at the message below." }'

{
  "message_ids": [
    "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  ]
}
PreviousInboxes
NextThreads

Last updated

Was this helpful?