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
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_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. |
query | query | No | string | Words 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. |
from | query | No | string | Bare sender address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units. |
recipient | query | No | string | Bare recipient address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units. |
subject | query | No | string | Text the subject contains, matched literally without regard to case. At most 998 UTF-16 code units. |
after | query | No | string | Earliest (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})$ |
before | query | No | string | Latest (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_all | query | No | array of Label | Messages 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_any | query | No | array of Label | Messages 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_none | query | No | array of Label | Messages 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 |
order | query | No | "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.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
threads | Yes | array of ThreadSummary | |
next_cursor | Yes | string 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.
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.
Schema: Label
1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.
string. x-max-utf8-bytes: 128
Schema: ThreadSummary
| 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 |
latest_message | Yes | ThreadLatestMessage | |
matching_message_ids | No | array of string | maxItems: 100 |
matching_message_count | No | integer | minimum: 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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
direction | Yes | "received" | |
counterpart | Yes | ParsedAddress or null | The message's From; null when absent. |
preview | Yes | Preview or null |
Alternative 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
direction | Yes | "sent" | |
counterpart | Yes | Mailbox or null | First To recipient, as a lowercase address without a name; null when unavailable. Sent detail has every recipient. |
preview | Yes | Preview 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
| 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: Preview
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
text | Yes | string | Start of the chosen text, whitespace collapsed; empty when the message added no new text. maxLength: 300 |
truncated | Yes | boolean | true when the chosen text was longer than the excerpt. |
source | Yes | "reply_text" or "text" or "html" | Which text the excerpt comes from. |
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. |