Skip to main content
Domain management for platforms covers the standard flow: your customer adds a domain, you show them the DNS records Helo generates, and they paste those records in at their own DNS provider. That works well, but it means a manual DNS step for every customer, and it ties each customer’s DNS directly to Helo’s records. If you ever want to stop using Helo or add another email service provider to the mix, you have to go back to that customer and ask them to update their DNS records again. An arguably better pattern is NS delegation, where your customer delegates a subdomain to your name servers so you can control the related DNS records instead. Doing so allows you to make future changes to their DNS records, which you might need to do if you want to:
  • rotate or manage their DKIM keys for them
  • add the ability to send to a new email service provider (ESP) or migrate from one ESP to another
That second point is especially powerful. If you’re a platform, locking all or most of your customers to a single ESP, including Helo, can represent a significant business risk. We believe platforms should be free to use whichever ESP (or combination of ESPs) that works best for them, given the current circumstances, without arbitrary vendor lock-in. This guide covers two ways to set that up. Cloudflare DNS is the recommended default because it supports custom (vanity) nameservers, so every customer delegates to the same branded set — such as ns1.yourplatform.com and ns2.yourplatform.com — instead of a Cloudflare-branded pair. That does require a Business or Enterprise plan, though. If you’re using AWS and would prefer to use Route 53 instead, the reusable delegation set approach is below.

​
The one-time customer step: NS delegation

Instead of asking a customer to add Helo’s specific TXT and CNAME records, ask them to add NS records that delegate a subdomain — for example yourplatform.customerdomain.com — to nameservers you control. Once that’s in place, yourplatform.customerdomain.com is a zone you fully manage. You can add, change, or remove any record underneath it without ever going back to the customer, including if you rotate a DKIM key or change providers down the line. The only difference between the two providers below is how you get those nameservers and where you write records afterward. Cloudflare is the recommended default because it supports custom (vanity) nameservers: you can serve every customer’s zone from a single consistent, on-brand set like ns1.yourplatform.com and ns2.yourplatform.com. That gives you the same one-time-to-document nameserver set that Route 53 gets from a reusable delegation set, without tying customer DNS to AWS. Custom nameservers require a Business or Enterprise plan. The mechanics are otherwise the same as any DNS provider: you add each customer’s subdomain to your Cloudflare account as its own zone, and Cloudflare assigns that zone a pair of nameservers when you create it. You surface the appropriate nameservers to the customer and then manage all of the zone’s records through the Cloudflare API.
Account custom nameservers, the single set shared by every zone in your account, are available on Enterprise plans, and on Business plans after you contact Cloudflare Support. If you’d rather not depend on a Cloudflare plan, the Route 53 approach is available on all AWS accounts.
1

Add the customer's subdomain as a Cloudflare zone

Create the zone with an API token that has Zone:Edit and DNS:Edit permissions, scoped to All zones in your account so the token can create new zones:
command-line
The response returns the zone id — which you’ll use for every DNS write — and name_servers, the pair of nameservers this zone is pinned to (for example john.ns.cloudflare.com and melinda.ns.cloudflare.com). Save both on the customer’s record.
If you’re using Cloudflare’s assigned nameservers, this pair differs per zone, so generate the NS records you show each customer from this response rather than hardcoding them. If you’ve configured account custom nameservers, use those (ns1.yourplatform.com, ns2.yourplatform.com, and so on) for every customer instead — that’s the single branded set that makes Cloudflare the recommended default.
2

Ask your customer to delegate their sending subdomain

This is the only manual DNS step your customer will ever do. Show them the two name_servers from step 1 and ask them to add NS records for the subdomain they want to send from:
If you’re using account custom nameservers, these are identical for every customer and can be baked straight into your onboarding docs or in-product instructions. If you’re using the assigned nameservers, generate them per customer from the zone-create response.NS propagation isn’t instant. Before moving on, confirm delegation has actually taken effect. dig +trace follows the delegation down from the root, so you can see the parent zone handing off to your nameservers:
command-line
3

Create the domain in Helo

Use the Domains API to register the subdomain in Helo, scoped to the Channel you use for this customer:
command-line
Helo’s response includes the DKIM TXT record (dnsRecords.domainKeyActive) and the two Return-Path CNAME records (dnsRecords.returnPath) this domain needs. Each record has a host and a value. See Domains for what those records are and why Helo asks for two Return-Path records.
4

Write the records into the zone

