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 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 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.
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, both checked against the envelope sender rather than the forgeable From: header:
- Receive policy: the mailbox-wide default.
- open accepts everything that passes authentication.
- 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.
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. 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, 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, connect to GET /v1/email/mailboxes/{mailbox_id}/events. The SSE stream sends the event type, thread ID, and message ID for mailbox activity, including spam and blocked arrivals. Fetch full messages with those IDs. The stream does not replay events after a disconnect. Use webhooks for durable delivery, and use the list endpoints to catch up after a gap.
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.
| Content or action | Retention window |
|---|---|
| Message headers, extracted text, and mailbox attachments | Selected tier: 30, 90, or 365 days |
| Original HTML and plain-text bodies | 30 days on every tier |
| Raw MIME for received messages | 30 days on every tier; sent messages have no stored raw MIME |
| Forwarding a message in the dashboard | Requires original content within its 30-day window |
| Reading extracted text or replying with new content | Available while the message is retained |
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.