01
Plans#
Custom domains are included on Builder (3), Team (50), and Enterprise. On Free, POST /v0/domains returns 403 with code plan_required and an upgrade_url. Past your plan's limit it returns 429 domain_limit_reached.
02
1. Add the domain#
Add the domain under Dashboard → Domains, or with the API (account key), and pick what it does. Send only (the default) adds DKIM, a return-path subdomain and DMARC, and no MX record, so the email you already use on the domain (Google Workspace, Microsoft 365) keeps working; send from example.com safely. Send and receive on a subdomain adds the domain as send-only plus a receiving subdomain such as in.example.com in one step; only the subdomain gets an MX record, and it counts as one domain on your plan. Full MX receives all of the domain's mail at BotInbox and replaces the MX records it has today, so the dashboard asks you to type the domain name to confirm; use it only for a domain nobody uses for email. Before anything is created, the dashboard checks the name for the mode you picked: MX records that already receive mail (a full MX setup would replace them; send-only leaves them alone), an existing SPF record (we give you one merged value to use instead of a second record), and a CNAME at the name (which can't coexist with MX or TXT records). You then land on the domain's setup page, where a send-only domain can add a receiving subdomain later. The API response lists every DNS record to publish in records; each record has a type, name, value, optional priority, and a purpose.
curl https://botinbox.dev/v0/domains -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" \
-H "Content-Type: application/json" -d '{"name":"agents.example.com"}'03
2. Publish the DNS records#
Copy each record exactly as returned into your DNS provider. ownership: a TXT record botinbox-verify=<token> that proves you control the domain. inbound (receiving domains only): an MX record (priority 10) that routes the domain's mail to BotInbox. spf (receiving domains only): a TXT record authorizing BotInbox to send for the domain; send-only domains are authorized on the bounce subdomain instead, so your existing SPF record is untouched. dkim: three CNAME records under _domainkey that sign outgoing mail. mail_from_mx and mail_from_spf: an MX and a TXT record on bounce.<domain> that handle bounces. dmarc: a TXT record on _dmarc.<domain>, starting at p=none (tighten to quarantine or reject once mail flows). If your DNS provider can proxy records (for example Cloudflare), set every record to DNS only. On the setup page each row has copy buttons for the name and the value. Names are shown relative to your zone (agents, bounce.agents), the way most providers' host field expects; switch to Full name if yours wants the whole name. We detect your DNS provider from its nameservers and show short provider-specific steps and gotchas. Download the records as a BIND zone snippet or CSV, or use Send setup to IT to email them to whoever manages your DNS, with a read-only live status link that expires after 7 days.
{
"records": [
{ "type": "TXT", "name": "agents.example.com", "value": "botinbox-verify=...", "purpose": "ownership" },
{ "type": "MX", "name": "agents.example.com", "value": "inbound-smtp.us-east-1.amazonaws.com", "priority": 10, "purpose": "inbound" },
{ "type": "TXT", "name": "agents.example.com", "value": "v=spf1 include:amazonses.com ~all", "purpose": "spf" },
{ "type": "CNAME", "name": "abc._domainkey.agents.example.com", "value": "abc.dkim.amazonses.com", "purpose": "dkim" },
{ "type": "MX", "name": "bounce.agents.example.com", "value": "feedback-smtp.us-east-1.amazonses.com", "priority": 10, "purpose": "mail_from_mx" },
{ "type": "TXT", "name": "bounce.agents.example.com", "value": "v=spf1 include:amazonses.com ~all", "purpose": "mail_from_spf" },
{ "type": "TXT", "name": "_dmarc.agents.example.com", "value": "v=DMARC1; p=none; adkim=r; aspf=r", "purpose": "dmarc" }
]
}Note
04
Or add the records automatically#
The setup page can add the records for you, so you don't copy them one by one. One-click setup: when your DNS provider supports Domain Connect, the setup page shows Add records at <your provider>. You sign in there, review the changes, and approve; the provider adds every record in one step, merges our SPF entry into an existing SPF record instead of adding a second one, and sends you back to the setup page, which re-checks DNS right away. The button only appears when your provider supports it for your domain and the records for its mode (send only, or send and receive), and not when the name already has MX records or a CNAME that the change would replace. Connect Cloudflare: if your DNS is hosted at Cloudflare, you can instead paste a Cloudflare API token. The setup page links to Cloudflare's token page with the DNS Edit permission filled in; limit the token to the zone that holds your domain (Zone → DNS → Edit). We add only the records that are missing, always as DNS only (grey cloud), and never change or delete existing records: if something already on the name disagrees with what we need, such as another SPF record or MX records pointing elsewhere, it is listed as a conflict with what to change, and you decide. Each record shows Created, Already there, Conflict, or Not added. Running it again is safe: records that are already there are skipped. The token is used for that one request and is never stored; you can delete it in Cloudflare afterwards.
05
3. Verify#
Verification is automatic. While the setup page is open, each record's status updates live: Pending (not in DNS yet), Found (published with the right value), Verified (confirmed), or Wrong value (with what we found and what we expected). The domain moves from Pending to Partially verified (it can already send, or receive) to Verified. Sending needs the ownership, DKIM, and SPF records; receiving needs the MX record. A send-only domain has no MX record to check and is Verified once it can send. In the background we keep checking pending domains for 72 hours, email you when the domain is verified, and email troubleshooting tips if it is still pending after 24 hours. After 72 hours it shows Needs attention with the reason, for example the MX record pointing somewhere else. With the API, trigger a check yourself: the response includes a checks object (ownership_txt, sending_verified, dkim_status, mail_from_status, inbound_mx). 200 means VERIFIED; 409 means still PENDING (or FAILED). DNS changes can take from a few minutes to a few hours to propagate.
curl https://botinbox.dev/v0/domains/DOMAIN_ID/verify -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY"06
4. Test and create inboxes on the domain#
On the setup page, send yourself a test email from test@<your domain> once sending is ready, and reply to it to confirm receiving. Then create the first inbox (for example support@<your domain>) from the prefilled form, or pass the verified domain when creating an inbox with the API. Inboxes need a domain that receives mail: on a send-only domain, add a receiving subdomain (in.<your domain>) and create inboxes there. Mail to that address arrives in the inbox, and sends are signed for your domain.
curl https://botinbox.dev/v0/inboxes -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" \
-H "Content-Type: application/json" -d '{"username":"support","domain":"agents.example.com"}'07
Ongoing health#
We re-check verified domains daily. If a record disappears, we email you and the setup page shows which one. If the DKIM record is removed, sending from that domain is paused, because mail would fail authentication: sends return 403 with code domain_paused until the record is back, and sending resumes on its own. The setup page also shows a health card for SPF, DKIM, DMARC, and MX. New sending domains warm up: they can send 1,000 emails per 24 hours for the first three days after verification, then the limit doubles daily until it reaches your plan's daily limit; the setup page shows a warming-up banner, and sends over the limit return 429 with code domain_warming_up and the current limit. If a domain's bounce rate reaches 4% or its complaint rate reaches 0.08% over 30 days, we pause sending from that domain only (403 domain_paused) and email your Owners and Admins; your other domains keep sending. For DMARC, start with p=none; after two weeks of clean reports, change it to p=quarantine so spoofed mail goes to spam.