Inboxes

An inbox is a receiving address plus the rules applied to the mail that arrives on it. Eight tools, including the two that manage the allowed-recipients list.

See the Inbox model for the shape of the returned object.

---

inboxes_list

Read · scope inbox/inboxes · permission inboxes.list · GET /inboxes

List inboxes in the selected workspace. Cursor-paginated.

Parameter	Type	Description
cursor	string	Opaque cursor from a previous page.
limit	integer	Page size, default 25, max 100.
sort	string	Sort keys, - prefix for descending.
status	active | inactive	Filter by status.
agent_id	string (uuid)	Only inboxes bound to this agent.
slug	string	Filter by slug.
email	string	Filter by receiving address.
external_id	string	Filter by the id in your system.
created_at_gte	string	created_at on or after this ISO 8601 timestamp.
created_at_lte	string	created_at on or before this ISO 8601 timestamp.

inboxes_get

Read · scope inbox/inboxes · permission inboxes.show · GET /inboxes/{id}

Fetch one inbox by internal id or external_id.

Parameter	Type	Description
id required	string	Internal id or external_id.

inboxes_create

Write · scope inbox/inboxes + write · permission inboxes.create · POST /inboxes

Create an inbox. The receiving address is composed server-side as {organization}.{workspace}.{inbox}@<domain> and is live immediately — no AWS call is involved. 409 on a slug collision in the same workspace, 422 when the composed local part exceeds 64 characters.

Parameter	Type	Description
label required	string	Display name, 1–120 chars.
slug	string	Lowercase, dasherized, max 20 chars. Last segment of the receiving address; derived from the label when omitted.
external_id	string	Id of the record in your system.
agent_id	string (uuid) | null	Agent that processes mail for this inbox.
allowed_recipients	string[]	When set, only mail whose envelope sender is in this list is accepted.
filters	object[]	Acceptance rules applied to incoming mail.
attachments_allow	boolean	Whether attachments are accepted.
attachments_max_file_number	integer	Maximum number of attachments.
attachments_max_file_size	integer	Maximum size per attachment, in bytes.
attachments_max_total_size	integer	Maximum total attachment size, in bytes.
attachments_allow_rules	array|null	Allow list of attachments; each rule needs extensions, filename_pattern or both — see attachment allow rules. null clears it.
custom_metadata	object	Free-form JSON owned by the caller.
idempotency_key	string	Replay guard, 8–255 chars.

inboxes_upsert

Write · scope inbox/inboxes + write · permission inboxes.create · PUT /inboxes

Create or update an inbox, matched by id, then external_id, then email. Omitted fields keep their stored value.

Parameter	Type	Description
id	string (uuid)	Match by internal id first.
email	string	Match by receiving address, after id and external_id.
label	string	Display name, 1–120 chars.
slug	string	Lowercase, dasherized, max 20 chars.
external_id	string	Match key in your system.
agent_id	string (uuid) | null	Agent that processes mail for this inbox.
allowed_recipients	string[]	Accepted envelope senders.
filters	object[]	Acceptance rules.
attachments_allow	boolean	Whether attachments are accepted.
attachments_max_file_number	integer	Maximum number of attachments.
attachments_max_file_size	integer	Maximum size per attachment, in bytes.
attachments_max_total_size	integer	Maximum total attachment size, in bytes.
attachments_allow_rules	array|null	Allow list of attachments; each rule needs extensions, filename_pattern or both — see attachment allow rules. null clears it.
custom_metadata	object	Free-form JSON.
idempotency_key	string	Replay guard.

inboxes_update

Write · scope inbox/inboxes + write · permission inboxes.update · PATCH /inboxes/{id}

Update an inbox. Changing slug repoints the receiving address — mail sent to the previous one stops arriving. Filter changes apply to future mail only.

Parameter	Type	Description
id required	string	Internal id or external_id.
label	string	Display name, 1–120 chars.
slug	string	Lowercase, dasherized, max 20 chars.
external_id	string	Id in your system.
agent_id	string (uuid) | null	Agent that processes mail for this inbox.
allowed_recipients	string[]	Accepted envelope senders.
filters	object[]	Acceptance rules.
attachments_allow	boolean	Whether attachments are accepted.
attachments_max_file_number	integer	Maximum number of attachments.
attachments_max_file_size	integer	Maximum size per attachment, in bytes.
attachments_max_total_size	integer	Maximum total attachment size, in bytes.
attachments_allow_rules	array|null	Allow list of attachments; each rule needs extensions, filename_pattern or both — see attachment allow rules. null clears it.
custom_metadata	object	Free-form JSON.

inboxes_delete

Destructive · scope inbox/inboxes + write · permission inboxes.delete · DELETE /inboxes/{id}

Soft-delete an inbox. Incoming mail for that address becomes recipient_unknown; the slug is released and can be reused.

Parameter	Type	Description
id required	string	Internal id or external_id.

inboxes_add_recipient

Destructive · scope inbox/inboxes + write · permission inboxes.update · POST /inboxes/{id}/recipients

Add one address to allowed_recipients. Idempotent — 200 if already present, 201 if new.

Parameter	Type	Description
id required	string	Internal id or external_id.
email required	string	Address to allow.

inboxes_remove_recipient

Destructive · scope inbox/inboxes + write · permission inboxes.update · DELETE /inboxes/{id}/recipients

Remove one address from allowed_recipients. 404 when the address is not in the list.

Parameter	Type	Description
id required	string	Internal id or external_id.
email required	string	Address to remove.