Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Inboxes

Email addresses that keep mail in threads and reply from the same address, for an AI agent or for people.

An inbox is one email address that receives mail into threads and sends from the same address. Give one to an AI agent, which reads it through the API, webhooks or the MCP server, or to people, who read it in the dashboard. An inbox is an address on one of your receiving domains, or an address on BillionSend’s shared domain that needs no DNS.

The SDKs cover every inbox endpoint as inboxes.*, including the safety rules, quarantine, approvals and the live event stream.

Agent or people

Every inbox has a kind, chosen when it is created and never changed. The kind sets the defaults of the safety settings.

Setting Agent People
accept_from verified anyone
screening on off
extract_codes on on
send_policy reply_only open (reply_only on the shared domain)
require_approval off off
private_codes on off
send_cap 200 (50 on the shared domain) none (50 on the shared domain)
  • agent is the default when kind is left out. Mail from senders whose domain does not vouch for them waits in quarantine, mail from other outside senders is screened for prompt injection, and the agent replies inside existing threads: a new conversation it starts becomes a draft that waits for a person. See Agent safety.
  • human is for people reading in the dashboard: everyone’s mail is delivered (a failed authentication lands in the spam folder) and nothing is screened.

Mail carrying a virus is quarantined in every inbox.

Create an inbox

In the dashboard, open Inboxes and choose Create inbox. Or call the API:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Orders agent",
    "kind": "agent"
  }'

With the Node.js SDK:

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});

The answer (201) is the whole inbox: id, name, email_address, domain_id, kind, shared, expires_at, unread (threads with an unread message), drafts, quarantined, pending_approval and more.

Field Rules
email_address An address on a verified domain of your team that receives mail. Lowercased; the part before @ takes up to 64 letters, digits and . _ % + -. It cannot change later. Leave it out for an address on the shared domain.
username With email_address left out, the part before @ on the shared domain; left out, the address is random. With a domain_id of one of your own domains, it is the part before @ there.
domain_id A GET /domains row: your team’s shared subdomain (shared: true), or one of your verified domains.
name 1 to 320 characters; the address when left out.
from_name Display name of the mail the inbox sends, up to 78 characters: a plain name, without @, :, <, >, line breaks, links or phone numbers.
kind agent (default) or human.
expires_in When the inbox expires, such as 1h, 24h or 7d; left out, never.
safety Any of the safety settings.
forwarding true adds a receiving_address on the shared domain, to forward a mailbox you keep elsewhere into the inbox.
Answer When
409 validation_error Another inbox already uses the address. No other name is picked for you.
403 validation_error Your plan’s inbox limit is reached.
429 rate_limit_exceeded Too many inboxes created in the last hour, or the shared domain’s name review reached today’s limit. retry-after says when to retry.
422 validation_error The domain is not verified or does not receive mail, a username breaks a rule or is reserved, or a setting breaks a rule.
503 name_review_unavailable A shared-domain name could not be reviewed right now. Try again shortly.

The other calls:

  • GET /inboxes lists inboxes, newest first (?kind=agent or ?kind=human narrows it).
  • GET /inboxes/{id} reads one. Every {id} in an /inboxes/{id}/… path takes the inbox’s id or its email address.
  • PATCH /inboxes/{id} changes name, from_name or expires_in.
  • DELETE /inboxes/{id} deletes the inbox with its threads, drafts and labels, and revokes its API keys. A message that also reached another inbox or a catch-all address stays there.

Addresses

Your own domain

An inbox on your own domain needs the domain to receive mail: verified, with receiving on and its MX record published. Each message goes by the address the sender’s server delivered to:

  1. to the inbox with exactly that address;
  2. otherwise, for name+tag@, to the inbox of name@;
  3. otherwise, when the domain’s catch-all is on, to All received without an inbox; with catch-all off, the address is refused (550 5.1.1).

Mail sent from an inbox’s address follows the inbox’s rules on every surface: POST /emails, the batch endpoint, the SMTP relay and MCP. Give an inbox an address your app does not already send from.

Shared domain

