Agent mailboxes

An agent mailbox is an addressable inbox that your code manages through the API. Read and filter its threads, reply to messages, or compose new mail without running an IMAP server or parsing raw MIME.

A mailbox lives on the shared inbox.ai domain or on one of your own sending domains. 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 we generate a collision-free one for you (a7f3k2@inbox.ai). Always available.
• Custom: ask for a specific local part (support@inbox.ai). Custom handles are globally unique, first-come, first-served, and 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 remains reserved for your workspace.

On your own domain, pass domain on create and pick any local part, such as support@acme.com. How mail reaches the mailbox depends on the domain's setup:

• Receiving enabled: mail arrives directly once the domain's MX records point to us. See Receiving email.
• Receiving not enabled: the domain needs verified ownership, and your MX records stay as they are. The mailbox gets a forwarding_address, such as k7q2mzxw4h6p5ra3@eu1.inbound.bird.com. Add a forwarding rule for support@acme.com at your current email provider, pointing to that address. Forwarded mail lands in the mailbox, and replies and new mail still go out from support@acme.com.

For an existing own-domain mailbox without a forwarding address, open Mailbox settings and choose Set up forwarding. This keeps the mailbox address, messages, receive policy and retention unchanged. It requires mailbox management write permission and verified domain ownership in the workspace. A domain claimed for receiving by another workspace cannot get a new forwarding address here.

The API equivalent is POST /v1/email/mailboxes/{mailbox_id}/forwarding-address, with no request body. It returns the full mailbox with its forwarding_address. Repeating the request returns the same address, including after delete and restore; it does not rotate the address or resume a suspended mailbox. The CLI command is bird email mailboxes forwarding-address create <mailbox-id>.

Creating an address does not configure forwarding at your provider, change DNS or verify delivery. If your provider already receives mail, keep its MX records and add the forwarding rule there. If MX records point to us, first prepare the mailbox and forwarding rule at your provider, then move the MX records to that provider. Keep Receiving enabled while the DNS change propagates. Test forwarding before turning off direct receiving.

Gmail and Google Workspace send a confirmation message to a new forwarding address. Open it in this mailbox and follow its confirmation instructions to finish setup. Microsoft 365 may require an administrator to allow external forwarding. Under the replies_only or allowlist policy, check blocked mail; also check Spam and receive rules. A drop policy does not retain the confirmation: change the policy explicitly before requesting a fresh confirmation. A suspended mailbox must be resumed to accept messages normally.

Keep a copy at your provider while testing. Send a fresh message from another account to the original mailbox address, then open the received message in this mailbox. Its Delivered to address must match the forwarding_address to demonstrate delivery through that route. The API exposes this as delivered_to. Mailbox message counts include outbound activity and do not verify forwarding.

To return to direct delivery, enable Receiving, restore our MX records and test direct delivery before removing your provider's forwarding rule. Overlapping routes, such as Google Workspace dual delivery, can put each message in the mailbox twice. The forwarding address keeps working when direct receiving is turned off and stays the same across delete and restore.

Threads and messages

Received and sent mail is grouped into threads, one per conversation. A thread has 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 exposes headers, extracted plain text with quoted history removed, and attachments. Original bodies are available for 30 days; raw MIME is available only for received messages. 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:

• Receive policy: the mailbox-wide default.
  • open accepts mail after block rules. SPF and DKIM results do not change this admission policy.
  • replies_only accepts only mail that continues a thread already in the mailbox.
  • allowlist accepts only senders your rules allow, plus replies to an existing thread.
  • drop discards everything, no exceptions.
• 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.

A block rule matches the envelope sender or the From: address. An allow rule matches the envelope sender, or the From: address when the message has a valid DKIM signature from that address's domain. The From: header is easy to forge, so an unsigned From: never earns an allow. This covers forwarded mail, where Gmail and Microsoft 365 replace the envelope sender with their own address, and mail from sending services that use a separate bounce address. Forwarded mail without a surviving DKIM signature still matches on the forwarding service's address.

Mail that a rule blocks is stored in the mailbox and stays readable. It is filed out of the inbox and sends no webhook. The one exception is a mailbox set to drop, which discards everything at the door instead of filing it.

Sending

A mailbox sends two ways over the API: reply to a message (the outbound message folds into that thread) or compose a new message (which opens a new thread). In the dashboard, open a message and choose Forward to send its original body and attachments to new recipients, within the original content's 30-day window. Mail sends from the mailbox's own address, using its name as the sender name and its configured default Reply-To. When name is unset, the sender name falls back to display_name. 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. Both events carry authentication results. Check those fields before automated routing: inbox delivery alone does not mean the sender was verified.

Retention and erasure

A mailbox's retention tier controls how long you can read message headers, extracted text, and mailbox attachments, measured from sending or receipt. The default is 30 days. If your plan includes 90-day or 365-day retention, set retention_tier on create or update. A tier your plan does not include is refused with E17048.

For example, on day 40 a message in a 90-day mailbox still has readable, searchable extracted text and retained attachments. You can reply with new content, but you cannot open the original body, download its raw MIME, or forward it. Extracted text is limited to 64 KiB per message and can omit parts of the original. Attachments stored before extended attachment retention was enabled keep their original expiry of approximately 31 days; changing tiers does not migrate them. Raising the tier cannot recover content that has already been deleted.

Messages stop being returned by the API when their retention expires. An hourly sweep processes deletion in the background; physical cleanup can lag behind API expiry.

Lowering the tier takes effect on reads immediately: anything older than the new cutoff stops being returned at once. You have ten minutes to undo it, and ten minutes is the only guarantee: raise the tier again inside that window and nothing is lost. Past it the stranded messages become eligible for deletion and the next hourly sweep takes them, so a later raise recovers only whatever the sweep has not reached.

Raising to a tier your plan includes is accepted at any time, including while an earlier change is still being applied. The background update is independent of the ten-minute undo window. Lowering a second time is accepted after the first change has updated every stored message. The update starts every ten minutes and can take hours for large mailboxes. Until it completes, the API returns E17050; retry later.

If your plan sets a finite mailbox storage allowance, one allowance is shared by every live or restorable mailbox. Each mailbox reports its share as size_bytes. A plan without a finite allowance has unlimited mailbox storage. Once the mailboxes together reach a finite allowance, sending is refused with E17049 until you free space in any of them.

Deleting a mailbox stops it from receiving mail immediately. The mailbox can be restored for 30 days, while normal message-retention expiry continues. After 30 days, permanent erasure removes the mailbox and its remaining messages. Once permanent erasure starts, restore is refused even if cleanup is still in progress. The address remains reserved to your workspace.

Next steps

• Claim your first mailbox: the API happy path from create to reply.
• Build with AI: drive mailboxes from an agent via the MCP server.