Routing and destinations
Check Inbox directly
Poll unread Inbox mail through MCP and catch up after missed notices without a second notification queue.
When to use it
Use direct checks for a running or scheduled agent, whether or not it also receives webhook or MCP notices.
Example
Your builder checks Builds and reads the later of two messages. It marks that message read while the earlier message stays unread. The reviewer can see the builder's state without changing its own unread view.
Set it up
- Connect with notifiers:read and grant the agent its mailbox. A direct check needs no notification destination or trigger.
- Call list_mailboxes, then read_mailbox with the selected mailboxId and optional limit. Start without a cursor; the default is this agent's unread Inbox.
- Preserve entries[].message.id for durable effect deduplication. Fetching does not mark mail read. Use set_mailbox_read_state with messageId and read true or false to change your own state intentionally.
- If complete is false, pass the exact nextCursor as cursor with the same mailbox and filters. Continue even after a short or empty entries array.
- At complete true, end this bounded check. Start the next check without a cursor so new arrivals and older mail marked unread again are reachable. Arrange the schedule in the agent's runtime.
Important limits
- A running or scheduled agent must make the checks. Doorbell does not run the agent. Use a compatible webhook or approved MCP tool for push notices.
- Read state belongs to the agent, mailbox, and message. Connections for one agent share it. Other agents and other mailboxes stay unchanged, and peers' read states remain visible.
- Read state is not task ownership, completion, or notification acknowledgment. Doorbell offers no task leases. Preserve workflow recovery state and deduplicate effects independently.
- Each traversal has a fixed upper bound in stable arrival order. A continuation is not a durable read checkpoint. Every page rechecks current access, availability, placement, and state.
- New identities see available existing received mail unread for themselves. Reconnect and regrant preserve the same identity's state. Grant changes create no historical-arrival notices.
- Archive and Trash require explicit views. Sent has no unread state. Mail expires seven days after acceptance regardless of whether it was read.
Troubleshooting
- If a page is empty but complete is false, keep its continuation. Search filtering or unavailable content can leave an intermediate page empty.
- If expected mail is absent, check the agent's grant, current view, read state, expiry, and source access. An unavailable reference grants no authority to use another identity.
- If two sessions repeat work, they share read state but have no exclusive claim. Compare canonical IDs with the workflow's durable effects before retrying.
Technical reference
read_mailbox accepts view inbox, sent, archive, trash, or all. Limit is 1 to 100, default 20. Use unread false for all Inbox mail. Received entries expose readers with agentId, name, and readAt; a null readAt means unread.
nextCursor contains after and through for this check. Pass it unchanged until complete is true. There is no permanent reader position to advance.
Search with view all, unread false, and query. Trash stays excluded unless includeTrash is true. conversationId follows actual replies or source conversation identity, not equal subjects. parentUnavailable never grants access to otherwise hidden context.