cherami.
API referenceReceived messages

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: content holds the parsed headers, the text and HTML bodies, reply_text and attachment metadata. The sender is content.from.
  • pending or processing: 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

ParameterLocationRequiredTypeMeaning
message_idpathYesstringCherami 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.

ReceivedDetail

{
  "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.

Error

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.

Error

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.

Error

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.

Error

Schema: ReceivedDetail

Exactly one of these shapes applies.

Alternative 1

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
thread_idYesstring or null
envelope_fromYesstring
envelope_toYesstring
subjectYesstring or null
received_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
processing_statusYes"ready"
labelsYesarray of string
message_idYesstring or nullThe message's Message-ID header, not a Cherami ID: reply and forward take id.
raw_sizeYesintegerminimum: 0
processed_atYesstring or null
contentYesReceivedContent

Alternative 2

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
thread_idYesstring or null
envelope_fromYesstring
envelope_toYesstring
subjectYesstring or null
received_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
processing_statusYes"pending" or "processing" or "failed"
labelsYesarray of string
message_idYesstring or nullThe message's Message-ID header, not a Cherami ID: reply and forward take id.
raw_sizeYesintegerminimum: 0
processed_atYesstring or null

Schema: ReceivedContent

FieldRequiredTypeMeaning and constraints
fromYesParsedAddress or null
senderYesParsedAddress or null
reply_toYesarray of ParsedAddress
toYesarray of ParsedAddress
ccYesarray of ParsedAddress
bccYesarray of ParsedAddress
subjectYesstring or null
message_idYesstring or nullMessage-ID header as the sender wrote it.
in_reply_toYesstring or null
referencesYesstring or null
dateYesstring or nullThe sender's Date header: ISO when it parses, otherwise as written. Use received_at for ordering.
reply_textYesstring or nullNew text without quoted history. Empty: there is none. Null: it couldn't be extracted.
textYesstring or null
htmlYesstring or null
attachmentsYesarray 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

FieldRequiredTypeMeaning and constraints
nameYesstring
addressYesstring

Alternative 2

FieldRequiredTypeMeaning and constraints
nameYesstring
groupYesarray of object

group fields

FieldRequiredTypeMeaning and constraints
nameYesstring
addressYesstring

Schema: ReceivedAttachment

FieldRequiredTypeMeaning and constraints
idYesstring
filenameYesstring or null
sizeYesintegerminimum: 0
mime_typeYesstring
dispositionYesstring or null
content_idYesstring or null
relatedYesboolean

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Errors, limits and pagination · Download OpenAPI 3.1

On this page