Received messages
Incoming-message pagination, prepared fields, processing states, downloads, and deletion.
Read as Markdown ↗All routes require bearer authentication. Missing or other-account resources return 404.
List messages
GET /v1/inboxes/{inbox_id}/messages?limit=20
Returns 200 with messages and next_cursor. Messages are ordered newest-received first. limit is 1–100, default 20. Follow the returned cursor as a URL-encoded cursor parameter on the same URL. See pagination.
{
"messages": [{
"id": "22222222-2222-4222-8222-222222222222",
"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": "pending"
}],
"next_cursor": null
}Every summary contains the fields above. 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. There are no body previews in the list.
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.
Count messages
GET /v1/inboxes/{inbox_id}/messages/count returns 200 with {"count":3}.
This is the current count, including unfinished messages, not an unread count or a snapshot shared with pagination.
Read a message
GET /v1/messages/{message_id} returns 200 with the summary metadata except the list-only from, plus:
| Field | Value |
|---|---|
message_id | RFC message identifier or null; distinct from the resource id. |
raw_size | Original MIME size in bytes. |
processed_at | Processing completion timestamp or null. |
content | Present only when processing_status is ready. |
content has these fields:
| Field | Value |
|---|---|
from, sender | Parsed address object or null. |
reply_to, to, cc, bcc | Arrays of parsed address objects; empty when absent. |
subject, message_id, in_reply_to, references, date | Parsed header strings or null. date is sender-supplied, not the service receipt time. |
text, html | Body strings or null. HTML is untrusted text, not safe application markup. |
attachments | Array of attachment metadata, empty when absent. |
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.
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.
Download raw MIME
GET /v1/messages/{message_id}/raw
Returns 200 with original MIME bytes, Content-Type: message/rfc822, and attachment disposition. This does not require successful parsing.
Download an attachment
GET /v1/messages/{message_id}/attachments/{attachment_id}
Returns 200 with file bytes, Content-Type: application/octet-stream, and attachment disposition. Use the ID returned in ready content, not a guessed filename. An unavailable attachment or a message that is not ready returns 404; missing stored content can return 503.
Downloads use no-store, nosniff, and a sandbox content security policy. Reported filenames and MIME metadata do not establish that files are safe to execute or render.
Delete a message
DELETE /v1/messages/{message_id} returns 202:
{"id":"22222222-2222-4222-8222-222222222222","status":"deletion_pending"}Permanently deletes the received message and its attachments, including when parsing is unfinished. No trash or undo. It is no longer available for retrieval or as a new reply target. Repeated deletion is safe and can return 202 or 404.