The Mailbox API for agents that answer their own email.
A real inbox your code owns. Mail lands as threads; your agent reads and replies over the API. No IMAP, no MIME parsing.
# Claim an address on inbox.ai
curl -X POST https://us1.platform.bird.com/v1/email/mailboxes \
-H "Authorization: Bearer $BIRD_API_KEY" \
-d '{
"domain": "inbox.ai",
"local_part": "goldcrest",
"display_name": "Goldcrest Support"
}'
{
"id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
"address": "goldcrest@inbox.ai",
"receive_policy": "open",
"state": "active"
}
# Mail arrives; your webhook fires
POST /your-webhook-endpoint
{ "type": "email_mailbox.message_received", "data": { "thread_id": "thr_…", … } }
Claim, compose, and reply in the language you already use.
SDKs, CLI, and the hosted MCP server all speak the same loop.
Every surface runs the same four calls: claim an address, wait for a webhook, read the new content, and reply. Pick your runtime; the contract is identical.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
// Claim an address on inbox.ai
const mailbox = await bird.mailbox.create({
domain: "inbox.ai",
local_part: "support",
display_name: "Acme Support",
receive_policy: "open",
});
// Send a message from the mailbox
await bird.mailbox.compose(mailbox.id, {
to: ["alice@example.com"],
subject: "Your request has been received",
text: "We'll get back to you within one business day.",
});
Claim, receive, read, reply.
The whole loop is four calls.
The address is yours from the first call, and on inbox.ai it is permanently reserved to your organization. Nothing polls: step 02 is the wake, over webhook. The examples are plain REST; the SDKs, the CLI, and the hosted MCP server run the same loop.
curl -X POST https://us1.platform.bird.com/v1/email/mailboxes \
-H "Authorization: Bearer $BIRD_API_KEY" \
-d '{"domain": "inbox.ai", "receive_policy": "open"}'
{
"id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
"address": "k7mq3vx2npr5wcj4tzh6@inbox.ai",
"state": "active"
}
curl -X POST https://us1.platform.bird.com/v1/email/mailboxes \
-H "Authorization: Bearer $BIRD_API_KEY" \
-d '{"domain": "inbox.ai", "receive_policy": "open"}'
{
"id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
"address": "k7mq3vx2npr5wcj4tzh6@inbox.ai",
"state": "active"
}
You decide what gets in.
Nothing disappears.
A receive policy and per-sender rules run against the envelope sender; a block always beats an allow. Mail blocked by a sender rule is stored silently — you can still read it, and it fires no webhooks. (The `drop` policy discards mail entirely and does not store it.)
The model reads the message.
Not the archaeology.
Every message exposes headers, HTML, raw source, and attachments. The field your agent actually wants is extracted_text: the new content, quote-stripped. Context lives in the thread, not in forty lines of quoting.
What you can use Mailboxes for.
Four jobs a mailbox does on day one.
A support inbox the agent runs.
Every conversation is a thread; the agent answers in-thread and flags the unsure ones with a label a human watches.
Everything in the box.
The full surface at a glance.
Inbox API. Claim an address in one call: generated on inbox.ai, a custom handle, or your own domain.
MCP & SDKs. A hosted MCP server for agents; SDKs and the CLI for everything else.
Threads & labels. One thread per conversation; Gmail-style labels with a single PATCH grammar.
extracted_text. The new content, quote-stripped, ready to hand to the model.
Attachments. Headers, HTML, raw source, and attachments, all over the API.
Events. The email_mailbox.* webhook family: message_received, thread_created, message_sent, message_delivered, message_failed.
Receive rules. A policy plus per-sender allow and block, checked against the envelope sender.
Thread filters. Filter every mailbox's threads by label, participant, subject, or read state via the API.
Scoped keys. mailbox reads and writes conversations; mailbox_management administers.
Suppression-aware sends. Replies declare marketing or transactional; the suppression list is enforced by category.
Mail lands.
Your agent wakes.
Webhooks for durable delivery. Only inbox-placement mail fans out to webhooks — spam and blocked mail is stored silently.
POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
{
"type": "email_mailbox.message_received",
"timestamp": "2026-07-23T14:11:02Z",
"data": {
"thread_id": "thr_01krdh2p8qz3m9wv6xf0abcnde",
"message_id": "rem_01krdh3v7t2j5nqx8fw4mzp6bc"
}
}
email_mailbox.message_receivedInbound mail reached the inbox.email_mailbox.thread_createdA new conversation opened.email_mailbox.message_sentA reply or compose left the mailbox.email_mailbox.message_deliveredThe receiving server accepted it.email_mailbox.message_failedDelivery failed; the status folds back onto the message.
Pricing
Mailboxes come with your Email plan
There is no separate mailbox subscription. Every email plan includes mailboxes with generated @inbox.ai addresses; paid plans add custom handles.
Free
$0
Startup
from $15/mo
Growth
from $80/mo
Enterprise
Custom
Mailboxes (any domain)
5
from 50
from 100
Custom
Custom @inbox.ai handles
—
from 10
from 25
Custom
Generated @inbox.ai addresses
Unlimited within your mailbox count, free on every plan
Handles on your own domain
Any handle, no allowance used
Thread retention
30 days on every plan
Restore window after delete
Deleted mailboxes enter a 30-day restore window. Inbox.ai addresses stay permanently reserved to your organization; custom-domain addresses can be rebound by the same workspace after 30 days.
Allowances grow with your plan's email volume. Downgrades never break a mailbox: handles you already claimed keep working, you just can't claim new ones until you're back under the allowance.