Documentation
Sign inGet started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Agent mailboxes

An agent mailbox is a real, addressable inbox your code owns. Mail sent to it lands in threads you can read, filter, reply to, and send from over the API. It's the two-way email loop an autonomous agent needs, without running an IMAP server or parsing raw MIME yourself.
A mailbox lives on the shared inbox.ai domain, or on your own receiving-enabled sending domain. Its address is claimed the moment you create it and stays yours: the local part is reserved to your workspace and is never handed to anyone else, even after you delete the mailbox.

Addresses

Every mailbox has one address, {local_part}@inbox.ai. You get an address two ways:
  • Generated: omit the local part and Bird mints a collision-free one for you (a7f3k2@inbox.ai). Always available.
  • Custom: ask for a specific local part (support@inbox.ai). Custom handles are first-come, first-served across all workspaces and are a paid-plan allowance; a free workspace uses generated addresses.
An address is immutable once created. To change it, create a new mailbox and delete the old one. The old local part is held for 30 days (its restore window) before it can be claimed again, and only ever by the workspace that held it.

Threads and messages

Received and sent mail is grouped into threads, one per conversation. A thread carries the participating addresses, an unread count, the direction of its latest message (inbound or outbound), and the timestamp of its most recent activity. Replies fold into the thread they answer; a fresh compose starts a new thread.
Each message in a thread exposes its headers, the extracted plain-text body (quote-stripped, so an agent reads the new content without the quoted history), the full HTML and raw source, and its attachments. Message IDs are prefixed by direction: rem_ for a received message, em_ for one you sent.

Deciding what gets in

Two controls sit in front of the inbox, both checked against the envelope sender rather than the forgeable From: header:
  • Receive policy: the mailbox-wide default. open accepts everything that passes authentication; a stricter policy admits only what your rules allow.
  • Receive rules: per-sender allow or block entries, matched on a full address or a domain (a domain rule also matches its subdomains). A block always beats an allow.
Mail that a rule blocks, or that fails DMARC, is still stored in the mailbox and stays readable: it is filed out of the inbox rather than dropped, and it wakes no webhook. Nothing a mailbox receives is silently discarded.

Sending

A mailbox sends two ways: reply to a message (the outbound message folds into that thread) or compose a new message (which opens a new thread). Mail sends from the mailbox's own address, with the display name and default Reply-To you configured on it. Delivery status folds back onto the sent message, so you can see whether a reply was delivered or bounced.

Events

Subscribe to the email_mailbox.* webhook family to drive an agent without polling: email_mailbox.message_received (inbound mail reached the inbox), email_mailbox.thread_created, and the delivery-status events for messages you send. Only inbox mail fans out; spam and rule-blocked mail is stored quietly, so a flooded mailbox can't amplify into a flood of webhooks. Inbox mail also fires the standard email.received event, so an existing inbound integration keeps working.
For a live view without webhook infrastructure, open the mailbox's event stream instead: GET /email/mailboxes/{mailbox_id}/events holds an SSE connection that pushes a thin notification — the event type plus the thread and message IDs — the moment anything happens in the mailbox. The stream carries spam and blocked arrivals too (a single connection can't be amplified the way webhooks can), so it's also the way to watch the junk folders live. Fetch full messages with the IDs each event carries. It's a live tail, not a log: nothing is replayed after a disconnect, so pair it with webhooks when you need durable delivery, and catch up with the list endpoints after a gap.

Retention and erasure

A mailbox retains its messages and threads for 30 days, after which they expire and are purged. Deleting a mailbox, or deleting the workspace or organization that owns it, erases its stored mail (bodies, attachments, and the received-message record) and releases its address back to the pool after the restore window.

Next steps