A shared-domain inbox needs no DNS. Each team gets its own subdomain on BillionSend’s shared domain, named after the team. Leave email_address out, or send the shared row’s id as domain_id, and username names the address:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Orders agent" }'

Without username the address is random. A username is refused (422) when it is reserved (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root), starts with fwd-, or looks like a well-known brand. One that is taken answers 409.

Name review. A chosen username, a from_name and the team’s subdomain are reviewed before they are published, to stop names that pose as a brand, a bank, a government or an official role. A refused name answers 422. While the review cannot answer you get 503 name_review_unavailable; a new team’s subdomain is retried until it passes, and after 24 hours the team takes team- and six random characters. Past 20 refused names or 200 reviews in a UTC day, the answer is 429 until midnight UTC.

Shared addresses follow rules of their own, since the domain is every team’s:

  • They last until deleted, unless expires_in says otherwise, and count toward your plan’s inbox limit. One nobody used for 90 days is deleted.
  • On the Free plan, and for any address whose name looks like a well-known brand, they only reply inside their own threads, to senders whose domain vouched for them and to your team members’ sign-in addresses. On a paid plan, people start conversations from them, and an agent does when its send_policy is open and your team is past its first sends; otherwise its new conversations wait for a person as drafts. Each message to a stranger is checked for phishing before it goes out. A refusal answers 403 inbox_send_policy.
  • Each email goes to 10 recipients at most. An inbox sends to 50 recipients a day at most (send_cap from 1 to 50), and all your team’s shared addresses together reach 1,000 recipients per UTC day; past it, 429 inbox_send_cap_reached.
  • from must be the inbox’s address exactly, and the email cannot carry scheduled_at, reply_to, attachments or custom headers (422). POST /emails/batch, broadcasts and the SMTP relay always refuse a shared address.
  • forward_to takes members’ sign-in addresses only.

Mail to postmaster@ and abuse@ on the shared domain goes to BillionSend, never to an inbox.

Forward a mailbox into an inbox

forwarding: true is for an address whose mail lives elsewhere, such as a Google Workspace mailbox. The inbox gets a receiving_address, a random address on your team’s shared subdomain: forward the mailbox there, and the inbox receives the mail while replying from its own address. The domain then only needs to be verified for sending.

Expiry

expires_in is a number followed by h or d, from 1h to 365d; left out, the inbox never expires. A PATCH with a new expires_in counts from that moment, and null removes the expiry. expires_at shows when it ends.

At expires_at the inbox stops: mail to it is refused (550 5.1.1), reads answer 404 and its API keys stop working. Within the hour it is deleted, with an inbox.expired webhook followed by inbox.deleted. Changing the expiry takes the developer, admin or owner role.

Threads

Every message of an inbox belongs to a thread, and a thread holds both directions: what the inbox received and what it sent.

  • How replies find their thread. Mail the inbox sends carries a thread token in its References header. A reply lands in the same thread when it carries that token, when its In-Reply-To names a message the inbox sent, or when it refers to an earlier message of the thread. Subjects never join threads.
  • Folders. A thread sits in one folder: inbox, archive, spam, sent or trash. New mail moves an archived or sent thread back to inbox. DELETE moves a thread to trash, which is emptied after 30 days.
  • Read state. A PATCH with read marks the whole thread. Held mail never makes a thread unread. In a people inbox, opening a thread marks it read; in an agent inbox, read state belongs to your agent.
  • Labels. Up to 100 per inbox, names of 1 to 64 characters, colors as #RRGGBB.
Call Does
GET /inboxes/{id}/threads Threads, latest activity first. Filters: folders, labels, read, include_quarantined.
GET /inboxes/{id}/threads/search The same filters plus query ("exact phrase" and -excluded work), from, to, cc, bcc, has_attachment, start_date, end_date.
GET /inboxes/{id}/threads/{thread_id} One thread.
PATCH /inboxes/{id}/threads/{thread_id} Set read or folder.
POST / PUT / DELETE …/threads/{thread_id}/labels Add, replace or remove labels.
DELETE /inboxes/{id}/threads/{thread_id} Moves the thread to trash.
GET /inboxes/{id}/threads/{thread_id}/emails Its emails, oldest first.

