List conversations
GET /v1/inboxes/{inbox_id}/threads
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/threads
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
Threads are grouped automatically. They contain ready received messages and sent attempts, including rejected and unknown outcomes.
GET /v1/inboxes/{inbox_id}/threads?limit=20 returns 200.
Most recent activity first by default. Accepts the shared search, filters and ordering. A conversation matches when one member satisfies every condition. Filtered results additionally include matching_message_ids (up to 100, newest first) and matching_message_count (total matching members). subject is from the earliest surviving message and can be null. Counts include attempts, not just successful correspondence.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
limit | query | No | integer | Decimal integer without signs, whitespace or leading zeroes. minimum: 1 maximum: 100 default: 20 |
cursor | query | No | string | Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null. |
query | query | No | string | Nonempty lexical subject/body search, at most 512 UTF-16 code units and 16 words or closed quoted phrases. Every term must match; no raw FTS operators. Attachments and filenames are excluded. |
from | query | No | string | Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope. |
recipient | query | No | string | Exact case-insensitive bare parsed-header address. At most 320 UTF-16 code units before trimming; not the SMTP envelope. |
subject | query | No | string | Case-insensitive literal substring, nonblank and at most 998 UTF-16 code units before trimming. |
after | query | No | string | Inclusive lower service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets. 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 | Exclusive upper service receipt/submission bound. Timezone-qualified valid calendar instant; after must precede before. URL-encode normally, including literal plus signs in offsets. 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 | Require every listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope. maxItems: 32 |
labels_any | query | No | array of Label | Require at least one listed label. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope. maxItems: 32 |
labels_none | query | No | array of Label | Exclude any message carrying a listed label; unlabeled messages qualify. Repeat this parameter per label, never comma-separate. Groups combine with AND; contradictory filters match nothing. Omit unused groups; use labels_all even for one label. Normalized set order and duplicates do not change cursor scope. maxItems: 32 |
order | query | No | "newest" or "oldest" or "relevance" | relevance requires query. Listings are live views, not snapshots. default: newest |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/inboxes/INBOX_ID/threads" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
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: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.
invalid_search: Correct search terms, filters, timestamps, or ordering. See search.
invalid_labels: Correct label names, changes, filter groups, or discovery prefix.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 500
internal_error: Operation failed; a write may already have happened. Follow the operation-specific recovery below.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: Label
1–128 UTF-8 bytes after trimming. Well-formed Unicode 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, distinct from the RFC Message-ID. Use the returned value. |
inbox_id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
subject | Yes | string or null | |
last_activity_at | Yes | string | UTC service instant with milliseconds and Z suffix. 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 |
matching_message_ids | No | array of string | maxItems: 100 |
matching_message_count | No | integer | minimum: 0 |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1