> ## Documentation Index > Fetch the complete documentation index at: https://docs.helohq.com/llms.txt > Use this file to discover all available pages before exploring further. # Automate customer DNS with Route 53 subdomain delegation > Manage DKIM and Return-Path records for every customer domain programmatically, using a Route 53 reusable delegation set [Domain management for platforms](/platforms/platforms-domain-management) 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 walks through doing that with Amazon Route 53. ## 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. Normally, every Route 53 hosted zone you create is assigned a random set of 4 nameservers. A [reusable delegation set](https://docs.aws.amazon.com/Route53/latest/APIReference/API_CreateReusableDelegationSet.html) 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. ```bash command-line theme={null} aws route53 create-reusable-delegation-set \ --caller-reference "helo-platform-delegation-set" ``` 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. 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: ``` yourplatform.customerdomain.com. NS ns-1487.awsdns-57.org. yourplatform.customerdomain.com. NS ns-406.awsdns-50.com. yourplatform.customerdomain.com. NS ns-870.awsdns-44.net. yourplatform.customerdomain.com. NS ns-1972.awsdns-54.co.uk. ``` 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: ```bash command-line theme={null} dig NS yourplatform.customerdomain.com ``` Once delegation is confirmed, create a Route 53 hosted zone for the customer's subdomain, pinned to your reusable delegation set: ```bash command-line theme={null} aws route53 create-hosted-zone \ --name "yourplatform.customerdomain.com" \ --caller-reference "customer-1234-mail-domain" \ --delegation-set-id "N1PA6795SAMPLE" ``` Because the zone is created with your delegation set, its NS records automatically match what the customer already delegated to — you don't set them manually. Use the [Domains API](/api-reference/domains/create-a-domain) to register the subdomain in Helo, scoped to the [Channel](/core/channels) you use for this customer: ```bash command-line theme={null} curl --location 'https://api.helohq.com/domains' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $HELO_API_KEY' \ --data '{ "name": "yourplatform.customerdomain.com", "channelId": "" }' ``` Helo's response includes the DKIM TXT record and the two Return-Path CNAME records this domain needs — see [Domains](/core/domains) for what those are and why Helo asks for two Return-Path records. Take the records from Helo's response and write them into the hosted zone via the Route 53 API — no customer involvement required: ```bash command-line theme={null} aws route53 change-resource-record-sets \ --hosted-zone-id Z2SAMPLE1234 \ --change-batch file://change-batch.json ``` ```json change-batch.json theme={null} { "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": { "Name": "helo._domainkey.yourplatform.customerdomain.com", "Type": "TXT", "TTL": 300, "ResourceRecords": [{ "Value": "\"\"" }] } }, { "Action": "UPSERT", "ResourceRecordSet": { "Name": "", "Type": "CNAME", "TTL": 300, "ResourceRecords": [{ "Value": "" }] } }, { "Action": "UPSERT", "ResourceRecordSet": { "Name": "", "Type": "CNAME", "TTL": 300, "ResourceRecords": [{ "Value": "" }] } } ] } ``` Trigger verification with the [Verify a domain](/api-reference/domains/verify-a-domain) endpoint, or let Helo's periodic checks pick it up: ```bash command-line theme={null} curl --location --request POST 'https://api.helohq.com/domains//verify' \ --header 'Authorization: Bearer $HELO_API_KEY' ``` Subscribe a [webhook](/core/webhooks) 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`). That's not something Helo currently supports: 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](/platforms/platforms-domain-management) 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](/core/sending-guidelines#protect-your-domain-and-ip-reputation) and [Migrating to Helo from another ESP](/core/sending-guidelines#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](/api-reference/domains/rotate-a-domain-key)), or if you ever need to change providers, the update happens inside the hosted 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 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. ### Give propagation a moment before you automate the next step If you're scripting this end-to-end, don't create the hosted zone or 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 their registrar and the TTL of any records the delegated name previously had. Confirm delegation resolves first. ## Related reading * [Domain management for platforms](/platforms/platforms-domain-management) — the simpler, non-delegated approach * [Domains](/core/domains) — what the DKIM and Return-Path records are and why Helo needs both * [Channels](/core/channels) and [Separate your customers' sending](/platforms/platforms-channels) * [Webhooks](/core/webhooks)