# 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

```json
{
  "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_...
```

```json
{
  "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`](messages#list-messages-in-a-thread).