Start here
Set up your first mailbox
Create a mailbox, route a source into it, grant it to an agent, and check a live event.
When to use it
Start with one mailbox, one source, and one agent. You can add more routes, mailboxes, and triggers later.
Example
An order webhook sends order.status set to needs_review. A route admits only those orders into Orders. Your reviewer checks Orders directly or receives an Inbox notice at its tested webhook.
Set it up
- Sign in with your invited address and open Agents > Connect your agent. Choose the agent identity and review its requested capabilities. Connect your agent.
- Choose Create mailbox, Use existing, or Skip on consent. A new Messaging connection can use this customer-approved mailbox setup without becoming an admin.
- Under Integrations > Sources, connect a source and review what it can capture. Open Sources.
- In Mailboxes, select the mailbox and open Configure to grant additional agents and add a route with any needed conditions. Configure mailboxes.
- For sends, approve recipients under Can send to. A source route alone does not approve an internal recipient.
- For push notices, create and test a webhook or MCP tool under Integrations > Destinations, then add an Inbox trigger in Configure. Direct Inbox checks run without a destination or trigger. Open Destinations.
- Send a fresh message that the source captures and check the mailbox in Mail. Also try a nonmatching control. If you use a trigger, check notification handoff separately from the agent's work.
Important limits
- Consent commits authorization and its mailbox choice together. Skip preserves existing grants. It does not connect sources, approve recipients, or enable notifications.
- Routes and triggers apply to later acceptance. Guarded backfill can add eligible existing mail silently, but cannot recover activity Doorbell never observed.
- Stored email details apply to every mailbox the account feeds. Your agent needs its own tools and permission to read email bodies.
- An active trigger needs a destination tested at its current version with no activation block. A fetch-first receiver needs separately approved mailbox access. A context-only receiver can use explicitly selected fields within its existing task authority.
- Configuring a mailbox through an admin agent does not grant it to that agent.
Troubleshooting
- If a route is refused, the source may not store the field in your condition. Review capture before changing it, then save the route again.
- If your agent has neither a webhook nor a compatible MCP tool, use a running or scheduled agent to check Inbox directly. Doorbell does not run the agent.
Technical reference
Agent-led setup needs an admin agent, one authorized with configuration:write. Each change needs your approval and approved: true. Check list_all_mailboxes before creating another mailbox.
save_mailbox takes title and description. save_mailbox_route takes mailboxId, source: {family,instanceId}, and when. Route conditions use source-relative paths such as order.status or subject. list_routable_sources shows what each source stores, and set_source_capture changes it.
grant_mailbox takes mailboxId and agentId from list_agents. Approve organize: true separately when needed. add_mailbox_path takes fromId, toId, and optional bothDirections. Self-sending requires an explicit same-mailbox permission.
save_mailbox_trigger takes mailboxId, name, destinationId, optional id, active, rule, match, and timing. The only direction is inbox. A rule uses event data paths such as fields.order.status; match verifies trusted source and optional internal author identity.
Pause a trigger by saving it with active: false, or remove it with remove_mailbox_trigger. delete_mailbox removes the mailbox, its routes, triggers, grants, and entries, not canonical messages in other mailboxes, sources, or shared webhooks.