Create a domain
/domainsAuthorizationBearer 令牌 · header必填A BillionSend API key (bs_…).
application/jsonnamestring必填regionstringSES region of the identity, one of the regions this deployment serves (the values listed here; the first is the default). Any other region is rejected with 422. A domain has one region, fixed when it is added.
us-east-1eu-west-1sa-east-1ap-northeast-1custom_return_pathstringopen_trackingbooleanInject a tracking pixel served from the tracking host and record email.opened events. Off by default.
click_trackingbooleanRewrite links to redirect through the tracking host and record email.clicked events. Off by default.
tracking_subdomainstringDNS label of the domain's own tracking host, e.g. "links" for links.<domain>. Optional: without one, tracked links use the shared tracking host. Setting it adds a Tracking CNAME to records[] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Tracking record then reads verified, and links go through it from then on. A subdomain that does not activate within 72 hours reads failed; send the same tracking_subdomain again to retry.
unsubscribe_subdomainstringBillionSend extension: DNS label of the domain's own unsubscribe host, e.g. "unsubscribe" for unsubscribe.<domain>. Optional: without one, unsubscribe links (and the List-Unsubscribe header) use the shared unsubscribe host. Setting it adds an Unsubscribe CNAME to records[] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Unsubscribe record then reads verified, and unsubscribe links go through it from then on. The same label as tracking_subdomain is allowed: one host then serves both and records[] shows one row. A subdomain that does not activate within 72 hours reads failed; send the same unsubscribe_subdomain again to retry. Kept apart from tracking_subdomain because ad blockers filter tracking hosts by name.
capabilitiesobjectWhat the domain is used for (sending, receiving); omitted fields keep their value.
显示属性隐藏属性
sendingstringOnly enabled is accepted: a domain of your own can't be receive-only, so disabled is a 422.
enableddisabledreceivingstringInbound mail for every address at the domain (a catch-all), readable at /emails/receiving and announced by the email.received webhook. Enabling needs a verified domain, and adds a Receiving MX record to records[]. A domain that already has mailboxes is best received on a subdomain (inbound.example.com): the Receiving MX would take their mail.
enableddisabledDomain created
idstring<uuid>必填namestring必填statusstring必填created_atstring必填regionstring必填open_trackingboolean必填click_trackingboolean必填tracking_subdomainstring | null必填tracking_statusstring | null必填BillionSend extension: where the tracking subdomain stands: pending (waiting for its CNAME and certificate), active (links go through it) or failed (did not activate within 72 hours; links use the shared host). null while no tracking_subdomain is set.
pendingactivefailednulltracking_errorstring | null必填BillionSend extension: why the tracking subdomain is not active, when known
unsubscribe_subdomainstring | null必填BillionSend extension: the domain's own unsubscribe host label, null when unset
unsubscribe_statusstring | null必填BillionSend extension: where the unsubscribe subdomain stands: pending, active (unsubscribe links go through it) or failed (links use the shared host). null while no unsubscribe_subdomain is set. When both subdomains are the same label they share one host and always read the same.
pendingactivefailednullunsubscribe_errorstring | null必填BillionSend extension: why the unsubscribe subdomain is not active, when known
unsubscribe_pageobject必填BillionSend extension: this domain's own look for its unsubscribe pages. A null field falls back to the team's default page, then to the built-in default.
显示属性隐藏属性
brand_namestring | null必填messagestring | null必填success_messagestring | null必填redirect_urlstring | null必填background_colorstring | null必填text_colorstring | null必填accent_colorstring | null必填logo_radiusstring | null必填squaregentleroundedcirclenulllogo_urlstring | null必填Read-only; uploaded in the dashboard
capabilitiesobject必填显示属性隐藏属性
sendingstring必填enabled; on the shared row, disabled while sending from the shared domain is paused
receivingstring必填enabled while the domain receives mail
receiving_catch_allboolean必填BillionSend extension: whether mail to an address without an inbox is stored (true) or refused at RCPT (false)
sharedboolean必填BillionSend extension: true on the team's subdomain of the shared inbox domain, a read-only row listed after the team's own domains (403 on changes) that POST /inboxes domain_id takes; false on the team's own domains
sending_modestringBillionSend extension, on the shared row only: what its inboxes' addresses may send. open starts conversations, reply_only replies inside their threads, receive_only sends nothing. Holds on names still apply per send: an address whose username or from_name imitates a brand, or one on an older label that does, replies only, even when the mode is open.
openreply_onlyreceive_onlysending_mode_reasonstring | nullBillionSend extension, on the shared row only: what holds sending below open: plan when the team's plan holds it, the other value when the platform's sending switches do; null when open
planinstancenullrecordsobject[]必填显示属性隐藏属性
object 数组recordstring必填Which record this is: DKIM, SPF (the MAIL FROM MX and TXT rows), DMARC, Tracking (the tracking subdomain's CNAME, present once a tracking subdomain is set), Unsubscribe (the unsubscribe subdomain's CNAME, present once an unsubscribe subdomain is set to a label other than the tracking one) or Receiving (the MX inbound mail needs, present while receiving is enabled; it reads verified only when it is among the domain's lowest-numbered MX records). Only the DKIM and SPF rows gate sending.
namestring必填typestring必填ttlstring必填statusstring必填not_started | pending | verified | failed. DKIM and SPF rows combine public DNS with the provider's verification: found in DNS but not yet confirmed reads pending, a different published value reads failed, no record reads not_started. DMARC reads verified when a policy covers the domain — its own or a parent domain's (see inherited_from) — and not_started when none does. Tracking and Unsubscribe read verified once their CNAME resolves and its certificate is issued, pending until then, and failed when it did not activate within 72 hours.
valuestring必填prioritynumberlivestringWhat public DNS answers for this record right now: found, missing, mismatch (a different value is published) or unknown (the lookup did not conclude). Omitted when no live check ran (the create response).
foundmissingmismatchunknowndetailstringOne sentence explaining a row that is not verified: found but awaiting the provider, the value that is published instead, no record at the name, or which parent DMARC policy covers the domain. Omitted when there is nothing to add.
inherited_fromstringDMARC only: the _dmarc name whose policy covers this domain when it has no record of its own (RFC 7489 organizational-domain fallback).
policystringDMARC only, alongside inherited_from: the inherited policy's p= value.
nonequarantinerejectMissing, malformed, unknown or revoked API key
statusCodenumber必填namestring必填messagestring必填Plan domain limit reached, an own tracking or unsubscribe subdomain needs a paid plan, or the key is held to one domain (it cannot create domains)
statusCodenumber必填namestring必填messagestring必填Domain already added
statusCodenumber必填namestring必填messagestring必填Validation error
statusCodenumber必填namestring必填messagestring必填Too many domains created recently, or the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumber必填namestring必填messagestring必填