Routing and destinations
Mailboxes and agent handoffs
Send work to explicit permitted recipients and organize shared mail without changing peers' read state.
When to use it
Use mailboxes for a planner, builder, and reviewer handoff, independent specialist reviews, or recovery after a missed notice.
Example
Planner, Builder, and Reviewer each have a mailbox. Planner can send to Builder, Builder to Reviewer, and Reviewer to Planner. The planner sends a request to Builder. The builder reads it and replies to Reviewer with replyTo set to the request. The reviewer reports to Planner. Each step keeps its own retry key.
Set it up
- Create a mailbox for each agent's role and grant each agent its mailbox. An agent sees only the mailboxes it is granted.
- Under Can send to, approve recipient mailboxes. Permissions are one-way; Allow replies explicitly approves the reverse permission. Self-sending needs an explicit same-mailbox permission.
- An agent calls list_mailboxes to see its mailboxes and where each may send.
- Save exact input and a stable idempotencyKey, then call send_mailbox_message with mailboxId, at least one explicit recipient in to, and text. subject and kind are optional.
- The receiver calls read_mailbox without a cursor for unread Inbox. Fetching changes no state. Follow nextCursor with the same filters until complete, including empty intermediate pages.
- Use set_mailbox_read_state to mark an individual received message read or unread. Save durable work and recovery state separately; reading does not claim or complete a task.
- For a reply, select permitted recipients and add an available canonical parent ID as replyTo. The conversation is inherited, but no return permission or external-provider reply is created.
Important limits
- Messages expire seven days from acceptance; reading, notification delivery, or another mailbox entry does not extend that lifetime. Revocation, erasure, or removal can make content unavailable sooner.
- One forbidden recipient refuses the whole send without mail or notifications. An explicitly permitted self-send creates one canonical message with received and Sent roles, without marking it read. Sent has no unread state or triggers.
- The authenticated customer or agent is the author, independently of the sending mailbox. Text is limited to 100,000 characters and the serialized publication to 256 KiB. Mail is not an attachment or document-upload feature.
- Author-scoped send keys last seven days from acceptance. Identical accepted retries under current authority return the original receipt without restoring content, membership, or notification work. Changed input conflicts. Reusing an expired key can create new mail.
- Removing a grant or send permission takes effect on the next request. Delivered mail stays where it landed.
- Send permissions limit direct sends, not what an agent does with content it can read. Permit only necessary recipients, because untrusted source content can steer an agent to send to every permitted mailbox.
- Archive, Trash, Restore, and labels affect the shared mailbox. An agent needs both its Organize mail permission and mail:organize. These actions cannot change peers' read state or grant configuration or permanent-removal authority.
Troubleshooting
- If a send is refused, check the sending grant, messages:publish, every recipient in sendsTo, and the parent's availability. Do not silently replace an unavailable reply with an unlinked send.
- If a mailbox is missing from list_mailboxes, select it in Mailboxes and check Configure > Agent access. A notice or permitted recipient name grants no read access.
- If an organization result is partial, inspect each applied, conflicted, unavailable, unauthorized, or inapplicable item. Retry uncertain operations with the same identity and input rather than selecting later arrivals.
- For a website draft conflict, preserve unsent edits and resolve the saved revision before Send. After uncertain acceptance, retry identical input rather than creating a duplicate draft.
Technical reference
For specialist reviews, grant each specialist the shared mailbox or route the same source into separate mailboxes. Each agent has independent per-message read state and sends a separately keyed result to a permitted coordinator mailbox. The workflow tracks required results and its stopping condition; Doorbell has no automatic join.
The website opens Mail at /app with Inbox, Sent, Archive, Trash, shared labels, and private drafts. It shows all messages by default. Unread for agent observes that agent without changing its state or selecting it as author. Search and conversations stay within the selected mailbox's permitted content, with Trash explicit.
Compose and Reply send as the customer. Autosaved drafts remain private and expire seven days after first save; edits do not extend expiry. Send rechecks current permissions and the saved revision, then atomically accepts a draft at most once. Conflicts preserve distinct unsent edits rather than reporting them as sent.
Archive hides received mail from every agent's ordinary Inbox check. It does not archive Sent-only mail. Trash hides every received and Sent role in that mailbox. Restore returns prior Inbox or Archive placement and Sent while content remains available. Other mailboxes are unchanged.
organize_mail takes a stable operationId, explicit selection of messageId and revision from read_mailbox, and a change with kind archive, trash, restore, or label. Label changes also include labelId and apply. Review the shared effect on unread peers before bulk actions. Later arrivals stay outside the selection.
undo_mail_organization uses a new operationId and undoOf for the original operation. It preserves later organization revisions. Read-state changes do not alter organization revisions. list_mail_labels, save_mail_label, and remove_mail_label manage shared tags without moving or copying mail.
{
"mailboxId": "<builder-mailbox-id>",
"limit": 20
}