Search matches whole words, in any letter case, in the subject, the sender (address and display name), the recipients, the text of a received email (the earlier messages it quotes included), its attachment names and the text of its PDF, Word and Excel attachments (once that text has been read). Chinese, Japanese and Korean text is split into words. Every word of query must match somewhere in the same email; from, to, cc and bcc take words of an address or a name. Sent emails are searched by subject, sender and recipients.

matched_email_id is the thread’s best match, and highlights marks the words in its subject, sender and recipients (it is {} when only the text or an attachment name matched). A new email is searchable a second or two after it arrives. If search is briefly unavailable, the call answers 503 with search_unavailable and a Retry-After header; every other call works as usual.

A thread email has direction, from, to, cc, bcc, reply_to, subject, message_id, html, text, attachments, read and received_at. Received mail adds extracted_text (the reply, cleaned of hidden text), screening, spam_verdict and virus_verdict.

Send from an inbox

POST /inboxes/{id}/emails (inboxes.send() in the SDKs) starts a new conversation from the inbox address in one call.

curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "ada@example.org",
    "subject": "Your order 1042",
    "text": "It ships today. The invoice is attached.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'

It takes to, subject, html and/or text, and optionally cc, bcc, attachments and requires_approval. The inbox’s rules decide as they do for a reply, and the answers are a reply’s: 200 with { "id", "thread_id" }, or 202 with the draft when the rules hold the send (an inbox that may not start conversations, a first-time recipient past the ramp, requires_approval: true). An inbox-scoped key can call it for its own inbox.

Attachments are the ones POST /emails takes: filename and base64 content, optionally content_type and content_id for an inline image. A remote path answers 422. Replies, forwards, new sends and drafts all take them, up to 10 MiB decoded in all (a forward counts the original’s files too); programs and disguised file types answer 422, and an inbox on the shared domain takes none.

Reply and forward

curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, your order ships today." }'

A reply goes to the message’s Reply-To, or else its sender. reply_all adds the other to and cc addresses as cc; bcc is never copied. One send takes 50 recipients at most. …/forward needs to, takes a note, and quotes the original with its attachments, plus any attachments you add (up to 10 MiB in all). Both take attachments and requires_approval: true to have a person approve the send. A reply from an agent inbox carries Auto-Submitted: auto-replied.

Answer Means
200 Sent: { "id", "thread_id" }.
202 Held for a person: the draft, with status: "pending_approval" and its approval_reasons.
403 inbox_send_policy The inbox’s rules refuse the send outright.
403 email_quarantined The email is held in quarantine, or carries a virus.
403 restricted_api_key An inbox-scoped key reaching another inbox.
429 inbox_send_cap_reached The inbox’s daily cap is used; retry-after counts to midnight UTC.

To reply to any received email, in an inbox or not, use POST /emails/receiving/{id}/reply.

Drafts and approval

A draft is standalone for a new conversation, or a reply with thread_id and reply_to_email_id. Its status:

status Means
draft Being written; nothing sends it until …/send, or until its send_at.
pending_approval A send was held and waits for a person. approval_reasons says why. It expires after 7 days.
sent Sent; email_id names the email.
rejected A person turned it down.
expired Nobody approved it within 7 days.
Call Does
POST /inboxes/{id}/drafts Creates a draft: to, cc, bcc, subject, text, html, attachments, plus thread_id and reply_to_email_id for a reply. A reply draft does not copy recipients, so set to before sending.
GET /inboxes/{id}/drafts Unsent drafts, most recently updated first.
GET / PATCH / DELETE /inboxes/{id}/drafts/{draft_id} Read, change (setting text or html replaces the whole body, and attachments replaces the whole list) or delete a draft; 409 once sent.
POST /inboxes/{id}/drafts/{draft_id}/send Sends it. 200 with the sent email’s id and thread_id, 202 when held, 422 without a recipient.
POST /inboxes/{id}/drafts/{draft_id}/reject Turns a draft down (approvers only).