Take the records from Helo’s response and create them with the Cloudflare DNS records API — no customer involvement required. Create the DKIM TXT record first:
command-line
Then create each of the two Return-Path CNAME records Helo returned:
command-line
Repeat that request for the second Return-Path record, using <return-path-host-2-from-helo> and <return-path-value-2-from-helo>.
Keep "proxied": false on the Return-Path CNAMEs. If Cloudflare proxies them, they resolve to Cloudflare’s IPs instead of Helo’s, which breaks Return-Path verification and bounce handling. These records must stay DNS only.
5

Verify the domain and listen for the result

Trigger verification with the Verify a domain endpoint, or let Helo’s periodic checks pick it up:
command-line
Subscribe a webhook to the domain-key-verified, domain-key-verification-failed, return-path-domain-verified, and return-path-domain-verification-failed events (optionally scoped to this customer’s Channel) so your product can reflect real verification status without polling.

​
Option 2: Route 53 (if you’re using AWS)

If you’re using AWS and would prefer to use Route 53 instead, a reusable delegation set pins every customer’s hosted zone to one fixed set of 4 nameservers. That means the NS records are identical for every customer, so you can document them once and never look them up per customer.
1

Create a reusable delegation set

Normally, every Route 53 hosted zone you create is assigned a random set of 4 nameservers. A reusable delegation set flips that around: you create one fixed set of 4 nameservers up front, then assign every customer’s hosted zone to that same set. Do this once, not per customer.
command-line
The response includes an Id (something like /delegationset/N1PA6795SAMPLE) and 4 NameServers. Save both — you’ll reuse the delegation set ID for every hosted zone you create, and the nameserver names are what you’ll show every customer.
Route 53 doesn’t support renaming these to something like ns1.yourplatform.com. A reusable delegation set gets you consistent nameservers across every customer, not vanity ones — which is enough to document once and never look up per customer. True vanity nameservers mean moving to a DNS provider built for that specifically, and most platforms don’t need it.
2

Create a hosted zone for the subdomain

Create a Route 53 hosted zone for the customer’s subdomain, pinned to your reusable delegation set:
command-line
Because the zone is created with your delegation set, its NS records automatically match the nameservers from step 1 — you don’t set them manually. The response includes the hosted zone’s Id (for example /hostedzone/Z2SAMPLE1234). Save it on the customer’s record, because you’ll use it for every DNS write.
Create the hosted zone before the customer adds their NS records. If the customer delegates to nameservers that don’t host a zone for the subdomain yet, lookups fail and the delegation is left dangling.
3

Ask your customer to delegate their sending subdomain

This is the only manual DNS step your customer will ever do. Show them the 4 nameservers from step 1, and ask them to add NS records for the subdomain they want to send from:
Because these NS records are identical for every customer, you can bake them straight into your onboarding docs or in-product instructions — no per-customer lookup needed.NS propagation isn’t instant. Before moving on, confirm delegation has actually taken effect. dig +trace follows the delegation down from the root, so you can see the parent zone handing off to your nameservers:
command-line
4

Create the domain in Helo

Use the Domains API to register the subdomain in Helo, scoped to the Channel you use for this customer:
command-line
Helo’s response includes the DKIM TXT record (dnsRecords.domainKeyActive) and the two Return-Path CNAME records (dnsRecords.returnPath) this domain needs. Each record has a host and a value. See Domains for what those records are and why Helo asks for two Return-Path records.
5

Write the records into the hosted zone

Take the records from Helo’s response and write them into the hosted zone via the Route 53 API, using the hosted zone ID from step 2 — no customer involvement required:
command-line
change-batch.json
Route 53 limits each string in a TXT record to 255 characters, and a 2048-bit DKIM key is longer than that. Split the DKIM value into chunks of 255 characters or fewer, each wrapped in its own quotes and separated by a space, such as "\"<first-255-chars>\" \"<rest-of-value>\"". Receivers join the chunks back together when they look up the key.
6

Verify the domain and listen for the result

Trigger verification with the Verify a domain endpoint, or let Helo’s periodic checks pick it up:
command-line
Subscribe a webhook to the domain-key-verified, domain-key-verification-failed, return-path-domain-verified, and return-path-domain-verification-failed events (optionally scoped to this customer’s Channel) so your product can reflect real verification status without polling.

​
Good to know

​
This assumes your customers are fine sending from a subdomain

