List received messages
GET /v1/inboxes/{inbox_id}/messages
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/messages
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Lists received mail in the inbox, newest first. Narrow it with query and the sender, recipient, subject, date and label filters, or order by oldest or relevance: see Find mail and labels. Follow next_cursor with the same filters and order for the next page (pagination).
A message is listed as soon as it arrives. Only entries with processing_status: "ready" have from and a preview, and thread_id stays null until then. Identify the sender by from, a parsed mailbox such as {"name":"Sender","address":"sender@example.com"} or a group such as {"name":"Team","group":[...]}; envelope_from is the SMTP sender and can be a bounce address.
Previews
Received and sent listings include preview, an excerpt of up to 300 characters, null until the message's content is ready. It starts from the new reply text when that can be extracted, so even an untruncated preview can leave out the rest of the body: read the message before acting on it.
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/messages" \
--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 |
|---|---|---|---|
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: 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: ReceivedSummary
Exactly one of these shapes applies.
Alternative 1
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
thread_id | Yes | string or null | |
envelope_from | Yes | string | |
envelope_to | Yes | string | |
subject | Yes | string or null | |
received_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$ |
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. |
inbox_id | Yes | string | Cherami resource ID. |
thread_id | Yes | string or null | |
envelope_from | Yes | string | |
envelope_to | Yes | string | |
subject | Yes | string or null | |
received_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$ |
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 | 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: 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: 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. |