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

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 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 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 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.
    • 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: 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, 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 retains its messages and threads for 30 days, after which they expire and are purged. Deleting a mailbox 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