---
title: Domains
description: 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

```bash
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](/docs/concepts/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_tracking` and `click_tracking` on `PATCH /domains/{id}`. See [Tracking](/docs/concepts/tracking).
- **Own tracking and unsubscribe subdomains.** Serve tracked links and unsubscribe links from your own domain. A paid plan is required. See [Tracking](/docs/concepts/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_page` on `PATCH /domains/{id}`. See [Unsubscribes](/docs/concepts/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](/docs/receiving). Turn it on with **Enable receiving** on the domain page, or with `PATCH /domains/{id}`:

```json
{ "capabilities": { "receiving": "enabled" } }
```

- Only a verified domain can turn receiving on. `POST /domains` with `"receiving": "enabled"` answers `422`: add the domain, verify it, then turn receiving on.
- Turning it on adds two `Receiving` records: MX records that point at `mx1.billionsend-dns.com` and `mx2.billionsend-dns.com`, both with priority `10`. 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 as `inbound.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](/docs/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_all` on `PATCH /domains/{id}`.

## Shared subdomain

Every team also gets a subdomain on a BillionSend shared domain, where its shared [inboxes](/docs/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](/docs/concepts/topics) or [segment](/docs/concepts/segments) is bound to the domain. Delete it, or set its `domain_id` to `null`.
- A scheduled or sending [broadcast](/docs/concepts/broadcasts) uses the domain. Cancel it, or wait until it has gone out.

Deleting a domain also deletes its inboxes. Recipients' [unsubscribes](/docs/concepts/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](/docs/api-keys) page lists them. A key can also be limited to one [inbox](/docs/inboxes).
