---
title: "Domains and DNS"
description: "Add a domain once, under Senders & domains. OneSend registers it with every connected provider that supports it through their APIs, merges the records they ask for into one DNS plan, and tracks verification per provider."
url: https://onesend.email/docs/domains-and-dns/
---
# Domains and DNS

Add a domain once, under **Senders & domains**. OneSend registers it with every connected provider that supports it through their APIs, merges the records they ask for into one DNS plan, and tracks verification per provider.

```
onesend domains add acme.dev --auto-dns
```

## What happens
1. For each connection with domain support (see the [provider catalog](https://onesend.email/docs/providers/)), OneSend calls the provider's "create domain" API and collects the records it returns. For providers without a domain API, add the domain in the provider's dashboard.
2. Records are merged into one plan:
   - **Ownership:** a TXT record at `_onesend-verify.<domain>` with the value `os-verify=…` shown in the plan. It proves your workspace owns the domain. The domain is only marked verified, and inbound mail is only delivered, after this record is found. Keep it in place.
   - **DKIM:** one record per provider, each under its own selector (e.g. `resend._domainkey`, `brevo1._domainkey`). They coexist without conflict.
   - **SPF:** a single TXT record at each host (see the 10-lookup limit below).
   - **Return-path or bounce subdomains:** where providers support a custom MAIL FROM (e.g. `send.acme.dev`, `bounce.acme.dev`), so each provider's SPF lives on its own subdomain instead of the root.
   - **DMARC:** one `_dmarc` record, starting at `p=none` with reports sent to OneSend; tighten to `quarantine`/`reject` once everything passes.
   - **MX for receiving:** exactly one inbound target per domain (Cloudflare Email Routing or the built-in receiver).
   - **Tracking:** an optional CNAME (e.g. `links.acme.dev`) for open and click tracking, when you set a [custom tracking domain](#per-domain-tracking) for the domain.
3. OneSend detects where the domain's DNS is hosted from its nameservers. If you connected that DNS host (Settings > DNS hosts), **Apply changes** shows the plan and then writes the records. Otherwise the domain page shows exactly what to type at your host, or you can copy every record or download the BIND zone (`GET /v1/domains/:id/zone`). See [Using any DNS host](#using-any-dns-host).
4. **Check again** (`POST /v1/domains/:id/verify`) re-checks DNS and asks each provider to verify. The domain matrix shows each record × provider with live status. The router only uses a provider for a domain after that provider reports it verified (see [Which providers send for a domain](#sending-providers)).

Ownership of verified domains is re-checked daily. A domain loses verified ownership only after its `_onesend-verify` record has been missing for 3 checks spanning at least 24 hours, so one failed DNS answer does not stop inbound mail. Another workspace adding the same name does not affect it. The DNS plan and the zone file always include the ownership record.

<a id="per-domain-tracking"></a>
### Tracking per domain

Each domain has its own open and click tracking, in the **Tracking** section of the domain page or with `PATCH /v1/domains/:id`:

```json
{ "tracking": { "opens": true, "clicks": true, "customDomain": "links.acme.dev" } }
```

- `opens` and `clicks` are `true`, `false` or `null`. `null` uses the workspace default (Settings → Tracking).
- Which setting wins, for an email sent from `acme.dev` (or from a subdomain such as `eu.acme.dev` that is not a domain of its own):
  1. the email's own `tracking` (`POST /v1/emails`, a campaign's tracking settings, an automation step);
  2. the domain's `opens` and `clicks`;
  3. the workspace defaults (`settings.trackOpens`, `settings.trackClicks`);
  4. otherwise off.
- `customDomain` must be a subdomain of the domain (`links.acme.dev` for `acme.dev`), with no other record at that name. Otherwise the request returns 400 `tracking_domain_not_subdomain`, `invalid_tracking_domain` or `tracking_domain_conflict`. Send `null` or `""` to remove it.
- The CNAME record (`links.acme.dev` → your server's host from `ONESEND_PUBLIC_URL`) joins the domain's DNS plan, the zone file and **Apply changes**. It is checked at once and then with the domain's other records. It does not change the domain's status.
- Links and the open pixel in email from the domain use the custom domain only once its CNAME is found and the domain's ownership record is verified. Until then they use the workspace tracking domain, or the server's public URL. The response's `tracking.customDomainStatus` (`pending`, `verified`, `missing`, `mismatch`) and `tracking.effective` (`opens`, `clicks`, `host`) show what email from the domain gets now.
- The server must serve HTTPS for the custom host. Put the host on your TLS certificate, or use a proxy that issues one for each host (Caddy on-demand TLS, Cloudflare).

Click links redirect only to a URL that is in the stored message they belong to. A valid token for any other URL, a tampered token, or a request on a host that is not the public URL or a verified tracking domain of that workspace is refused. So the tracking host is never an open redirect.

<a id="tracking-domain"></a>
### Workspace tracking domain

`settings.trackingDomain` (`PATCH /v1/workspace`) is the default tracking host for every domain without a verified custom tracking domain. It must be the domain itself or a name under a domain that this workspace has verified, for example `t.acme.dev` under `acme.dev`; otherwise the request returns 400 `tracking_domain_unverified`. Point it with a CNAME at your OneSend host. Open, click and view-in-browser links work only on `ONESEND_PUBLIC_URL`'s host, on the workspace's own tracking domain, or on a verified custom tracking domain of one of its domains (and on any `localhost` name outside production). In production, links in mail carried by the Sandbox provider show a test-link page instead of redirecting.

<a id="sending-providers"></a>
## Which providers send for a domain

Providers limit domains differently: some free plans allow one domain, others three. OneSend never sends an email through a provider where its From domain is not set up and verified. Two rules decide which connections may carry an email whose From domain is a domain of the workspace (the domain itself or a subdomain of it):

1. **Automatic (always on).** A connection is eligible only when the domain's registration at that provider is `verified`, or when the provider does not verify domains per sending domain (`capabilities.domains` is false in its manifest; for example SMTP servers, Azure, ZeptoMail). A domain with no registration at a provider is not set up there.
2. **Allowed providers (optional, per domain).** In the **Sending providers** section of the domain page, choose **Only selected providers**, or send `PATCH /v1/domains/:id` with `{ "allowedConnections": ["con_resend…", "con_ses…"] }`. Only those connections send for the domain, and still only where it is verified. `null` goes back to automatic. An empty list is refused (400 `allowed_connections_empty`). Listed providers that do not have the domain yet get it set up when you save; a provider connected later is not set up for a domain that is limited to others.

The routing policy then orders the eligible connections, and failover moves only among them. To use different providers per From domain inside one policy, add a policy rule with `when.fromDomain` (exact names, such as `news.acme.dev`): it replaces the policy's steps for that domain, and both rules above still apply. Example: `acme.dev` allows Resend and SES; a policy rule for `news.acme.dev` uses Brevo first.

When no connection of the routing path may or can send for the From domain:
- `POST /v1/emails` returns 422 `no_provider_for_domain`. The message names the domain and says what to do, `error.domain` and `error.domainId` identify it, and `error.details.candidates` lists each connection with its `code` (`domain_not_verified` or `domain_not_allowed`).
- An email that was accepted earlier and lost its provider before delivery fails with the same message, and its `failed` event has `data.code: "no_provider_for_domain"`.
- `POST /v1/route/preview` returns the same `error`, the domain's rule in `domain`, and a `code` per candidate.

The domain page lists every connection with its state for the domain (can send, waiting for verification, verification failed, not set up, not allowed). **Routing** shows each domain's rule.

<a id="using-any-dns-host"></a>
## Using any DNS host

Verification never depends on your DNS host: OneSend reads the records from public DNS, so a domain at Hostinger, Cloudflare, GoDaddy or anywhere else is verified the same way. What differs is how the records get there.

1. **Detection.** When you add a domain, OneSend looks up its NS records (a subdomain such as `mail.acme.dev` uses its parent zone) and matches them against known DNS hosts: `GET /v1/dns-hosts/detect?domain=acme.dev` returns `{ host, confidence, nameservers, automatic, zone }`. You can pick another host on the domain page (`PATCH /v1/domains/:id/dns-host`) if the guess is wrong.
2. **Automatic setup** (hosts with a connector). Create an API token at the host and add it under Settings > DNS hosts (`POST /v1/dns-hosts/connections`). The token is encrypted at rest (like provider credentials), never returned, and re-encrypted when `ONESEND_SECRET` is rotated. Then:
   - `POST /v1/domains/:id/dns-plan` is a dry run: every record is **create**, **update**, **no change** or **conflict**, with the reason. Nothing is written.
   - `POST /v1/domains/:id/dns-apply` with the plan's `planId` writes the create and update items. If the zone changed since the plan, nothing is written (409 `plan_changed`). The response lists the previous values, and for Hostinger the snapshot that holds the earlier zone, so a change can be undone.
   - Rules every host follows: SPF is merged into your existing SPF record (never a second one, which would make SPF fail; two existing SPF records are merged into one); an existing DMARC policy is kept; a CNAME is never added next to other records or at the root; an MX record is not added where the domain already receives mail somewhere else. Those cases are shown as conflicts and not written.
3. **Guided manual setup** (every other host, or when you prefer it). The domain page and `GET /v1/domains/:id/dns-setup` show, for that host's form, exactly what to type: the name as `@`, empty, or the part before the domain (`send`, or `send.mail` for a subdomain sender in the parent zone); whether to add quotes; whether long TXT values are pasted whole or as quoted 255-character parts; the MX priority field; and a TTL. Each value has a copy button, and the list re-checks every 20 seconds.
4. **Diagnostics.** `GET /v1/domains/:id/diagnostics` reports each record as found, missing, wrong value or still propagating (seen by the DNS host or by a second public resolver but not yet by the first), and explains common mistakes with a fix: the domain typed twice (`send.acme.dev.acme.dev`), extra quotation marks, two SPF records, SPF missing an include, a DKIM key cut short or with spaces, a CNAME at the root or hiding other records, MX missing or with another priority, mail also going to another MX host, two DMARC records, and a record added on the wrong name (the root, or `send` instead of `send.mail`). Results are cached for a minute; `?fresh=true` (the **Check again** button) checks again. Unverified domains are also re-checked in the background: with growing delays for about two days, then daily for two weeks.

| DNS host | Setup | What the token needs |
|---|---|---|
| Cloudflare | Automatic | API token with Zone > DNS > Edit and Zone > Zone > Read for the zone |
| Hostinger | Automatic | hPanel > profile > API token (account-wide: create one just for OneSend). OneSend validates each change with Hostinger first; Hostinger keeps zone snapshots you can restore |
| GoDaddy | Automatic | Production API key + secret, or a personal access token. GoDaddy limits DNS API access on some accounts |
| Amazon Route 53 | Automatic | IAM access key allowed `route53:GetHostedZoneCount`, `ListHostedZonesByName`, `ListResourceRecordSets`, `ChangeResourceRecordSets` |
| DigitalOcean | Automatic | Personal access token with the `domain` read, create, update and delete scopes |
| Vercel | Automatic | Access token for the team that owns the domain (plus the team ID) |
| Porkbun | Automatic | API key + secret with `read` and `dns`; turn on API Access for the domain |
| Namecheap | Automatic (beta) | API key, your username, and this server's IP on the API allowlist; the domain must use BasicDNS. Namecheap replaces all records on every change, so OneSend re-reads and resends them all |
| DNSimple | Automatic | Account API token |
| Netlify | Automatic | Personal access token (Netlify has no update call: a change deletes and recreates the record) |
| Squarespace Domains (Google Domains), IONOS, OVHcloud, Gandi, Wix, Hetzner, Bluehost, Hover, NameSilo, Azure DNS, SiteGround | Guided manual | — |
| Any other host | Guided manual (general steps) | — |

The connectors are written against each host's published API reference (linked from `GET /v1/dns-hosts`). Hostinger's API reference does not document the MX content format; OneSend sends `10 mail.example.com.` (priority first) and reads MX records in that form, so check an MX change in hPanel the first time.

**Adding a host.** Host data lives in `packages/core/src/dns`: a nameserver pattern in `detect.ts`, the form rules and steps in `guides.ts`, and, for automatic setup, an adapter in `hosts/` implementing `DnsHostAdapter` (find the zone, list records, write single records or whole name-and-type sets). Planning, SPF merging and diagnostics are shared, so a new adapter only translates the host's API.

<a id="receiving-email"></a>
## Receiving email

Mail sent to `you@acme.dev` goes to whatever host the domain's **MX records** point to. That can be OneSend itself: the self-hosted edition has a team inbox, so with inbound turned on for the domain and its ownership verified, OneSend receives the mail through its built-in receiver (MX pointed at your server), Cloudflare Email Routing or a provider's inbound webhook, and files it into workspace mailboxes. See [Inbox](https://onesend.email/docs/inbox/) and [Receiving mail](https://onesend.email/docs/self-hosting/#receiving-mail). The mail can also go elsewhere: a forwarding service that passes it on to an inbox you already have, or a mailbox host. The domain page has a **Receiving email** section after the sending records (and the add-domain wizard a **Receiving email** step) that asks *Where should email to @acme.dev arrive?*:

- **Forward to an inbox I have**, for example Cloudflare Email Routing to your Gmail;
- **A mailbox host** such as Google Workspace or Microsoft 365;
- **I already have this set up**: OneSend only checks the MX records and confirms;
- **Skip for now**: nothing changes.

The choice is saved on the domain (`PATCH /v1/domains/:id/receiving`); DNS is never changed by choosing.

**Detection.** `GET /v1/domains/:id/receiving` reads the MX and SPF records from public DNS (`ONESEND_DNS_OVERRIDES` in development) and matches each MX target against the catalog below:

| Status | Meaning |
|---|---|
| `ok` | Receiving is set up with one known host, and the root SPF record includes it |
| `no_mx` | No MX records: mail to the domain bounces (`nullMx: true` when it publishes `0 .`, "accepts no mail") |
| `spf_missing` | MX points to a known host, but the SPF record does not include it |
| `mixed` | MX records point to several hosts, so mail is split between them |
| `unknown_host` | MX points to a host that is not in the catalog |
| `lookup_failed` | DNS could not be asked; the last known status is kept |

The response also has `recommendation`: the records for the chosen host (or `?hostId=`, or the detected host), typed for the domain's DNS host (`?dnsHost=` for another), and **one** SPF record merged from what is published now, the sending providers' root SPF and the host's include, with the DNS lookups counted through nested includes (limit 10; over it, `spf_over_limit` is a warning). `warnings` say, among others, when pointing MX elsewhere would move existing mail (`mx_change_moves_mail`) and when the domain is a subdomain (its MX records do not affect the parent domain). The last status is stored on the domain, so the domain list shows a receiving badge without a DNS lookup per row; verification checks refresh it.

**Applying.** When the domain's DNS host is connected (Settings > DNS hosts), `POST /v1/domains/:id/receiving/apply` with `{ "hostId": "google-workspace" }` previews the change (`mode: "preview"`, the default): MX records to create, update or remove, the merged SPF record, and conflicts. Nothing is written. `mode: "confirm"` with the preview's `planId` writes it (409 `plan_changed` when the zone changed in between). If mail arrives at another host now, its MX records are listed in `existingMx` and are only removed with `replaceExisting: true` (otherwise 409 `mx_in_use`); old and new MX records are never left side by side. The response lists the previous records so the change can be undone. The dashboard shows the same preview and asks you to confirm the move. Applying needs the admin role; test-mode keys are refused. Hosts whose records are per account (Microsoft 365) or unverified are never written: follow their setup page. Without a connection, copy the records shown for your DNS host (Cloudflare, Hostinger, GoDaddy, Namecheap, Route 53 and the others in the table above).

Most hosts also need their own verification TXT record and DKIM records, generated in their console; the catalog (`GET /v1/receiving-hosts`) lists them as notes and links to each host's setup page. Create the mailboxes or forwarding rules at the host before switching MX, so no mail is lost. These mailboxes can also be brought into the OneSend inbox as [connected accounts](https://onesend.email/docs/unified-inbox/), on a self-hosted server and in the Mac app (Settings > Accounts).

| Host | Kind | MX records (priority) | SPF include | Free tier | Values |
|---|---|---|---|---|---|
| Cloudflare Email Routing | Forwarding | `route1/2/3.mx.cloudflare.net` (assigned by Cloudflare) | `_spf.mx.cloudflare.net` | Yes | Verified. Needs Cloudflare DNS; Cloudflare adds the records when you onboard the domain |
| ImprovMX | Forwarding | `mx1.improvmx.com` (10), `mx2.improvmx.com` (20) | `spf.improvmx.com` | Yes (1 domain, 25 aliases) | Verified |
| Forward Email | Forwarding | `mx1.forwardemail.net` (0), `mx2.forwardemail.net` (0) | `spf.forwardemail.net` | Yes | Verified |
| Google Workspace | Mailbox | `smtp.google.com` (1) | `_spf.google.com` | No | Verified (older accounts: `ASPMX.L.GOOGLE.COM` records, still recognized) |
| Microsoft 365 | Mailbox | Per domain, from the admin center (0) | `spf.protection.outlook.com` | No | Verified rule; the MX value is per tenant, so it is not written |
| Zoho Mail (US) | Mailbox | `mx.zoho.com` (10), `mx2.zoho.com` (20), `mx3.zoho.com` (50) | `zohomail.com` | Yes (Forever Free, some data centers) | Verified |
| iCloud+ Custom Email Domain | Mailbox | `mx01.mail.icloud.com` (10), `mx02.mail.icloud.com` (10) | `icloud.com` | No | Verified |
| Fastmail | Mailbox | `in1-smtp.messagingengine.com` (10), `in2-smtp.messagingengine.com` (20) | `spf.messagingengine.com` | No | Verified |
| Proton Mail | Mailbox | `mail.protonmail.ch` (10), `mailsec.protonmail.ch` (20) | `_spf.protonmail.ch` | No (paid plans) | Verified |
| Hostinger Email | Mailbox | `mx1.hostinger.com` (5), `mx2.hostinger.com` (10) | `_spf.mail.hostinger.com` | Included with some plans | Verified |
| Namecheap Private Email | Mailbox | `mx1.privateemail.com` (10), `mx2.privateemail.com` (10) | `spf.privateemail.com` | No | Verified |
| Zoho Mail (EU, India, Australia, …) | Mailbox | From the Zoho Admin Console | — | Some data centers | Unverified: recognized, records not shown |
| GoDaddy Professional Email | Mailbox | From the Email & Office Dashboard | — | No | Unverified: recognized, records not shown |
| IONOS Mail | Mailbox | From your IONOS account (`mx00/mx01.ionos.com` in the US) | — | No | Unverified: recognized, records not shown |

The sources of every value are in `packages/core/src/dns/receiving.ts`. To add a host, add an entry there (MX records, the SPF include, the MX names that identify it, its setup page and sources) and a fixture to `packages/core/test/dns/receiving.test.ts`.

<a id="testing-locally"></a>
## Testing domains locally

Domains such as `acme.test` have no public DNS, so they cannot be verified normally. In development (not when `NODE_ENV=production`), set `ONESEND_DNS_OVERRIDES` to inline JSON or the path of a JSON file:

```bash
# every record OneSend checks under acme.test (ownership TXT, DKIM, SPF, MX) is answered as expected
ONESEND_DNS_OVERRIDES='{"acme.test":"*"}'

# or exact answers by name and type (TXT, MX, CNAME, A, NS)
ONESEND_DNS_OVERRIDES='{"_onesend-verify.acme.test":{"TXT":["os-verify=…"]}}'

# NS answers drive DNS host detection, for example to try the Hostinger instructions locally
ONESEND_DNS_OVERRIDES='{"acme.test":{"NS":["ns1.dns-parking.com","ns2.dns-parking.com"]}}'
```

Names under an overridden domain are never looked up in public DNS. The server logs a warning at startup while overrides are active. With the domain verified, inbound mail works locally through the built-in receiver (port 2525), `/ingest/cloudflare`, forwarding and replies. Provider verification still depends on each provider. See [Try the inbox locally](https://onesend.email/docs/getting-started/#try-the-inbox-locally).

## The SPF 10-lookup limit
SPF ([RFC 7208](https://www.rfc-editor.org/rfc/rfc7208#section-4.6.4)) allows at most **10 DNS lookups** while evaluating a record; `include:`, `a`, `mx`, `redirect` and nested includes all count. Each provider's `include:` typically costs 1 to 4 lookups, so stacking 5 to 7 providers on the root domain exceeds the limit and SPF returns `permerror`, which can fail DMARC.

How OneSend avoids it:
- **DMARC passes on DKIM alignment alone.** Every provider signs with DKIM for your domain, so SPF on the root is not required for DMARC.
- **Per-provider return-path subdomains** keep each provider's SPF include on its own host.
- The DNS plan **counts lookups** and warns before you publish a record over the limit.

## One sending domain or several?
Using a subdomain per purpose (`mail.acme.dev` for transactional email, `news.acme.dev` for campaigns) separates their reputation, so a spike in campaign complaints does not affect password-reset delivery. Add each one as a domain to give it its own providers and tracking settings.

## Buying domains
OneSend does not sell domains. Buy one from Cloudflare, Namecheap, Porkbun or any registrar. If its DNS host is in the table above, OneSend can write the records for you; otherwise follow the steps on the domain page.
