Menu Conventions

Reference

Conventions

The rules every schema of the API shares, said once here instead of on every field.

Schemas

  • Time. RFC 3339 in UTC, always with milliseconds: 2026-10-22T18:01:02.123Z (.000Z when the fraction is zero). Headers such as Retry-After and X-RateLimit-Reset stay in seconds.
  • Shape. Field names are camelCase; a field whose value is null is present, an empty list is []; enums are UPPERCASE (bodyState: "STORED"), error codes lowercase (not_found).
  • Lists. page (from 0) and size (1–50, 20 by default); out of range is a 400, never clamped. The answer is { content, page, size, totalPages, totalElements }, newest first.
  • Errors. Every error is JSON { "error": "<code>", "message": "<phrase>" }. Switch on error; message is a fixed English phrase for the developer reading the log.

A time you are shown is not a cursor: the server keeps microseconds, the JSON shows milliseconds, so two messages can share a createdAt. To go on after a message, use its id (Waiting for emails).

A mailbox accepts mail for 24 hours and cannot be renewed; once expiresAt passes, it and its messages answer 404 and are deleted soon after.

Downloads

Two operations answer with a file instead of JSON. Both are reads: they cost nothing against the monthly quota, only against the per-minute rate limit, and a 404 still comes back as the usual JSON error, not_found.

  • GET /v1/mailboxes/{address}/messages/{id}/rawThe message exactly as received, as an .eml file (message/rfc822) – headers, every part, every attachment. It is the only way to read a message whose bodyState is UNPARSED; an OVERFLOW message kept no source and answers 404.
  • GET /v1/mailboxes/{address}/messages/{id}/attachments/{attachmentId}The decoded bytes of one attachment, with the Content-Type the sender declared and the file name in Content-Disposition – the attachment id when the email gave none. The sender chose the name: strip any directories from it before saving the file. Take the id from attachments of the message; an UNPARSED or OVERFLOW message has none.
Something missing, confusing or wrong on this page? Tell us