Domains
Verify a sending domain, add its DNS records, and set it up for tracking, receiving and warm-up.
Every email must be sent from a domain your team has verified. Any other from address is refused with 422. Add and verify domains in the dashboard under Domains, or with the API.
Add and verify a domain
curl -X POST https://api.billionsend.com/domains \
-H "Authorization: Bearer $BILLIONSEND_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "mail.example.com" }'
The response lists the DNS records to add at your DNS provider. A subdomain such as mail.example.com is a good choice for a sending domain. Once the records are live, press Verify on the domain page or call POST /domains/{id}/verify.
| Record | Purpose |
|---|---|
DKIM (two CNAMEs, bs1._domainkey and bs2._domainkey) |
Signs your mail so providers know it is yours. |
| MAIL FROM (MX and TXT) | A bounce address on your own domain, so SPF aligns. |
| DMARC (TXT, recommended) | Tells providers what to do with mail that fails the checks. It does not block sending. |
DKIM and MAIL FROM must be verified before you can send. On Cloudflare, keep these records DNS only (grey cloud).
The domain page shows each record as found, missing or mismatched, checked live against public DNS. GET /domains/{id} returns the same in records[]. Each record has a status (not_started, pending, verified or failed), a live value for what public DNS answers right now, and a short detail when something is wrong.
DKIM keys rotate by themselves
BillionSend creates a DKIM key for each domain and replaces it every 180 days, switching between the two CNAMEs. You add the records once and never touch them again. You can turn automatic rotation off in the domain’s Settings tab.
Region
POST /domains takes an optional region. A domain lives in one region. To move it, delete it and add it again in the other region; its DNS records change.
Plan limits
| Free | Starter | Pro and Scale | |
|---|---|---|---|
| Sending domains per team | 3 | 10 | Unlimited |
Past the limit, POST /domains answers 403 plan_limit_reached. A domain name that another team already holds answers 409.
New domain warm-up
A newly registered domain sends at a limited daily volume while it builds a reputation. The cap depends on the age of the registered domain (example.com for mail.example.com) and counts per UTC day:
| Domain age | Emails per day |
|---|---|
| Under 1 day | 100 |
| 1 to 7 days | 300 |
| 7 to 30 days | 2,000 |
| 30 days or older | Your plan’s limit only |
- A domain that sends cleanly, with few bounces and no complaints, moves up a step sooner.
- The cap applies on top of your plan. Upgrading does not lift it.
- Your new domains share one daily volume: adding another new domain does not add volume.
- Mail over the cap is not lost. It shows as Waiting and goes out the next day, oldest first. If a lot of mail is already waiting, a send answers
429 daily_quota_exceeded; retry after the UTC day rolls over.
The domain page shows “Warming up: N/day today” while a cap applies. See Sending limits for all the protections on sending.
Settings
Once a domain is verified, these settings are available:
- Open and click tracking. Both are off by default. Turn them on in the domain’s Links tab, or with
open_trackingandclick_trackingonPATCH /domains/{id}. See Tracking. - Own tracking and unsubscribe subdomains. Serve tracked links and unsubscribe links from your own domain. A paid plan is required. See Tracking.
- Unsubscribe page. The look of the page your recipients see: name, logo, colors and texts. Set it in the domain’s Brand tab, or with
unsubscribe_pageonPATCH /domains/{id}. See Unsubscribes. - TLS required. Deliver only to servers that support TLS. Set it in the Settings tab.
- Default from name, from address and reply-to. Set them in the Settings tab.
Receiving
A verified domain can also receive mail. Turn it on with Enable receiving on the domain page, or with PATCH /domains/{id}:
{ "capabilities": { "receiving": "enabled" } }
- Only a verified domain can turn receiving on.
POST /domainswith"receiving": "enabled"answers422: add the domain, verify it, then turn receiving on. - Turning it on adds two
Receivingrecords: MX records that point atmx1.billionsend-dns.comandmx2.billionsend-dns.com, both with priority10. Publish both, so a sender that finds one down retries on the other. They do not affect sending. If the domain already receives mail elsewhere, put the MX records on a subdomain such asinbound.example.com, because a lower-numbered MX record would take the mail instead. - A name can receive in one team only. A name that another team already receives on answers
409. - By default only the addresses of your inboxes receive mail. Catch-all accepts every address on the domain. It needs a paid plan and is set in the dashboard or with
receiving_catch_allonPATCH /domains/{id}.
Shared subdomain
Every team also gets a subdomain on a BillionSend shared domain, where its shared inboxes get their addresses. It appears at the end of GET /domains with shared: true. It is already verified and read-only: PATCH, verify and DELETE answer 403 forbidden, and it does not count toward your domain limit. It can send only from your inboxes’ own addresses.
Delete a domain
DELETE /domains/{id}, or Delete on the domain page, is refused with 409 in two cases:
- A topic or segment is bound to the domain. Delete it, or set its
domain_idtonull. - A scheduled or sending broadcast uses the domain. Cancel it, or wait until it has gone out.
Deleting a domain also deletes its inboxes. Recipients’ unsubscribes from the domain are kept, and apply again if you add the same name back.
API keys and domains
An API key can be limited to one domain. Such a key can send only from that domain, and any other from answers 403 restricted_api_key. It reads only the mail received at that domain, sees and changes only that domain under /domains (any other domain answers 404), and the keys it creates are limited to the same domain. Webhooks, suppressions, templates and the rest of what belongs to the whole team answer 403 restricted_api_key; the API keys page lists them. A key can also be limited to one inbox.