Read a conversation
GET /v1/threads/{thread_id}
Read as Markdown โGET /v1/threads/{thread_id}
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns the conversation's metadata and its messages, with bodies and attachment metadata. Each message has direction (received or sent), timestamp, and the fields of received or sent detail.
The first page holds the newest messages, oldest first within the page; next_cursor fetches older ones. Order follows Cherami's receipt and send times, not the senders' Date headers. Counts describe the whole conversation.
Attachment bytes aren't included: download a received file, or read sent detail for a sent file's base64 content.
Received messages that aren't ready, or failed, aren't part of a conversation; read them through the message endpoints.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
thread_id | path | Yes | string | Cherami resource ID returned by the API. |
limit | query | No | integer | Results per page. minimum: 1 maximum: 100 default: 20 |
cursor | query | No | string | next_cursor from the previous page. Keep the URL, filters and order unchanged. |
curl example
Supply CHERAMI_API_KEY privately.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/threads/THREAD_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Success.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
{
"id": "11111111-1111-4111-8111-111111111111",
"inbox_id": "11111111-1111-4111-8111-111111111111",
"subject": null,
"last_activity_at": "2026-10-01T00:00:00.000Z",
"message_count": 0,
"received_count": 0,
"accepted_count": 0,
"rejected_count": 0,
"unknown_count": 0,
"messages": [],
"next_cursor": null
}HTTP 400
invalid_limit: Use an integer from 1 to 100.
invalid_cursor: Send a cursor only to the listing, filters and order that returned it, or restart from the first page.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 401
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 500
internal_error: The operation failed. Retry a read; after a write the change may have happened, so recover as retry by operation describes.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 503
content_unavailable: Stored content could not be read. Retry later.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
Schema: ThreadDetail
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
subject | Yes | string or null | |
last_activity_at | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
message_count | Yes | integer | minimum: 0 |
received_count | Yes | integer | minimum: 0 |
accepted_count | Yes | integer | minimum: 0 |
rejected_count | Yes | integer | minimum: 0 |
unknown_count | Yes | integer | minimum: 0 |
messages | Yes | array of ThreadReceivedDetail or ThreadSentDetail | |
next_cursor | Yes | string or null |
Schema: ThreadReceivedDetail
All of these schemas apply.
Part 1
Part 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
direction | Yes | "received" | |
timestamp | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
Schema: ReceivedDetail
Exactly one of these shapes applies.
Alternative 1
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
thread_id | Yes | string or null | |
envelope_from | Yes | string | |
envelope_to | Yes | string | |
subject | Yes | string or null | |
received_at | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
processing_status | Yes | "ready" | |
labels | Yes | array of string | |
message_id | Yes | string or null | The message's Message-ID header, not a Cherami ID: reply and forward take id. |
raw_size | Yes | integer | minimum: 0 |
processed_at | Yes | string or null | |
content | Yes | ReceivedContent |
Alternative 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
thread_id | Yes | string or null | |
envelope_from | Yes | string | |
envelope_to | Yes | string | |
subject | Yes | string or null | |
received_at | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
processing_status | Yes | "pending" or "processing" or "failed" | |
labels | Yes | array of string | |
message_id | Yes | string or null | The message's Message-ID header, not a Cherami ID: reply and forward take id. |
raw_size | Yes | integer | minimum: 0 |
processed_at | Yes | string or null |
Schema: ReceivedContent
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
from | Yes | ParsedAddress or null | |
sender | Yes | ParsedAddress or null | |
reply_to | Yes | array of ParsedAddress | |
to | Yes | array of ParsedAddress | |
cc | Yes | array of ParsedAddress | |
bcc | Yes | array of ParsedAddress | |
subject | Yes | string or null | |
message_id | Yes | string or null | Message-ID header as the sender wrote it. |
in_reply_to | Yes | string or null | |
references | Yes | string or null | |
date | Yes | string or null | The sender's Date header: ISO when it parses, otherwise as written. Use received_at for ordering. |
reply_text | Yes | string or null | New text without quoted history. Empty: there is none. Null: it couldn't be extracted. |
text | Yes | string or null | |
html | Yes | string or null | |
attachments | Yes | array of ReceivedAttachment |
Schema: ParsedAddress
Mailbox or group from the message headers, written by the sender and not verified.
Exactly one of these shapes applies.
Alternative 1
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
name | Yes | string | |
address | Yes | string |
Alternative 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
name | Yes | string | |
group | Yes | array of object |
group fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
name | Yes | string | |
address | Yes | string |
Schema: ReceivedAttachment
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | |
filename | Yes | string or null | |
size | Yes | integer | minimum: 0 |
mime_type | Yes | string | |
disposition | Yes | string or null | |
content_id | Yes | string or null | |
related | Yes | boolean |
Schema: ThreadSentDetail
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
created_at | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
recipient_count | Yes | integer | minimum: 0 |
status | Yes | "accepted" or "rejected" or "unknown" | |
provider_message_id | Yes | string or null | Message-ID the provider assigned when it accepted the message. |
error_code | Yes | string or null | Reason code for a rejected or unknown outcome, such as E_RECIPIENT_SUPPRESSED or acceptance_unknown. |
thread_id | Yes | string or null | |
in_reply_to | Yes | string or null | |
labels | Yes | array of string | |
direction | Yes | "sent" | |
timestamp | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
reply_text | Yes | string or null | New text without quoted history. Empty: there is none. Null: it couldn't be extracted; read submission. |
submission | Yes | object |
submission fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
to | Yes | array of Mailbox or string | |
cc | Yes | array of Mailbox or string | |
bcc | Yes | array of Mailbox or string | |
subject | Yes | string | |
text | Yes | string | |
html | No | string | |
attachments | Yes | array of object | |
from | Yes | Mailbox or string | |
headers | No | object |
attachments fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | |
filename | Yes | string | |
mime_type | Yes | string | |
size | Yes | integer | minimum: 0 |
headers fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
In-Reply-To | Yes | string | |
References | Yes | string |
Schema: Mailbox
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
address | Yes | string | Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. maxLength: 254 |
name | No | string | Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. x-max-utf8-bytes: 256 |
Unknown fields are rejected.
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
message | Yes | string | Explanation of this case; its wording can change. |