cherami.
API referenceConversations

List conversations

GET /v1/inboxes/{inbox_id}/threads

Read as Markdown ↗

GET /v1/inboxes/{inbox_id}/threads

Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.

Lists the inbox's conversations, most recent activity first. A conversation holds ready received messages and every send attempt, rejected and unknown included, and its counts include them.

The search, filters and ordering of message listings apply; a conversation matches when one of its messages meets every condition. Filtered results add matching_message_ids (up to 100, newest first) and matching_message_count.

subject is the earliest message's. latest_message is the newest message, whichever messages matched: its id, direction, counterpart (the From of received mail, or the first To of sent mail) and preview.

Labels belong to messages, not conversations. Reply using a message's id, not the thread ID.

Parameters

ParameterLocationRequiredTypeMeaning
inbox_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.
queryqueryNostringWords or "quoted phrases" to find in the subject and body; every term must match. At most 16 terms and 512 UTF-16 code units. OR, NOT and wildcards have no special meaning, and attachments aren't searched. See Find mail.
fromqueryNostringBare sender address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units.
recipientqueryNostringBare recipient address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units.
subjectqueryNostringText the subject contains, matched literally without regard to case. At most 998 UTF-16 code units.
afterqueryNostringEarliest (inclusive) receipt or send time, as an ISO 8601 instant with a timezone, such as 2026-10-01T00:00:00Z. after must be earlier than before. URL-encode it, including any + in an offset. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$
beforequeryNostringLatest (exclusive) receipt or send time, as an ISO 8601 instant with a timezone, such as 2026-10-01T00:00:00Z. after must be earlier than before. URL-encode it, including any + in an offset. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$
labels_allqueryNoarray of LabelMessages carrying every listed label. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. maxItems: 32
labels_anyqueryNoarray of LabelMessages carrying at least one listed label. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. maxItems: 32
labels_nonequeryNoarray of LabelMessages carrying none of the listed labels, unlabeled ones included. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. maxItems: 32
orderqueryNo"newest" or "oldest" or "relevance"relevance requires query. default: newest

curl example

Supply CHERAMI_API_KEY privately.

curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/inboxes/INBOX_ID/threads" \
  --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.

FieldRequiredTypeMeaning and constraints
threadsYesarray of ThreadSummary
next_cursorYesstring or null
{
  "threads": [],
  "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.

invalid_search: Correct the search terms, filters, timestamps or ordering the message names. See search.

invalid_labels: Correct the label name, label change, filter group or discovery prefix the message names.

  • 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

Schema: Label

1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.

string. x-max-utf8-bytes: 128

Schema: ThreadSummary

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
latest_messageYesThreadLatestMessage
matching_message_idsNoarray of stringmaxItems: 100
matching_message_countNointegerminimum: 0

Schema: ThreadLatestMessage

The conversation's newest message, whichever messages the filters matched. id is a received or sent message ID, according to direction.

Exactly one of these shapes applies.

Alternative 1

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
directionYes"received"
counterpartYesParsedAddress or nullThe message's From; null when absent.
previewYesPreview or null

Alternative 2

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
directionYes"sent"
counterpartYesMailbox or nullFirst To recipient, as a lowercase address without a name; null when unavailable. Sent detail has every recipient.
previewYesPreview or null

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: Preview

FieldRequiredTypeMeaning and constraints
textYesstringStart of the chosen text, whitespace collapsed; empty when the message added no new text. maxLength: 300
truncatedYesbooleantrue when the chosen text was longer than the excerpt.
sourceYes"reply_text" or "text" or "html"Which text the excerpt comes from.

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