Read a received message
GET /v1/messages/{message_id}
Read as Markdown ↗GET /v1/messages/{message_id}
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns one received message. Check processing_status first:
ready:contentholds the parsed headers, the text and HTML bodies,reply_textand attachment metadata. The sender iscontent.from.pendingorprocessing: the content isn't ready yet; read the message again shortly.failed: the content couldn't be prepared. The raw MIME is still available.
For answers written between quoted lines, read text or html rather than reply_text.
Download an attachment by its id in content.attachments, with the attachment endpoint.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
message_id | path | Yes | string | Cherami resource ID returned by the API. |
curl example
Supply CHERAMI_API_KEY privately.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/messages/MESSAGE_ID" \
--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.
{
"id": "11111111-1111-4111-8111-111111111111",
"inbox_id": "11111111-1111-4111-8111-111111111111",
"thread_id": null,
"envelope_from": "sender@example.com",
"envelope_to": "my-agent@cherami.to",
"subject": null,
"received_at": "2026-10-01T00:00:00.000Z",
"processing_status": "ready",
"labels": [],
"message_id": null,
"raw_size": 0,
"processed_at": null,
"content": {
"from": null,
"sender": null,
"reply_to": [],
"to": [],
"cc": [],
"bcc": [],
"subject": null,
"message_id": null,
"in_reply_to": null,
"references": null,
"date": null,
"reply_text": null,
"text": null,
"html": null,
"attachments": []
}
}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.
HTTP 503
content_unavailable: Stored content could not be read. Retry later.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
Schema: ReceivedDetail
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 | |
message_id | Yes | string or null | The message's Message-ID header, not a Cherami ID: reply and forward take id. |
raw_size | Yes | integer | minimum: 0 |
processed_at | Yes | string or null | |
content | Yes | ReceivedContent |
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 | |
message_id | Yes | string or null | The message's Message-ID header, not a Cherami ID: reply and forward take id. |
raw_size | Yes | integer | minimum: 0 |
processed_at | Yes | string or null |
Schema: ReceivedContent
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
from | Yes | ParsedAddress or null | |
sender | Yes | ParsedAddress or null | |
reply_to | Yes | array of ParsedAddress | |
to | Yes | array of ParsedAddress | |
cc | Yes | array of ParsedAddress | |
bcc | Yes | array of ParsedAddress | |
subject | Yes | string or null | |
message_id | Yes | string or null | Message-ID header as the sender wrote it. |
in_reply_to | Yes | string or null | |
references | Yes | string or null | |
date | Yes | string or null | The sender's Date header: ISO when it parses, otherwise as written. Use received_at for ordering. |
reply_text | Yes | string or null | New text without quoted history. Empty: there is none. Null: it couldn't be extracted. |
text | Yes | string or null | |
html | Yes | string or null | |
attachments | Yes | array of ReceivedAttachment |
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: ReceivedAttachment
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | |
filename | Yes | string or null | |
size | Yes | integer | minimum: 0 |
mime_type | Yes | string | |
disposition | Yes | string or null | |
content_id | Yes | string or null | |
related | Yes | boolean |
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. |