A draft keeps its attachments encrypted, apart from its body, and reads them back by position as id, filename, content_type and size, never the content. They go out with the email when the draft is sent, and a held send keeps the files it carried with its draft. Once a draft is sent, rejected, expired or deleted its files are gone, and the 30-day content purge removes any that are left.

Scheduled sends. send_at on POST or PATCH (a BillionSend extension) sends the draft later, as whoever set it (an edit of a scheduled draft’s content makes the editor the one it sends as): an ISO 8601 time with offset, or a relative one like "in 2 hours", at most 30 days ahead; a time already past sends it within a minute, and null cancels. The draft needs a recipient by then, and only a draft can be scheduled: one waiting for approval answers 409. When send_at comes, the send runs every rule and limit as a send made then would. Sent, the draft turns sent; held by the inbox’s rules, pending_approval; refused (the key that scheduled it was revoked, the inbox is gone, a limit was reached), it stays a draft with send_at back to null, the refusal’s name in send_error and an inbox.draft.send_failed webhook that carries error: { name, message }. Scheduling it again clears send_error. With send_at, creating a second reply draft for the same email answers 409 instead of the existing draft.

Who approves. A person in the dashboard, or a full-access API key of the team that is not restricted to an inbox, approves by sending: the send skips the rules that hold agent mail. An agent cannot approve: an inbox-scoped key or an MCP client sending a pending draft gets 403 approval_required. In the dashboard, any member approves, edits or discards drafts under the inbox’s Needs review tab, and owners get one email a day while something waits.

Reasons a send is held:

Reason Held because
approval_required The request asked for a person (requires_approval: true).
require_approval The inbox has every send approved.
send_policy A recipient is not allowed by the inbox’s send policy.
ramp Too many new recipients today for a young inbox.
private_code It contains a code or sign-in link the inbox received.
loop_guard:<reason> It replies to an automatic message (out-of-office, mailing list, bounce).
loop_burst Too many automatic replies to one address within an hour.
reply_to_redirect The message’s Reply-To points to another organization.

Safety settings

GET /inboxes/{id}/safety reads an inbox’s rules, and PATCH changes any of them:

curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
Setting Does
accept_from Whose mail reaches the inbox: anyone; verified, senders whose domain vouches for the From address (plus owners, the allowlist and known threads); or allowlist, owners, the allowlist and known threads only. The rest is quarantined.
allowlist Up to 500 entries: name@domain, or *@domain for a domain and its subdomains.
owner_addresses Up to 50 more addresses treated as the inbox’s owners, besides your team members’ sign-in addresses. Ignored on the shared domain.
screening Score mail from outside senders for prompt injection and phishing (agent inboxes).
extract_codes Pull verification codes and sign-in links out of mail.
send_policy reply_only; allowlist, which adds new conversations with owners and the allowlist (not on the shared domain); or open, anyone, once the team is past its first sends.
require_approval Every send from the inbox waits for a person.
private_codes A code or sign-in link the inbox received cannot be sent to anyone but owners and the allowlist.
send_cap Recipients the inbox may send to per UTC day without a person: 1 to 100,000, or null for no cap (1 to 50 on the shared domain).
forward_to Up to 5 addresses that get a copy of every delivered message except spam: team members’ sign-in addresses or owner addresses. A copy that cannot go out right away is retried until it is sent, refused for good, or two days have passed; it is never sent twice.

A setting that breaks a rule answers 422 with the reason. An inbox-scoped key cannot change these settings (403 restricted_api_key), and neither can an agent key. An MCP client can read them but not change them. Only an owner, admin or developer changes them, in the dashboard or with a full-access API key. Agent safety explains what each one does.

Quarantine

Mail an inbox’s rules do not let in is quarantined: kept, listed and releasable, never dropped and never returned to its sender. It fires no email.received or inbox.email.received until it is released, and agents never see it.

