Reading mail

Listing messages

GET /inboxes/:id/messages returns mail for one address, newest first:

{
  "messages": [
    {
      "id": "msg_91be02c4a7d1",
      "inboxId": "ibx_k3v9x2mq7a",
      "receivedAt": "2026-09-18T09:14:03.000Z",
      "read": false,
      "sizeBytes": 18432,
      "content": { "…": "sealed" }
    }
  ],
  "nextCursor": null
}

Page with limit (default 50, at most 200) and cursor, passing the previous response’s nextCursor until it is null.

content is sealed. See Encryption and sealed data.

Mail past its address’s retention window is not returned, and an hourly sweep deletes it.

One message

GET /messages/:id returns a single message in the same shape, as message.

Attachments

GET /messages/:id/attachments/:index returns one attachment body as sealed bytes, Content-Type: application/octet-stream. The real file name and type are inside the sealed message. Attachments over 20MB are listed in the message but not stored.

Read state

POST /messages/:id/read marks a message read. Send { "read": false } to mark it unread.

Reading costs

Every message body and attachment comes from object storage, so reading is metered per object, not per request. Each plan has an hourly allowance; past it, reads return 429 with Retry-After. See Rate limits.