Mailboxes

Mailboxes are the email addresses your agents send and receive mail from. Each mailbox is owned 1:1 by an agent identity — mailboxes are created and destroyed atomically with the identity. To provision a mailbox, create an identity; to remove one, delete the identity.

This page covers the read and update surface on the mailbox itself.

GET /mailboxes

List all active mailboxes for your organization, newest first.

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

GET /mailboxes/{email_address}

Get a single mailbox by its email address.

Path parameters

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

PATCH /mailboxes/{email_address}

Update mutable fields on a mailbox. Only supplied fields are modified.

Path parameters

Request body

display_name has moved. Display name is now an identity-level field; this endpoint rejects display_name with 422 and a redirect-style message pointing at PATCH /identities/{agent_handle}.

Webhook configuration has moved. Mail event delivery is configured via the Webhook Subscriptions API, not on the mailbox resource.

Request example

JSON

Response (200)

Returns the updated mailbox object. When this request changes filter_mode to a new value, the response also includes a filter_mode_change_notice object counting rules that are now redundant under the new mode (see the Mailbox object below). The field is null on any other PATCH and on GET and list responses.

Code examples

cURL

cURL

JavaScript

Python

filter_mode_change_notice

• Webhook Subscriptions — attach event-delivery URLs to a mailbox
• Mailbox contact rules — the allow/block list interpreted by filter_mode
• Email guide — Filtering inbound mail — whitelist/blacklist walkthrough