GET /inboxes/{id}/quarantine lists the held messages with id, from, subject, quarantine_reason, sender_trust, injection_score, phishing_score and virus_signature, without content. POST /inboxes/{id}/quarantine/{email_id}/release delivers one, and { "trust_sender": true } also adds its sender to the allowlist. Both need a full-access key that is not restricted to an inbox. People release from the inbox’s Needs review tab, and MCP clients with receiving:manage use release_email. Who may release which hold is in Agent safety.

Verification codes

GET /inboxes/{id}/codes/latest answers the newest verification code or sign-in link the inbox received, so an agent never reads HTML:

curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
  • kind is otp (code in code) or link (address in url, with link_domain_matches_sender).
  • from narrows it to a sender; wait (0 to 50 seconds) waits for one to arrive; max_age (60 to 86,400 seconds, 600 by default) skips older codes; since skips mail received at or before that time, so pass the received_at of a code you already used to wait for the next one.
  • status is found, none, ambiguous (two codes equally likely, so none is answered) or timeout. The answer is always 200.
  • Codes never come from quarantined mail, from senders that failed authentication, or from an inbox with extract_codes off. Every read is recorded in the inbox’s activity.

Event stream

GET /inboxes/events is a server-sent event stream of everything that happens in your inboxes, the moment it is committed. Events carry the webhook event names (inbox.email.received, inbox.thread.created, inbox.draft.created, email.received and the other inbox.* events) and the webhook payload’s data. GET /inboxes/{id}/events streams one inbox and ends when that inbox is deleted or expires.

curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
  • Send the key as a Bearer header, as for every request. Browsers’ EventSource cannot set it: use fetch and read the body, or any SSE client that takes headers.
  • types narrows the stream to some events, comma separated; /inboxes/{id}/events still sends inbox.deleted and inbox.expired, the events that end it. Every event is metadata only, like a webhook: no body, code or link. Read the message with the receiving endpoints.
  • Resuming. Every event has an id. A client that reconnects with Last-Event-ID (or ?last_event_id=) gets what it missed, in order, before the live events. Events are kept for 24 hours; a reconnect from an older id first gets a stream.gap event, which means events may be missing and the lists should be read again.
  • A stream starts with no replay when it has no Last-Event-ID. It is closed by the server every 10 minutes or so, and when the API restarts: reconnect with the last id you saw. retry: 1000 asks a client to wait a second. A comment line every 15 seconds keeps proxies from closing an idle stream.
  • A team-wide key opens /inboxes/events. A key restricted to one domain, or to one inbox, opens /inboxes/{id}/events for an inbox it can reach. A sending-only key cannot open a stream.
  • An agent (a key restricted to one inbox, or an MCP connection) never receives inbox.email.quarantined, live or replayed, as it never reads held mail; naming it in types is a 403 restricted_api_key.
  • A stream closes within a few seconds once its key is revoked, the person who created the key leaves the team, or its inbox is deleted or expires.
  • Each key may hold 5 streams at once on each API process and each team 25; one more answers 429 too_many_streams with retry-after. One stream for the whole team is enough for most agents.

wait on /emails/receiving and codes/latest is woken by the same events, so waiting costs nothing while no mail arrives.

Inbox-scoped API keys

Give each agent a key that reaches only its own inbox. See API keys.

curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders agent",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
  • It needs permission: "full_access" and cannot take a domain_id too. An inbox holds 5 active keys at most, outside the team’s limit of 25.
  • The key reads its inbox (threads, emails, drafts, labels, codes, the event stream, and /emails/receiving limited to that inbox), replies, forwards, writes drafts and sends them, sends new email from its inbox, and sends from the inbox’s address only (403 restricted_api_key for another from; 550 5.7.1 over SMTP).
  • Everything else answers 403 restricted_api_key: it cannot change safety settings, list or release quarantine, approve drafts, create keys or reach another inbox.
  • It stops working when its inbox expires, and deleting the inbox revokes it.

In the dashboard, owners, admins and developers pick the inbox under Restrict to an inbox when creating a key.

Webhooks

