List received messages
GET /v1/inboxes/{inbox_id}/messages
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/messages
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns 200 with messages and next_cursor. Messages default to newest-received first. Combine keyword search, sender, recipient, subject, date and label filters; order accepts newest, oldest, or relevance. See search and filtering. limit is 1–100, default 20. Follow the returned cursor as a URL-encoded cursor parameter on the same URL. Use labels_all for required tags, optionally combined with labels_any and labels_none. Keep the same filters when following a cursor. See pagination and label filtering.
The response schema describes every summary field. subject may be null. thread_id is null until parsing succeeds. Only ready summaries additionally contain from, with a parsed address or null if absent. It is omitted for other states.
A parsed address is a mailbox ({"name":"Sender","address":"sender@example.com"}) or group ({"name":"Team","group":[{"name":"Sender","address":"sender@example.com"}]}). Parsed From is sender-supplied, not proof of identity. envelope_from is the SMTP sender and may be a bounce address.
Previews
Both received and sent listings include preview: null when derived content is not ready or unavailable, otherwise an object:
text is the beginning of the extracted reply when available, otherwise the plain-text body or text derived from HTML. Whitespace is normalized and the excerpt is capped at 300 Unicode code points, preferably at a word boundary. source is reply_text, text, or html; truncated indicates that the chosen text exceeded the excerpt. A short excerpt may contain the whole chosen text, not necessarily the whole original email. A genuinely empty extracted reply produces text: "", not null. Previews are deterministic excerpts, not summaries or read/unread state.
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/messages" \
--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 |
|---|---|---|---|
messages | Yes | array of ReceivedSummary | |
next_cursor | Yes | string or null |
{
"messages": [],
"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: ReceivedSummary
Exactly one of these shapes applies.
Alternative 1
| 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. |
thread_id | Yes | string or null | |
envelope_from | Yes | string | |
envelope_to | Yes | string | |
subject | Yes | string or null | |
received_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$ |
processing_status | Yes | "ready" | |
labels | Yes | array of string | |
preview | Yes | Preview or null | |
from | Yes | ParsedAddress or null |
Alternative 2
| 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. |
thread_id | Yes | string or null | |
envelope_from | Yes | string | |
envelope_to | Yes | string | |
subject | Yes | string or null | |
received_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$ |
processing_status | Yes | "pending" or "processing" or "failed" | |
labels | Yes | array of string | |
preview | Yes | null |
Schema: Preview
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
text | Yes | string | Beginning of selected text with normalized whitespace; empty is a valid extraction. maxLength: 300 |
truncated | Yes | boolean | |
source | Yes | "reply_text" or "text" or "html" |
Schema: ParsedAddress
Sender-controlled MIME address or group, not verified identity.
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: 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