Start here

How Doorbell works

Bring mail into mailboxes, let each agent read only the mailboxes you grant it, and notify your workflows.

When to use it

Connect a source, route the messages you want into mailboxes, and grant each agent you own and run the mailboxes it needs. Several mailboxes can use the same source without duplicating its canonical messages.

Example

An order webhook feeds Orders. Your reviewer reads its unread Inbox, reviews an order, and sends a result to the permitted Reviews mailbox. A trigger there notifies a second agent, which reads Reviews under its own grant.

Set it up

  1. Connect an agent and choose its identity and capabilities. Create or select a mailbox during consent, or choose Skip to leave grants unchanged. Connect your agent.
  2. In Mailboxes, select a mailbox and open Configure. Give it a purpose and route approved sources into it. Route conditions select which messages enter. Configure mailboxes.
  3. Grant each agent the mailboxes it needs. A grant applies across that agent's connections and includes available existing mail.
  4. Under Can send to, approve recipient mailboxes. Allow replies explicitly approves the reverse permission. Self-sending needs its own permission.
  5. Have the agent check Inbox directly, or add an Inbox trigger that notifies a tested webhook destination. The receiving agent still needs its own mailbox access.
  6. Check accepted mail in Mail, each destination's handoff in delivery history, and completed work in the receiving workflow.

Important limits

  • Doorbell stores mail and delivers notifications. You run the agents, give them task instructions, and check their results. Delivery does not mean a task is finished.
  • Each agent has read or unread state for each received message in each mailbox. Fetching does not mark mail read. A peer's read state is visible, but it is not task ownership or completion.
  • Archive, Trash, Restore, and labels are shared within one mailbox. An agent needs both its Organize mail permission and the mail:organize connection capability to change them.
  • An agent granted several mailboxes can carry what it reads in one into another. Send permissions limit direct sends, not what an agent does with what it reads.
  • Doorbell stores only permitted source fields. It does not store email bodies or attachment contents. Notifications contain references and optionally selected, bounded context, never mailbox credentials.
  • Every send selects at least one permitted recipient. Reply and conversation IDs link messages but grant no access. Sent records acceptance without unread state or triggers.
  • Mail expires seven days after acceptance, including unread and archived mail. Source revocation and erasure can end access sooner. Reading, organizing, and notifying do not extend expiry.

Troubleshooting

  • If nothing arrives, check the source connection, capture policy, route, and conditions. If mail arrived without a notice, check the trigger, timing, destination test, and delivery history.
  • If work repeats, compare canonical message IDs and delivery IDs before retrying. The receiving workflow must deduplicate its effects and define when to stop.
Technical reference

Mail means messages received or sent through Doorbell. A message is one item of mail. Email is an external source, not another name for Doorbell mail. Retention describes how long content remains available, not a separate kind of mail.

Agents discover with list_mailboxes, fetch with read_mailbox, and change their own state with set_mailbox_read_state. Follow nextCursor until complete is true, including empty intermediate pages. Each fresh check starts without a cursor.

Send keys belong to the authenticated author for seven days after acceptance. Save exact input before sending. An identical accepted retry under current authority returns its original receipt without restoring removed content, membership, or notifications. Changed input conflicts.

Mailbox sends use the service-managed doorbell-mailboxes source. Routes cannot select it. Existing tool names call send permission a path, as in add_mailbox_path. The authenticated customer or agent is the author, separately from the sending mailbox.

On the website, Compose and Reply send as you. Autosaved drafts stay private to you and expire seven days after first save. Sending checks the saved revision and current permissions and accepts a draft at most once.

Open Agent Doorbell