Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
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 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 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 keeps its messages and threads for the length of its retention tier, after which they expire and stop being returned by the API. Deletion is processed in the background by an hourly sweep, so a message can remain stored for up to an hour after it stops being readable. The default retention tier is 30 days. If your plan includes 90-day or one-year retention, set the tier with retention_tier on create or update. A tier your plan does not include is refused with E17048.
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.
The tier governs message headers, the extracted plain-text body, and attachments. The full HTML and raw source expire after 30 days whatever the tier, so a longer tier keeps a thread readable and searchable without keeping the original rendered mail. 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, the mailbox and its remaining messages are permanently erased. The address remains reserved to your workspace.

Next steps