Threads

List an inbox's threads (thin list)

Lists the inbox's threads, most-recently-active first, paginated. Each entry is the **thin** thread (no `messages[]` — fetch those with get-thread). Threads labeled `spam` or `unauthenticated` are excluded unless the matching `include_*` flag is set; opting into `spam` additionally requires the key's `label_spam_read` permission. An inbox with no mail returns an empty list; an unknown/cross-tenant inbox is a `404`.

GET
/inboxes/{inbox_id}/threads

Lists the inbox's threads, most-recently-active first, paginated. Each entry is the thin thread (no messages[] — fetch those with get-thread). Threads labeled spam or unauthenticated are excluded unless the matching include_* flag is set; opting into spam additionally requires the key's label_spam_read permission. An inbox with no mail returns an empty list; an unknown/cross-tenant inbox is a 404.

Authorization

x-api-key<token>

The per-tenant API key. Sent as the x-api-key request header. The key is tenant-scoped.

In: header

Path Parameters

inbox_id*string

The inbox's opaque id (e.g. inb_…).

Query Parameters

limit?integer

Page size, 1-100. Defaults to 50.

page_token?string

Opaque token from a previous page's next_page_token. Omit for the first page.

ascending?boolean

Sort oldest-first when true. Defaults to newest-first.

include_spam?boolean

Include threads labeled spam (excluded by default). Requires the key's label_spam_read permission.

include_unauthenticated?boolean

Include threads labeled unauthenticated (excluded by default).

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/inboxes/string/threads"
{  "count": 0,  "limit": 0,  "next_page_token": "string",  "threads": [    {      "id": "string",      "inbox_id": "string",      "subject": "string",      "preview": "string",      "senders": [        "string"      ],      "recipients": [        "string"      ],      "labels": [        "string"      ],      "message_count": 0,      "size": 0,      "last_message_id": "string",      "received_timestamp": "2019-08-24T14:15:22Z",      "last_activity_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}
{  "name": "string",  "message": "string"}
{  "name": "string",  "message": "string"}
{  "name": "string",  "message": "string"}
{  "name": "validation",  "errors": {    "property1": "string",    "property2": "string"  }}

Get a thread with its messages (fat get) GET

Returns the thread plus its **full** messages in chronological (`timestamp` ascending) order — the complete conversation an agent reads as memory. A `spam`-labeled thread requires the key's `label_spam_read` permission. Unknown/cross-tenant inbox or thread ids return an indistinguishable `404`.

Register a webhook scoped to an inbox POST

Register a webhook pre-scoped to this inbox — the endpoint only receives events for this one inbox. Otherwise identical to `POST /webhooks`: `url` must be HTTPS, `event_types` must list at least one type, and the response includes the one-time signing secret. Supplying `inbox_ids` in the body overrides the path scope.