Threads

Group related messages into conversations

A thread groups the inbound and sent messages that belong to the same conversation. Use these endpoints to page through an inbox's threads, fetch a single thread with its messages embedded, or delete a thread.

List threads

get

Returns the inbox's conversation threads, ordered by most recent activity first.

Only threads and messages within your plan's retention window are included; the per-thread aggregates (message count, size, senders, recipients, attachments) are computed over those accessible messages.

Results 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

Cursor from the previous response's last_id. Omit on the first request.

Example: eyJsYXN0X2FjdGl2aXR5X2F0IjoxNzQ2NzAwMjAwMDAwLCJpZCI6IjE3MDAwMDAwMDAwMDAxMjMifQ

Responses

200

List of threads

application/json

total_countintegerRequired

Total number of threads matching the query.

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}/threads

cURLNode.jsPHPPythonRuby.NETJava

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

{
  "data": [
    {
      "id": "1700000000000123",
      "subject": "Support request",
      "message_count": 3,
      "size": 24576,
      "first_message_at": "2026-05-08T10:30:00.000Z",
      "last_received_at": "2026-05-08T12:05:00.000Z",
      "last_sent_at": "2026-05-08T11:40:00.000Z",
      "last_activity_at": "2026-05-08T12:05:00.000Z",
      "last_message_id": "1700000000000789",
      "senders": [
        "[e-mail]",
        "[e-mail]"
      ],
      "recipients": [
        "[e-mail]",
        "[e-mail]"
      ],
      "attachments": [
        {
          "attachment_id": "att-1",
          "filename": "invoice.pdf",
          "size": 20480,
          "content_type": "application/pdf",
          "content_disposition": "attachment",
          "content_id": null,
          "download_url": "https://s3.amazonaws.com/inbound-mail/att-1?X-Amz-Signature=...",
          "download_url_expires_at": "2026-05-08T13:05:00.000Z"
        }
      ]
    }
  ],
  "total_count": 1,
  "last_id": null
}

Get a thread

get

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 lifecycle (delivery_status, delivered_at, bounced_at).
• placeholder — the message is outside the retention window. Only visibility_status and direction are returned; every other field is omitted and no attachment download URLs are issued.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

inbox_idintegerRequired

Inbound inbox ID

Example: 1

idstringRequired

Inbound thread ID

Example: 1700000000000123

Responses

200

Thread details

application/json

Summary of a thread. All aggregates are computed over the messages you can still access (those within the plan's retention window).

idstringOptionalExample: 1700000000000123

subjectstring · nullableOptional

Subject of the thread's root message.

Example: Support request

message_countintegerOptional

Number of accessible messages in the thread. Messages sent together (reply-all fan-out) count once.

Example: 3

sizeintegerOptional

Combined size of the accessible messages, in bytes.

Example: 24576

first_message_atstring · date-timeOptionalExample: 2026-05-08T10:30:00.000Z

last_received_atstring · nullableOptional

When the most recent inbound message arrived, if any.

Example: 2026-05-08T12:05:00.000Z

last_sent_atstring · nullableOptional

When the most recent message was sent, if any.

Example: 2026-05-08T11:40:00.000Z

last_activity_atstring · date-timeOptional

Timestamp of the most recent message in either direction.

Example: 2026-05-08T12:05:00.000Z

last_message_idstring · nullableOptional

ID of the most recent accessible message in the thread.

Example: 1700000000000789

sendersstring[]Optional

Distinct from addresses across the accessible messages.

Example: ["[e-mail]","[e-mail]"]

recipientsstring[]Optional

Distinct to/cc/bcc addresses across the accessible messages.

Example: ["[e-mail]","[e-mail]"]

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

get/api/inbound/inboxes/{inbox_id}/threads/{id}

cURLNode.jsPHPPythonRuby.NETJava

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

{
  "id": "1700000000000123",
  "subject": "Support request",
  "message_count": 3,
  "size": 24576,
  "first_message_at": "2026-05-08T10:30:00.000Z",
  "last_received_at": "2026-05-08T12:05:00.000Z",
  "last_sent_at": "2026-05-08T11:40:00.000Z",
  "last_activity_at": "2026-05-08T12:05:00.000Z",
  "last_message_id": "1700000000000789",
  "senders": [
    "[e-mail]",
    "[e-mail]"
  ],
  "recipients": [
    "[e-mail]",
    "[e-mail]"
  ],
  "attachments": [
    {
      "attachment_id": "att-1",
      "filename": "invoice.pdf",
      "size": 20480,
      "content_type": "application/pdf",
      "content_disposition": "attachment",
      "content_id": null,
      "download_url": "https://s3.amazonaws.com/inbound-mail/att-1?X-Amz-Signature=...",
      "download_url_expires_at": "2026-05-08T13:05:00.000Z"
    }
  ],
  "messages": [
    {
      "visibility_status": "available",
      "direction": "inbound",
      "id": "1700000000000123",
      "subject": "Support request",
      "rfc_message_id": "<[e-mail]>",
      "in_reply_to": null,
      "references": [],
      "from": "[e-mail]",
      "to": [
        "[e-mail]"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": null,
      "created_at": "2026-05-08T10:30:00.000Z",
      "email_size": 8192,
      "text_body": "I need help with my order.",
      "html_body": "<p>I need help with my order.</p>",
      "attachments": []
    },
    {
      "visibility_status": "available",
      "direction": "outbound",
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "subject": "Re: Support request",
      "rfc_message_id": "<[e-mail]>",
      "in_reply_to": "<[e-mail]>",
      "references": [
        "<[e-mail]>"
      ],
      "from": "[e-mail]",
      "to": [
        "[e-mail]"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": null,
      "created_at": "2026-05-08T11:40:00.000Z",
      "email_size": 8192,
      "text_body": "Happy to help — could you share your order ID?",
      "html_body": "<p>Happy to help — could you share your order ID?</p>",
      "attachments": [],
      "delivery_status": "delivered",
      "delivered_at": "2026-05-08T11:40:05.000Z",
      "bounced_at": null
    },
    {
      "visibility_status": "placeholder",
      "direction": "inbound"
    }
  ]
}

Delete a thread

delete

Delete a thread. Inbound messages in the thread are removed; sent messages are preserved.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

inbox_idintegerRequired

Inbound inbox ID

Example: 1

idstringRequired

Inbound thread ID

Example: 1700000000000123

Responses

204

Thread deleted

No content

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

delete/api/inbound/inboxes/{inbox_id}/threads/{id}

cURLNode.jsPHPPythonRuby.NETJava

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

No content