Create an inbox
An address that receives into threads, on one of your verified domains (receiving on, or forwarding: true) or, with email_address omitted, an address on the shared inbox domain that needs no DNS: username names it, or it is random. domain_id takes a row of GET /domains instead of email_address: the team’s shared subdomain, or one of your domains with username. It never expires unless expires_in says so. Returns the full inbox. BillionSend extensions: username, domain_id, kind (agent by default), expires_in and safety.
/inboxesAuthorizationBearer 令牌 · header必填A BillionSend API key (bs_…).
application/jsonemail_addressstringAn address on one of your verified domains; it needs receiving on unless forwarding is true. BillionSend extension: omitted, the inbox gets an address on the shared inbox domain (no DNS), named by username or random, unless domain_id names one of your domains.
domain_idstring<uuid>BillionSend extension: the id of a GET /domains row, instead of email_address. The team's subdomain of the shared domain (the row with shared: true) is the same as leaving email_address out; one of your verified domains needs username, the part before the @.
usernamestringBillionSend extension: with email_address omitted, the part before the @ of the shared-domain address, trimmed and lowercased: 1-64 letters, digits, dots, hyphens and underscores, starting and ending with a letter or digit, never cut short. Reserved names (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root, compared without dots, hyphens and underscores), the fwd- prefix and brand look-alikes answer 422, and one already in use 409. A chosen name is reviewed first: 503 with retry-after while that review is unavailable. Omitted: a random one. With a domain_id of one of your domains, it is the part before the @ there, required, under email_address's rule.
namestringInternal name, 1-320 characters, so any address fits. Defaults to email_address.
from_namestringThe name recipients see, a plain name (not "Name <email>"); "" leaves it unset. On the shared domain it may not imitate a brand, and it is reviewed like username.
forwardingbooleanReceive without an MX record: mail forwarded to the inbox's receiving_address lands in it
kindstringBillionSend extension: agent (default; threads, screening, drafts that wait for approval) or human (a team mailbox)
agenthumanexpires_instring | nullBillionSend extension: a lifetime counted from now, "1h" to "365d"; omitted or null, the inbox never expires. A shared-domain inbox left unused for 90 days (no mail in or out, no API calls on it) is deleted either way.
safetyInboxSafetyPatchBillionSend extension: safety rules over the kind's defaults
显示属性隐藏属性
accept_fromstringWho may write in: anyone; verified (DMARC-aligned senders, known threads, the allowlist); allowlist only. Mail that fails is quarantined.
anyoneverifiedallowlistallowliststring[]"local@domain" (exact) or "*@domain" (the domain and its subdomains). On the shared domain it only lets mail in
owner_addressesstring[]Owners besides the team members' login addresses; ignored on the shared domain
screeningbooleanScore external mail for prompt injection (agent inboxes only)
extract_codesbooleanExpose extracted codes and sign-in links
send_policystringWhat the inbox may send without a person's approval. On the shared domain "allowlist" answers 422, and so does "open" unless the team is on a paid plan and past its first sends
reply_onlyallowlistopenrequire_approvalbooleanEvery send waits for a person
private_codesbooleanReceived codes and sign-in links can't be sent on to anyone but owners
send_capinteger | nullUnattended recipients per UTC day; null: no cap. 1-50 on the shared domain
forward_tostring[]Forward every delivered message to these team member or owner addresses; team members only on the shared domain
Inbox created
objectstring必填inboxidstring<uuid>必填namestring必填email_addressstring必填domain_idstring<uuid>必填A shared address's is its team's shared subdomain: the GET /domains row with shared: true
receiving_addressstring | null必填from_namestring | null必填unreadinteger必填Threads with an unread message
draftsinteger必填Unsent drafts
last_receivedstring | null必填created_atstring必填updated_atstring必填kindstring必填agenthumansharedboolean必填On the shared inbox domain
expires_atstring | null必填quarantinedinteger必填Held messages not yet released
pending_approvalinteger必填Drafts waiting for a person
Missing, malformed, unknown or revoked API key
statusCodenumber必填namestring必填messagestring必填The plan's inbox limit, or a restricted API key
statusCodenumber必填namestring必填messagestring必填The address is already used by an inbox
statusCodenumber必填namestring必填messagestring必填Validation error
statusCodenumber必填namestring必填messagestring必填Too many inboxes created in the last hour, or too many names reviewed or refused on the shared domain today, or the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumber必填namestring必填messagestring必填A chosen username or from_name on the shared domain can't be reviewed right now, or the team's subdomain on the shared domain is still waiting for its name review; retry-after says when to try again
statusCodenumber必填namestring必填messagestring必填