Messages

Messages represent individual emails in a mailbox. List and detail endpoints return message metadata; full body content (text/HTML) is fetched from storage on detail requests. All list endpoints use cursor-based pagination.

GET /mailboxes/{email_address}/messages

List messages in a mailbox, newest first, with cursor pagination.

Path parameters

Query parameters

start_datetime, end_datetime, and tz filter on created_at. Both bounds are optional and non-breaking — omit them for unchanged behavior. See Filtering by date.

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

GET /mailboxes/{email_address}/messages/{message_id}

Get a single message with its full body content (plain text and HTML).

The body returned is the body Inkbox stored, which is not always the body the caller submitted: while the branding footer applies, outbound body_text/body_html come back with the "Sent via Inkbox" footer appended — see Branding footer under Send message.

Fetching marks inbound mail read. A GET here with an API key marks an unread inbound message read — is_read comes back true in the same response. Human (Console) reads don't, and neither do the list, thread, or attachment routes, so an agent that only reads through those still needs the flags PATCH to mark read. This is distinct from first_opened_at, which reflects the recipient opening a message you sent (see Open tracking).

Path parameters

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

POST /mailboxes/{email_address}/messages

Compose and send an email from a mailbox. Threading is automatically resolved from in_reply_to_message_id.

Path parameters

Request body

AttachmentUpload object:

Request example

JSON

Response (201)

Returns the created message metadata (same as a list item — body content is not included).

Branding footer

By default, outbound mail carries a short "Sent via Inkbox" footer, appended to the text and HTML parts of every send, reply-all, and forward. Organizations on a paid plan can remove it — see Branding footer.

While it applies, the footer is written into the stored message, so it changes what the API gives back: a later GET /messages/{message_id} returns body_text and body_html with the footer appended — not the exact bytes you submitted. A send with no body at all comes back with a body containing only the footer. Snippets and search text are computed from the body you submitted, so snippet and search are unaffected.

Open tracking

Set track_opens on a send or forward to embed an invisible tracking pixel in the HTML body. When the recipient's mail client loads it, the message reports two fields (present on every message response):

track_opens requires an HTML part — a plain-text-only send returns 422. Tracking is per-message ("at least one observed open"), not per-recipient, and the pixel can raise spam scores, so a borderline message may be more likely to be filtered. first_opened_at (the recipient loaded the pixel) is distinct from is_read (your agent consumed the message via the API — see Get message).

Error responses

Code examples

cURL

cURL

JavaScript

Python

POST /mailboxes/{email_address}/messages/{message_id}/reply-all

Reply to every visible participant on a stored message. Recipients are resolved server-side from the original — you don't pass them. The reply stays in the original thread and counts against the same send rate limits as POST /messages.

Path parameters

Request body

Recipient resolution

• Inbound original — To is the original Reply-To if present, otherwise the original sender. Cc is the original To + Cc.
• Outbound original — To and Cc reuse the original To and Cc.
• In both cases the replying mailbox, duplicates, and the original BCC recipients are removed.

The message detail (GET .../messages/{message_id}) returns the resolved reply_all_recipients ({ to, cc }) so UIs can prefill editable fields.

Request example

JSON

Response (201)

Returns a MessageResponse — the brand-new message representing the reply (same shape as a list item; body content is not included).

Error responses

Code examples

cURL

cURL

JavaScript

Python

POST /mailboxes/{email_address}/messages/{message_id}/forward

Forward a previously stored message out from this mailbox. A forward intentionally creates a new thread — it does not chain into the original conversation, matching the default behavior of Gmail, Outlook, and Apple Mail.

Forwards count against the same send rate limits as POST /messages and fire a message.forwarded webhook event on success (not message.sent).

Path parameters

Request body

At least one address is required across recipients.to, recipients.cc, and recipients.bcc.

Modes

• inline (default) — Renders the original body inline below a Gmail-style preamble that includes From:, Date:, Subject:, To:, and Cc: from the original. Original attachments are re-attached as direct outbound parts. Lossy: inline cid: images may break, and non-trivial multipart structure is flattened.
• wrapped — Attaches the original raw MIME as a single message/rfc822 part, semantically preserving all headers, body parts, attachments, and nested structure. Recipient clients either expand it inline (Gmail) or show it as a forwarded.eml attachment (Outlook). Use this for originals with inline images, calendar invites, or complex multipart. The result is semantically equivalent to the original, not byte-for-byte equivalent; DKIM-preserving forwarding is not supported in v1.

Forwarding behaviour

• Attachment type rejection applies only to caller-authored attachments, not to content carried over from the original message.
• Original-attachment bytes are not counted against the 25 MB caller cap. Only the 10 MB outbound limit on the final composed MIME applies to the combined output.
• The forward gets a brand-new Message-ID. The original is referenced via an X-Forwarded-Message-Id header.
• Filename collisions across original attachments and caller additional_attachments are deduplicated automatically (caller wins; originals get a forwarded- prefix and a numeric suffix).

Request example

JSON

Response (201)

Returns a MessageResponse — the brand-new message representing the forward (same shape as a list item; body content is not included).

Error responses

Code examples

cURL

cURL

JavaScript

Python

PATCH /mailboxes/{email_address}/messages/{message_id}

Update is_read or is_starred on a message. Omit a field to leave it unchanged.

This is how to mark mail read in bulk, to mark a message unread, or to mark read when you process from the list or thread routes (which never mark read on their own). Fetching a single inbound message with an API key marks it read automatically — see Get message.

Path parameters

Request body

Code examples

cURL

cURL

JavaScript

Python

DELETE /mailboxes/{email_address}/messages/{message_id}

Delete a message. Returns 204 No Content on success.

Deleting a message frees its storage immediately — the message and its associated storage overhead stop counting toward the inbox's storage cap right away.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

GET /mailboxes/{email_address}/messages/{message_id}/attachments/{filename}

Download an attachment from a message. By default, responds with a 302 redirect to a temporary download URL. Set redirect=false to get the URL as JSON instead.

Path parameters

Query parameters

Response (302) — redirect mode (default)

Redirects to a temporary download URL with a Content-Disposition: attachment header. The URL is valid for 15 minutes.

Response (200) — JSON mode

JSON

Error responses

Code examples

cURL

cURL

JavaScript

Python

MessageResponse (list items)

MessageDetailResponse (single message)

Includes all MessageResponse fields plus: