Read a received message
GET /v1/messages/{message_id}
Read as Markdown ↗GET /v1/messages/{message_id}
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns received metadata, raw size and processing completion time. The list-only from and preview are omitted.
Ready content includes original prepared bodies, parsed header values, extracted reply text and attachment metadata. Unfinished and failed detail responses omit content.
Each received attachment has id (string), filename (string or null), size (bytes), mime_type, disposition (string or null), content_id (string or null), and related (boolean). Use its id in the attachment download route.
Reply extraction preserves original bodies and does not change full-body search. It prefers plain text and derives text from HTML-only mail without rendering or fetching resources. It can miss unusual quoting or omit inline answers; read text or html when the full context matters. Explicitly marked forwards are retained rather than treated as quoted replies. Extraction failure does not fail ordinary retrieval.
Processing states
pending and processing mean prepared content is not ready. Check later with bounded backoff. ready supplies content; failed does not. All four states can return detail 200. Raw MIME remains available in unfinished and failed states. Missing stored content can return 503 content_unavailable.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
message_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
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/messages/MESSAGE_ID" \
--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.
{
"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: 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.
HTTP 503
content_unavailable: Expected stored content is unavailable. Retry the read later.
X-Request-ID: Support correlation ID, not an idempotency key.
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, 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 | |
message_id | Yes | string or null | |
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, 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 | |
message_id | Yes | string or null | |
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 | |
in_reply_to | Yes | string or null | |
references | Yes | string or null | |
date | Yes | string or null | |
reply_text | Yes | string or null | |
text | Yes | string or null | |
html | Yes | string or null | |
attachments | Yes | array of ReceivedAttachment |
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: 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 | 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