cherami.
API referenceConversations

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

ParameterLocationRequiredTypeMeaning
thread_idpathYesstringCherami resource ID returned by the API.
limitqueryNointegerResults per page. minimum: 1 maximum: 100 default: 20
cursorqueryNostringnext_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.

ThreadDetail

{
  "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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

Schema: ThreadDetail

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
subjectYesstring or null
last_activity_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
message_countYesintegerminimum: 0
received_countYesintegerminimum: 0
accepted_countYesintegerminimum: 0
rejected_countYesintegerminimum: 0
unknown_countYesintegerminimum: 0
messagesYesarray of ThreadReceivedDetail or ThreadSentDetail
next_cursorYesstring or null

Schema: ThreadReceivedDetail

All of these schemas apply.

Part 1

ReceivedDetail

Part 2

FieldRequiredTypeMeaning and constraints
directionYes"received"
timestampYesstringUTC 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

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
thread_idYesstring or null
envelope_fromYesstring
envelope_toYesstring
subjectYesstring or null
received_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
processing_statusYes"ready"
labelsYesarray of string
message_idYesstring or nullThe message's Message-ID header, not a Cherami ID: reply and forward take id.
raw_sizeYesintegerminimum: 0
processed_atYesstring or null
contentYesReceivedContent

Alternative 2

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
thread_idYesstring or null
envelope_fromYesstring
envelope_toYesstring
subjectYesstring or null
received_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
processing_statusYes"pending" or "processing" or "failed"
labelsYesarray of string
message_idYesstring or nullThe message's Message-ID header, not a Cherami ID: reply and forward take id.
raw_sizeYesintegerminimum: 0
processed_atYesstring or null

Schema: ReceivedContent

FieldRequiredTypeMeaning and constraints
fromYesParsedAddress or null
senderYesParsedAddress or null
reply_toYesarray of ParsedAddress
toYesarray of ParsedAddress
ccYesarray of ParsedAddress
bccYesarray of ParsedAddress
subjectYesstring or null
message_idYesstring or nullMessage-ID header as the sender wrote it.
in_reply_toYesstring or null
referencesYesstring or null
dateYesstring or nullThe sender's Date header: ISO when it parses, otherwise as written. Use received_at for ordering.
reply_textYesstring or nullNew text without quoted history. Empty: there is none. Null: it couldn't be extracted.
textYesstring or null
htmlYesstring or null
attachmentsYesarray 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

FieldRequiredTypeMeaning and constraints
nameYesstring
addressYesstring

Alternative 2

FieldRequiredTypeMeaning and constraints
nameYesstring
groupYesarray of object

group fields

FieldRequiredTypeMeaning and constraints
nameYesstring
addressYesstring

Schema: ReceivedAttachment

FieldRequiredTypeMeaning and constraints
idYesstring
filenameYesstring or null
sizeYesintegerminimum: 0
mime_typeYesstring
dispositionYesstring or null
content_idYesstring or null
relatedYesboolean

Schema: ThreadSentDetail

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
created_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
recipient_countYesintegerminimum: 0
statusYes"accepted" or "rejected" or "unknown"
provider_message_idYesstring or nullMessage-ID the provider assigned when it accepted the message.
error_codeYesstring or nullReason code for a rejected or unknown outcome, such as E_RECIPIENT_SUPPRESSED or acceptance_unknown.
thread_idYesstring or null
in_reply_toYesstring or null
labelsYesarray of string
directionYes"sent"
timestampYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
reply_textYesstring or nullNew text without quoted history. Empty: there is none. Null: it couldn't be extracted; read submission.
submissionYesobject

submission fields

FieldRequiredTypeMeaning and constraints
toYesarray of Mailbox or string
ccYesarray of Mailbox or string
bccYesarray of Mailbox or string
subjectYesstring
textYesstring
htmlNostring
attachmentsYesarray of object
fromYesMailbox or string
headersNoobject

attachments fields

FieldRequiredTypeMeaning and constraints
idYesstring
filenameYesstring
mime_typeYesstring
sizeYesintegerminimum: 0

headers fields

FieldRequiredTypeMeaning and constraints
In-Reply-ToYesstring
ReferencesYesstring

Schema: Mailbox

FieldRequiredTypeMeaning and constraints
addressYesstringBare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. maxLength: 254
nameNostringOptional 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

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Errors, limits and pagination ยท Download OpenAPI 3.1

On this page