Docs / Sending and domains
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
- For each connection with domain support (see the provider catalog), 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.
- Records are merged into one plan:
- Ownership: a TXT record at
_onesend-verify.<domain>with the valueos-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
_dmarcrecord, starting atp=nonewith reports sent to OneSend; tighten toquarantine/rejectonce 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 for the domain.
- Ownership: a TXT record at
- 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. - 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).
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.
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:
{ "tracking": { "opens": true, "clicks": true, "customDomain": "links.acme.dev" } }
opensandclicksaretrue,falseornull.nulluses the workspace default (Settings → Tracking).- Which setting wins, for an email sent from
acme.dev(or from a subdomain such aseu.acme.devthat is not a domain of its own):- the email's own
tracking(POST /v1/emails, a campaign's tracking settings, an automation step); - the domain's
opensandclicks; - the workspace defaults (
settings.trackOpens,settings.trackClicks); - otherwise off.
- the email's own
customDomainmust be a subdomain of the domain (links.acme.devforacme.dev), with no other record at that name. Otherwise the request returns 400tracking_domain_not_subdomain,invalid_tracking_domainortracking_domain_conflict. Sendnullor""to remove it.- The CNAME record (
links.acme.dev→ your server's host fromONESEND_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) andtracking.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.
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.
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):
- 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.domainsis false in its manifest; for example SMTP servers, Azure, ZeptoMail). A domain with no registration at a provider is not set up there. - Allowed providers (optional, per domain). In the Sending providers section of the domain page, choose Only selected providers, or send
PATCH /v1/domains/:idwith{ "allowedConnections": ["con_resend…", "con_ses…"] }. Only those connections send for the domain, and still only where it is verified.nullgoes back to automatic. An empty list is refused (400allowed_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/emailsreturns 422no_provider_for_domain. The message names the domain and says what to do,error.domainanderror.domainIdidentify it, anderror.details.candidateslists each connection with itscode(domain_not_verifiedordomain_not_allowed).- An email that was accepted earlier and lost its provider before delivery fails with the same message, and its
failedevent hasdata.code: "no_provider_for_domain". POST /v1/route/previewreturns the sameerror, the domain's rule indomain, and acodeper 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.
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.
- Detection. When you add a domain, OneSend looks up its NS records (a subdomain such as
mail.acme.devuses its parent zone) and matches them against known DNS hosts:GET /v1/dns-hosts/detect?domain=acme.devreturns{ 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. - 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 whenONESEND_SECRETis rotated. Then:POST /v1/domains/:id/dns-planis a dry run: every record is create, update, no change or conflict, with the reason. Nothing is written.POST /v1/domains/:id/dns-applywith the plan'splanIdwrites the create and update items. If the zone changed since the plan, nothing is written (409plan_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.
- Guided manual setup (every other host, or when you prefer it). The domain page and
GET /v1/domains/:id/dns-setupshow, for that host's form, exactly what to type: the name as@, empty, or the part before the domain (send, orsend.mailfor 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. - Diagnostics.
GET /v1/domains/:id/diagnosticsreports 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, orsendinstead ofsend.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.
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 and 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, 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.
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:
# 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.
The SPF 10-lookup limit
SPF (RFC 7208) 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.