Get one thread with its messages
Fetches one thread by threadId (a UUID) together with its messages, oldest first.
Fetches one thread by threadId (a UUID) together with its messages, oldest first. The response is the thread object — subject, status, messageCount, lastMessageAt, and timestamps — with a messages array inlined, where each message is the summary shape (from, to, subject, a 160-character textPreview, and hasHtml/hasAttachments flags) rather than the full body. At most the 100 oldest messages are returned and this array is not paginated, so for a longer thread — or to read a full textBody/htmlBody and its attachments — list messages filtered by threadId or fetch each message by id. Returns 404 when the thread does not exist or belongs to another account, and 400 when threadId is not a valid UUID. Requires the messages:read scope; see messages and threads.
Scope: messages:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
threadId | string | yes | The thread's ID. |
Response
200 Success. Body: application/json, ThreadResponse.
| Field | Type | Required | Description |
|---|---|---|---|
object | "thread" | no | |
id | string (uuid) | yes | |
inboxId | string (uuid) | yes | |
subject | string | yes | |
messageCount | integer | yes | (minimum 0) |
lastMessageAt | string (date-time) or null | yes | |
updatedAt | string (date-time) | yes | |
status | string | yes | |
lastMessagePreview | string or null | yes | |
createdAt | string (date-time) | yes | |
channel | "email", "a2a" | yes | The channel this message transited: "email" (external, over SES) or "a2a" (internal Dairo-to-Dairo, which skips SES). Reserved future values (sms, whatsapp, …) are not yet wired. |
messages | array of Message | 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). |
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.
List webhook subscriptions
Returns every webhook subscription in your organization, newest first, as an unpaginated list envelope — data[] holds the webhooks and there is no pagination cursor.