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

  1. 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.
  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 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.
  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).

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" } }
  • 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.

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):

  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.

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 hostSetupWhat the token needs
CloudflareAutomaticAPI token with Zone > DNS > Edit and Zone > Zone > Read for the zone
HostingerAutomatichPanel > profile > API token (account-wide: create one just for OneSend). OneSend validates each change with Hostinger first; Hostinger keeps zone snapshots you can restore
GoDaddyAutomaticProduction API key + secret, or a personal access token. GoDaddy limits DNS API access on some accounts
Amazon Route 53AutomaticIAM access key allowed route53:GetHostedZoneCount, ListHostedZonesByName, ListResourceRecordSets, ChangeResourceRecordSets
DigitalOceanAutomaticPersonal access token with the domain read, create, update and delete scopes
VercelAutomaticAccess token for the team that owns the domain (plus the team ID)
PorkbunAutomaticAPI key + secret with read and dns; turn on API Access for the domain
NamecheapAutomatic (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
DNSimpleAutomaticAccount API token
NetlifyAutomaticPersonal 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, SiteGroundGuided manual—
Any other hostGuided 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:

StatusMeaning
okReceiving is set up with one known host, and the root SPF record includes it
no_mxNo MX records: mail to the domain bounces (nullMx: true when it publishes 0 ., "accepts no mail")
spf_missingMX points to a known host, but the SPF record does not include it
mixedMX records point to several hosts, so mail is split between them
unknown_hostMX points to a host that is not in the catalog
lookup_failedDNS 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).

HostKindMX records (priority)SPF includeFree tierValues
Cloudflare Email RoutingForwardingroute1/2/3.mx.cloudflare.net (assigned by Cloudflare)_spf.mx.cloudflare.netYesVerified. Needs Cloudflare DNS; Cloudflare adds the records when you onboard the domain
ImprovMXForwardingmx1.improvmx.com (10), mx2.improvmx.com (20)spf.improvmx.comYes (1 domain, 25 aliases)Verified
Forward EmailForwardingmx1.forwardemail.net (0), mx2.forwardemail.net (0)spf.forwardemail.netYesVerified
Google WorkspaceMailboxsmtp.google.com (1)_spf.google.comNoVerified (older accounts: ASPMX.L.GOOGLE.COM records, still recognized)
Microsoft 365MailboxPer domain, from the admin center (0)spf.protection.outlook.comNoVerified rule; the MX value is per tenant, so it is not written
Zoho Mail (US)Mailboxmx.zoho.com (10), mx2.zoho.com (20), mx3.zoho.com (50)zohomail.comYes (Forever Free, some data centers)Verified
iCloud+ Custom Email DomainMailboxmx01.mail.icloud.com (10), mx02.mail.icloud.com (10)icloud.comNoVerified
FastmailMailboxin1-smtp.messagingengine.com (10), in2-smtp.messagingengine.com (20)spf.messagingengine.comNoVerified
Proton MailMailboxmail.protonmail.ch (10), mailsec.protonmail.ch (20)_spf.protonmail.chNo (paid plans)Verified
Hostinger EmailMailboxmx1.hostinger.com (5), mx2.hostinger.com (10)_spf.mail.hostinger.comIncluded with some plansVerified
Namecheap Private EmailMailboxmx1.privateemail.com (10), mx2.privateemail.com (10)spf.privateemail.comNoVerified
Zoho Mail (EU, India, Australia, …)MailboxFrom the Zoho Admin Console—Some data centersUnverified: recognized, records not shown
GoDaddy Professional EmailMailboxFrom the Email & Office Dashboard—NoUnverified: recognized, records not shown
IONOS MailMailboxFrom your IONOS account (mx00/mx01.ionos.com in the US)—NoUnverified: 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.