Jump to

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.

List messages GET

GET /mailboxes/{email_address}/messages

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

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Opaque cursor from a previous response's `next_cursor`
`limit`	integer	50	Results per page (1–100)
`direction`	string	—	Filter by `"inbound"` or `"outbound"`. Omit for all messages

Response (200)

JSON

Code examples

Get message GET

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

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

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message

Response (200)

JSON

Code examples

Send message POST

POST /mailboxes/{email_address}/messages

Compose and send an email from a mailbox. The message is sent via SES, and bodies are stored in S3. Threading is automatically resolved from in_reply_to_message_id.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the sending mailbox

Request body

Field	Type	Required	Description
`recipients.to`	string[]	Yes	Primary recipients (at least one)
`recipients.cc`	string[]	No	CC recipients
`recipients.bcc`	string[]	No	BCC recipients (excluded from headers, delivered separately)
`subject`	string	Yes	Email subject line (max 998 chars)
`body_text`	string	No	Plain-text body
`body_html`	string	No	HTML body
`in_reply_to_message_id`	string	No	RFC 5322 Message-ID of the email being replied to
`attachments`	object[]	No	File attachments (see below). Blocked types: `.exe`, `.bat`, `.scr`. Max total 25 MB.

AttachmentUpload object:

Field	Type	Description
`filename`	string	File name (max 255 chars)
`content_type`	string	MIME type (e.g. `application/pdf`)
`content_base64`	string	Base64-encoded file content

Request example

JSON

Response (201)

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

Error responses

Status	Description
429	Mailbox has exceeded 600 sends in the last hour. Response includes `Retry-After` (seconds), `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers

Code examples

Update message flags PATCH

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

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

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message

Request body

Field	Type	Required	Description
`is_read`	boolean	No	Mark as read (`true`) or unread (`false`)
`is_starred`	boolean	No	Star or unstar the message

Code examples

Delete message DELETE

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

Delete a message. Returns 204 No Content on success.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message

Code examples

Download attachment GET

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

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

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message
`filename`	string	Attachment filename (must match exactly with `attachment_metadata[].filename`)

Query parameters

Parameter	Type	Default	Description
`redirect`	boolean	`true`	`true` returns a `302` redirect to the download URL. `false` returns the URL as JSON.

Response (302) — redirect mode (default)

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

Response (200) — JSON mode

JSON

Field	Type	Description
`url`	string	Presigned download URL (valid for 15 minutes)
`filename`	string	Attachment filename
`expires_in`	integer	URL expiration time in seconds

Error responses

Status	Description
403	Mailbox does not belong to your organization
404	Mailbox, message, or attachment not found

Code examples

Message object

MessageResponse (list items)

Field	Type	Description
`id`	UUID	Unique message identifier
`mailbox_id`	UUID	Owning mailbox
`thread_id`	UUID \| null	Conversation thread, if resolved
`message_id`	string	RFC 5322 Message-ID header value
`from_address`	string	Sender address
`to_addresses`	string[]	Primary recipients
`cc_addresses`	string[] \| null	CC recipients
`subject`	string \| null	Email subject line
`snippet`	string \| null	First ~200 chars of the plain-text body
`direction`	string	`inbound` or `outbound`
`status`	string	`queued`, `sent`, `delivered`, `bounced`, `failed`, or `received`
`is_read`	boolean	Whether the message has been read
`is_starred`	boolean	Whether the message is starred
`has_attachments`	boolean	Whether the message has attachments
`created_at`	string	Creation timestamp (ISO 8601)

MessageDetailResponse (single message)

Includes all MessageResponse fields plus:

Field	Type	Description
`body_text`	string \| null	Plain-text body
`body_html`	string \| null	HTML body
`bcc_addresses`	string[] \| null	BCC recipients
`in_reply_to`	string \| null	RFC 5322 In-Reply-To header
`references`	string[] \| null	RFC 5322 References headers
`attachment_metadata`	object[] \| null	Attachment descriptors (filename, content_type, size, s3_key)
`ses_message_id`	string \| null	SES-assigned message ID (outbound only)
`updated_at`	string	Last update timestamp (ISO 8601)