Threads

A thread is a read-only grouping of an inbox's messages into one conversation, matched by subject and participants the same way a mail client threads a mailbox. Threads have no create or update endpoint — they are formed automatically as mail arrives and is replied to.

The thread object

{
  "id": "thr_01k2n9v8qf3m7d5b0y6xz4rt7i",
  "object": "thread",
  "inbox_id": "inb_01k2n9v8qf3m7d5b0y6xz4rt1c",
  "subject": "Question about my order",
  "participants": ["customer@example.com", "orders-bot@agentmail.ackuna.com"],
  "message_count": 3,
  "last_message_at": "2026-08-20T14:05:00.000Z",
  "created_at": "2026-08-19T10:00:00.000Z"
}

participants is every lowercased email address that has sent or received a message in the thread so far.

List threads in an inbox

GET /v1/inboxes/inb_01k2n9v8qf3m7d5b0y6xz4rt1c/threads?limit=25
Authorization: Bearer ak_...

{
  "data": [
    {"id": "thr_01k2n9v8qf3m7d5b0y6xz4rt7i", "object": "thread", "inbox_id": "inb_01k2n9v8qf3m7d5b0y6xz4rt1c", "subject": "Question about my order", "participants": ["customer@example.com", "orders-bot@agentmail.ackuna.com"], "message_count": 3, "last_message_at": "2026-08-20T14:05:00.000Z", "created_at": "2026-08-19T10:00:00.000Z"}
  ],
  "next_cursor": null,
  "has_more": false
}

Requires scope messages:read. Ordered most-recently-active first (last_message_at descending), so the top of page one is always what needs attention now. 404 not_found if the inbox is unknown or belongs to another organization.

Fetch a thread

GET /v1/threads/thr_01k2n9v8qf3m7d5b0y6xz4rt7i
Authorization: Bearer ak_...

Requires scope messages:read. Returns the thread object, or 404 not_found. To read the thread's messages, see GET /v1/threads/{thread}/messages.