List email threads
Returns a keyset-paginated list of the caller's threads, most-recent activity first — ordered by lastMessageAt descending, with threads that have no messages yet sorted last.
Returns a keyset-paginated list of the caller's threads, most-recent activity first — ordered by lastMessageAt descending, with threads that have no messages yet sorted last. Each item carries the thread's subject, status (open, waiting, or closed), messageCount, lastMessageAt, createdAt, and a lastMessagePreview — the newest message's text, whitespace-collapsed to 160 characters — but not the messages themselves; fetch a single thread to read those. Set inboxId to a valid inbox UUID to scope the list to one inbox, and size the page with limit (1–100, default 25). Each response's pagination.nextCursor is the opaque value to send as cursor on the next request, and pagination.hasMore is false once you reach the end. Requires the messages:read scope; a malformed inboxId or cursor, or an out-of-range limit, returns 400. See keyset pagination.
Scope: messages:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Maximum number of items in the page. (minimum 1, maximum 100, default 25) |
cursor | string | no | The nextCursor of the previous page; omit it for the first page (Pagination). |
inboxId | string | no |
Response
200 Success. Body: application/json, ThreadListResponse.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" | yes | |
data | array of Thread | yes | |
pagination | Pagination | yes |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
422 | The request is well-formed but a field failed validation (validation_failed). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |