Mailboxes

A mailbox is an address with its own inbox, gate mode, allow list and webhook. It is either an agent mailbox or a shared one, and mail_mailboxes reports which as its kind.

Agent mailboxes

Each connected agent has one mailbox of its own, such as ada@agents.example.com. Only that agent can read it, and in the dashboard only the person who connected the agent can see it. An agent never sees another agent's mailbox, and asking for it by id returns nothing.

The agent finds its address by calling mail_mailboxes and taking the one of kind agent. If it has none yet, the answer carries a notice that says why.

Shared mailboxes

A shared mailbox belongs to the workspace, such as team@. Every member can read it, and so can every agent connected to the workspace. Shared mailboxes need the Team plan. Only an agent that a workspace owner connected can create one, with mail_mailbox_create, and only while the plan has room.

Use a shared mailbox when a role, not one agent, owns the mail: support, sales, scheduling. People write to a stable address, and agents come and go behind it.

Addresses

An address is a name before the @ and a domain after it. By default the domain is the Mail domain. On Solo and Team it can be a custom domain your workspace has verified.

• mail_mailbox_rename changes the name, and optionally the domain. People who wrote to the old address bounce afterwards, so do it once and early.
• A name that is already in use is refused with address_taken, and a reserved one with address_reserved.
• Any agent can move its own address back to the Mail domain. Only an agent a workspace owner connected can put one on a custom domain.

Status

A mailbox is open or closed. Disconnecting an agent, or revoking its last Mail key, closes its mailboxes, and drafts still waiting for approval fail. A closed mailbox refuses sends with mailbox_closed. A mailbox whose sending was paused refuses them with mailbox_paused.

What the workspace shares

Mailboxes and sends are pooled across the workspace, not counted for each inbox. The plan sets how many mailboxes a workspace may have and how many messages it may send. See Limits.

Each mailbox keeps its own gate mode, allow list and webhook. A person sets the first two in the dashboard. An agent reads them with mail_rules and cannot change them. Mail older than the plan keeps is deleted.