Messages

List and inspect 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, or delete a message 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

HeaderAuthBearerAuth

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.

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

get

/api/inbound/inboxes/{inbox_id}/messages

cURL

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": "[email protected]",
      "to": [
        "[email protected]"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": null,
      "subject": "Hello",
      "message_id": "<[email protected]>",
      "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",
      "attachments": [
        {
          "attachment_id": "att-1",
          "size": 1024,
          "filename": "logo.png",
          "content_type": "image/png",
          "content_disposition": "inline",
          "content_id": "[email protected]"
        }
      ]
    }
  ],
  "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

HeaderAuthBearerAuth

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: [email protected]

tostring[]OptionalExample: ["[email protected]"]

ccstring[]Optional

bccstring[]Optional

reply_tostring · nullableOptional

subjectstring · nullableOptionalExample: Hello

message_idstring · nullableOptional

Value of the original Message-ID header.

Example: <[email protected]>

in_reply_tostring · nullableOptional

referencesstring[]Optional

headersobject · nullableOptional

Selected headers from the original message, lowercased.

Example: {"mime-version":"1.0","return-path":"<[email protected]>"}

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

raw_message_urlstring · nullableOptional

Presigned 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

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

get

/api/inbound/inboxes/{inbox_id}/messages/{id}

cURL

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": "[email protected]",
  "to": [
    "[email protected]"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": null,
  "subject": "Hello",
  "message_id": "<[email protected]>",
  "in_reply_to": null,
  "references": [],
  "headers": {
    "mime-version": "1.0",
    "return-path": "<[email protected]>"
  },
  "size": 4096,
  "html_size": 512,
  "text_size": 128,
  "received_at": "2026-05-08T10:30:00.000Z",
  "attachments": [
    {
      "attachment_id": "att-1",
      "size": 1024,
      "filename": "logo.png",
      "content_type": "image/png",
      "content_disposition": "inline",
      "content_id": "[email protected]",
      "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

HeaderAuthBearerAuth

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

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

delete

/api/inbound/inboxes/{inbox_id}/messages/{id}

cURL

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

No content