Helo requires an exact match between the domain you verify and the domain you send from. If you verify yourplatform.customerdomain.com, mail has to come from an address on that exact domain (e.g. hello@yourplatform.customerdomain.com) — there’s no way to verify a subdomain and send from its parent (hello@customerdomain.com). You might expect DMARC’s default relaxed alignment to get around this — under relaxed alignment, a DKIM signature from a subdomain (d=yourplatform.customerdomain.com) does align with a From header on the parent domain, since alignment only requires a shared organizational domain, not an exact match. That’s true as a general DMARC mechanic (it breaks down only for the small minority of domains that publish adkim=s). Helo doesn’t currently support it, though: domain verification, DKIM signing, and the From-address check on every send all key off an exact match today, with no subdomain/parent-domain logic in the pipeline. So the constraint holds in practice regardless of what DMARC alignment would technically permit. It’s worth knowing that even if this were supported, you’d probably want to avoid it anyway. Mailbox providers weigh the visible From domain heavily when building sender reputation, not just the authenticated identity DMARC checks. If a customer’s mail shows From: someone@customerdomain.com while actually being signed and delivered through a subdomain, their root domain’s reputation is on the hook for whatever gets sent through your platform — and vice versa, any reputation the root domain already has (good or bad) bleeds onto your platform’s sending. That’s exactly the mixing a dedicated sending subdomain is normally used to prevent (it’s why Google’s bulk sender guidelines recommend separating bulk mail onto its own subdomain in the first place). Exact-match domain verification, whatever its origin, ends up enforcing the isolation you’d want by default anyway. So this entire pattern only works if your customers are okay sending from a subdomain rather than their bare domain. A subdomain still clearly belongs to the customer’s brand, and most recipients don’t scrutinize the From address that closely. Delegating an entire subdomain does require a certain level of trust and should be something your customers are comfortable doing though. It’s worth noting that any subdomain can be used: it could be yourplatform.customerdomain.com or something else, including one of your customer’s choosing. If a customer specifically wants to send from their root domain, NS delegation of a subdomain won’t get you there. You’d need them to add records directly at their root domain instead, which puts you back in the manual, per-record flow for that customer. Worth confirming this is an acceptable tradeoff with a few customers before you build this out broadly.

​
Delegation controls DNS, not reputation

This pattern solves the DNS bottleneck: once a customer delegates their subdomain, you never need to go back to them for another record change. It does not solve the reputation bottleneck, and it’s worth being explicit about that with anyone building this. Inbox providers build trust in a domain or IP gradually, based on how recipients respond to mail actually sent from it — not based on what DNS says is authorized to send. If you ever move a customer’s sending from one ESP to another (including away from Helo), updating the records in the hosted zone is a quick process, but the new infrastructure behind those records still has no track record with inbox providers. Sending a customer’s full volume through it on day one will look like a spam run, however clean the DNS is. Treat a provider switch as a gradual cutover, not a DNS flip:
  • Run both providers in parallel for a period rather than switching 100% of a customer’s mail in one day.
  • Shift volume over gradually, watching bounce and complaint rates as you go.
  • Since each customer’s sending is already isolated (by Channel, if you’re on Helo), migrate customers in staggered cohorts instead of all at once — prove out deliverability on a few before moving the rest.
See Protect your domain and IP reputation and Migrating to Helo from another ESP for the warm-up practices themselves — this delegation setup makes those migrations easier to execute (no per-customer DNS step required), but doesn’t shorten how long they should take.

​
This makes future changes a background job, not a support ticket

If Helo asks you to rotate a domain’s DKIM key (via Rotate a domain key), or if you ever need to change providers, the update happens inside the zone you already control. Nobody emails the customer, and nobody’s DNS needs to change on their end — the NS delegation they set up once keeps pointing at your infrastructure regardless of what’s underneath it.

​
Hosted zones aren’t free on Route 53

Route 53 charges a small monthly fee per hosted zone. Factor that into your per-customer costs, and clean up zones for customers who churn. On Cloudflare, check how your plan prices and caps additional zones, and delete zones (for example, DELETE /zones/<zone-id>) when customers churn.

​
Give propagation a moment before you automate the next step

If you’re scripting this end-to-end, don’t attempt verification immediately after asking the customer to add NS records. Propagation can take anywhere from a few minutes to a few hours, depending on the customer’s DNS provider and how long resolvers have cached earlier answers for the subdomain. Confirm delegation resolves first, then write the records and verify.