Inbox events (inbox.created, inbox.thread.created, inbox.email.received, inbox.email.sent, inbox.email.quarantined, inbox.expired, the inbox.draft.* events and more) go only to endpoints that name them, never to an endpoint subscribed to all events. An endpoint can be limited to some inboxes with inbox_ids. email.received still fires for inbox mail once it is delivered. Payloads: Webhooks.

Activity

Everything done in an inbox is recorded: sends and the rules’ decisions, refusals, drafts, approvals, releases, code reads, safety changes, deletions and keys. The inbox’s Activity tab lists it with who acted: a person, an API key or a connected app. Decisions keep reason codes only, never content, codes or addresses.

Limits

Limit Value
Inboxes 3 on Free, 25 on Starter, unlimited on Pro and Scale.
Inboxes created per hour 10 on Free, 60 on Starter, 600 on Pro and Scale.
Mail per inbox 200 accepted messages per rolling hour for an agent inbox, 2,000 for a people inbox. Past that, senders get 452 4.2.2 and try again later.
Sends send_cap recipients per UTC day. A new inbox reaches new recipients gradually: 10 on its first day of sending, then 20, 40, 80, 160 and so on, up to the cap.
Recipients per send 50 (to, cc and bcc together); 10 from a shared address.
Attachments per send 10 MiB decoded in all; none from a shared address.
Shared domain 1,000 recipients per UTC day for all your team’s shared addresses; a shared inbox unused for 90 days is deleted.
Labels 100 per inbox.
Safety lists 500 allowlist entries, 50 owner addresses, 5 forward_to addresses.
Inbox-scoped keys 5 active per inbox.
Screening 200 messages per inbox per day; past it, mail that needs screening is quarantined.
Waiting 50 seconds per request; 20 waits at once per team on each API process.
Event streams 5 per API key and 25 per team at once on each API process; events replay for 24 hours.
Drafts and trash A pending draft expires after 7 days; a trashed thread is deleted after 30.
Retention Inbox mail follows received mail’s retention: 30 days.

Inboxes themselves cost nothing: received mail counts once per message against your receiving limit, never against your sending volume, as in Receiving.

Dashboard

Inboxes in the sidebar lists your inboxes under the All, Agent and People tabs, with what needs attention: drafts to approve, unread threads and messages in quarantine. A pinned All received row opens every email your domains received. An inbox’s page has four tabs: Threads (read, reply and approve drafts in place), Needs review (drafts and quarantine), Safety & rules and Activity.

Any member can work an inbox’s threads, approve drafts and release quarantine. Owners, admins and developers can also create, change and delete inboxes, change safety rules, create inbox-scoped keys, delete received mail and switch catch-all. See team roles.

MCP

MCP clients work with inboxes under three permissions: receiving:read (read mail, wait for it, read codes, list inboxes, threads, labels and drafts, search threads, read safety rules), receiving:reply (reply, forward, send from an inbox, write, send and delete drafts, organize threads and labels) and receiving:manage (create, change and delete inboxes, list and release quarantine). An MCP client always sees mail the way an agent does: without held mail and with message text fenced as untrusted. It never approves drafts, and create_inbox takes accept_from and no other safety setting; it never changes an inbox’s safety rules.

API notes

  • Creating an inbox or a draft answers the whole object.
  • email_address is optional: left out, the inbox gets a random permanent address on the shared domain.
  • kind defaults to agent, so an inbox created without it gets an agent’s protections.
  • There is no hosted agent: GET /inboxes/{id}/agent answers empty instructions, tone and actions, and PATCH /inboxes/{id}/agent answers 422.
  • Not supported yet: custom headers on replies, forwards and draft sends, and path (remote URL) attachments. Each answers 422 unless its value is empty.
  • A reply, forward or draft send held by the inbox’s rules answers 202 with the draft instead of 200 with the email: check that object reads inbox_draft before treating the result as sent.
  • Inbox errors: 403 inbox_send_policy, 429 inbox_send_cap_reached, 403 approval_required, 403 email_quarantined and 503 name_review_unavailable (see Errors).
  • inbox.* webhook events are opt-in; inbox.thread.assigned and inbox.thread.unassigned are not sent.

Was this page helpful?