Skip to content

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 /mailboxes

List all active mailboxes for your organization, newest first.

Query parameters

ParameterTypeDescription
limitintegerMaximum rows to return (1–101). Omit to return all visible mailboxes.
offsetintegerRows to skip (0–10,000). Defaults to 0.

Response (200)

JSONJSON

Code examples

Get mailbox GET

GET /mailboxes/{email_address}

Get a single mailbox by its email address.

Path parameters

ParameterTypeDescription
email_addressstringEmail address of the mailbox (local part or full address)

Response (200)

JSONJSON

Code examples

Update 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

ParameterTypeDescription
email_addressstringEmail 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 with PATCH /identities/{agent_handle}; it interprets the mail contact rules. Sending filter_mode on this mailbox PATCH is deprecated but still accepted and forwards to the identity's mail_filter_mode.

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.

Response (200)

Returns the updated mailbox object.

Mailbox object

FieldTypeDescription
idUUIDUnique mailbox identifier
email_addressstringFull email address (e.g. sales-agent@inkboxmail.com)
sending_domainstringBare 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_modestringDeprecated ("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_idUUID | nullAgent identity that owns this mailbox. Always populated for active customer mailboxes.
statusstringLifecycle status: active or paused
storage_used_bytesintegerBytes of mail currently stored in this mailbox. Always present.
storage_limit_bytesinteger | nullStorage cap for this mailbox, in bytes (e.g. 2147483648 = 2 GiB). null when the route did not resolve a cap.
created_atstringCreation timestamp (ISO 8601)
updated_atstringLast 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: 2147483648 bytes is 2 GiB. Caps vary by plan — see pricing.