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.
List mailboxes GET
GET /mailboxesList all active mailboxes for your organization, newest first.
Response (200)
JSONCode examples
cURLGet mailbox GET
GET /mailboxes/{email_address}Get a single mailbox by its email address.
Path parameters
| Parameter | Type | Description |
|---|---|---|
email_address | string | Email address of the mailbox (local part or full address) |
Response (200)
JSONCode examples
cURLUpdate mailbox PATCH
PATCH /mailboxes/{email_address}Most of the mailbox's former mutable settings have moved to other surfaces. The one remaining field, filter_mode, is deprecated but still accepted on this route as a compatibility bridge — it forwards to the owning identity's mail_filter_mode. New integrations should set the canonical control directly on the identity instead.
Path parameters
| Parameter | Type | Description |
|---|---|---|
email_address | string | Email address of the mailbox (local part or full address) |
Filter mode is moving. The canonical control now lives on the agent identity as
mail_filter_mode— see Manage identities. Set it withPATCH /identities/{agent_handle}; it interprets the mail contact rules. Sendingfilter_modeon this mailbox PATCH is deprecated but still accepted and forwards to the identity'smail_filter_mode.
display_namehas moved. Display name is now an identity-level field; this endpoint rejectsdisplay_namewith422and a redirect-style message pointing atPATCH /identities/{agent_handle}.
Webhook configuration has moved. Mail event delivery is configured via the Webhook Subscriptions API, not on the mailbox resource.
Response (200)
Returns the updated mailbox object.
Mailbox object
| Field | Type | Description |
|---|---|---|
id | UUID | Unique mailbox identifier |
email_address | string | Full email address (e.g. sales-agent@inkboxmail.com) |
sending_domain | string | Bare domain the mailbox sends from, derived from email_address. Either the platform default (inkboxmail.com) or a verified custom domain registered to your org. |
filter_mode | string | Deprecated ("whitelist" or "blacklist"), mirroring the owning identity's mail_filter_mode. Still accepted on the mailbox PATCH as a compatibility bridge that forwards to the identity's mode; the canonical control is the identity's mail_filter_mode, set via PATCH /identities/{agent_handle} — see Manage identities. |
agent_identity_id | UUID | null | Agent identity that owns this mailbox. Always populated for active customer mailboxes. |
status | string | Lifecycle status: active or paused |
storage_used_bytes | integer | Bytes of mail currently stored in this mailbox. Always present. |
storage_limit_bytes | integer | null | Storage cap for this mailbox, in bytes (e.g. 2147483648 = 2 GiB). null when the route did not resolve a cap. |
created_at | string | Creation timestamp (ISO 8601) |
updated_at | string | Last update timestamp (ISO 8601) |
Mailbox storage. Storage counts inbound and outbound mail plus associated storage overhead. Deleting a message or a thread frees its space immediately. Sizes are byte counts:
2147483648bytes is 2 GiB. Caps vary by plan — see pricing.
- Pricing — per-plan mailbox storage caps
- Webhook Subscriptions — attach event-delivery URLs to a mailbox
- Mail contact rules — the allow/block list interpreted by the identity's
mail_filter_mode - Email guide — Filtering inbound mail — whitelist/blacklist walkthrough
