Conversation threads
Inbox-scoped conversation metadata and paginated message context.
Read as Markdown ↗Both routes require bearer authentication. Threads are automatic; no creation request is needed. They contain ready received messages and sent attempts, including rejected and unknown outcomes.
List threads
GET /v1/inboxes/{inbox_id}/threads?limit=20 returns 200:
{
"threads": [{
"id": "44444444-4444-4444-8444-444444444444",
"inbox_id": "11111111-1111-4111-8111-111111111111",
"subject": "Review ready",
"last_activity_at": "2026-10-01T00:00:00.000Z",
"message_count": 3,
"received_count": 1,
"accepted_count": 1,
"rejected_count": 0,
"unknown_count": 1
}],
"next_cursor": null
}Most recent activity first. subject is from the earliest surviving message and can be null. Counts include attempts, not just successful correspondence. These are metadata, not AI summaries.
Read a thread
GET /v1/threads/{thread_id}?limit=20 returns 200 with the same thread metadata, plus messages and next_cursor.
Each entry has direction (received or sent), timestamp (ISO service receipt/submission time), and the fields from received detail or sent detail.
Bodies and attachment metadata are included, without attachment bytes. Received attachments use the ordinary download endpoint. Sent thread attachments have id, filename, mime_type, and size in bytes; use ordinary sent detail for their base64 content.
The first page contains the newest messages, chronological within the page. The next page contains older messages. Metadata counts describe the conversation, not just the current page.
Pagination and changes
Both routes accept limit 1–100, default 20. Follow next_cursor as a URL-encoded cursor parameter on the same resource URL. Ordering uses service timestamps, not sender-controlled Date headers.
Conversations can update, and pages are not a snapshot. Previously returned thread IDs remain usable while their conversation exists; the returned id may differ from the requested one. Continue a pagination sequence on the same requested URL, and refetch recent context when needed.
Pending, processing, and failed received messages have thread_id: null and are absent from threads. They remain available through message endpoints. Deleted messages disappear; surviving messages remain grouped. Empty, missing, or other-account conversations return 404. Invalid limits/cursors return 400, and unavailable content can return 503.
No thread-wide deletion, manual merging, search, labels, or quote stripping is provided. Thread membership is not proof of identity or delivery. Reply using a message resource ID, not the thread ID.