KoltrixDomain verification flows: checking DNS and explaining failures
Letting customers send from their own domain means checking their DNS. How to verify ownership, SPF, DKIM and DMARC and turn a failure into a clear fix.
On this page(9 sections)
If your product lets customers send email from their own domain, sooner or later you build a screen that says "Add these DNS records". It looks simple. It becomes the most-visited support topic in your product.
Customers do not know what a TXT record is, their DNS provider formats things in unexpected ways and the records take time to appear. Your job is to check their DNS reliably and, when something is wrong, say exactly what and how to fix it. This guide covers the checks, the traps and the way to word failures.
If you are the customer setting up records for a service, DNS records for email is the reference. This post is for the person building the flow.
What you are verifying
A typical setup asks for several records, each with a different job.
| Record | Purpose | What you check |
|---|---|---|
| Ownership TXT | Proves the customer controls the domain | A TXT value at a known name matching a token you issued |
| MX | Routes incoming mail to you (if you receive) | Hosts and priorities |
| SPF | Authorises you to send for the domain | Your include is present, and there is only one SPF record |
| DKIM | Signs mail with a key for the domain | A TXT at the selector with the expected public key |
| DMARC | Tells receivers what to do on failure | A valid policy exists |
Treat ownership as the gate. Until it passes, do not send mail for the domain or accept it as verified.
Ownership: first one with the token wins
Domain ownership claims are an attack surface. If two customers can add the same domain, one could block the real owner.
- Issue a unique token per workspace and domain, and have the customer publish it at a record only the owner can set.
- Verify by looking up that exact record and comparing the value.
- Decide a clear rule for conflicts: the workspace whose own token appears in DNS wins, and a pending claim by someone else does not block it.
- Re-check ownership periodically. A domain can change hands, and an old record can be left behind. See dangling DNS and email risks.
Doing the DNS lookups well
Query the authoritative source. Use a resolver you control and ask for the exact record type and name. Handle timeouts and server failures as "unknown", not as "missing".
Expect delay. Records can take minutes to hours to appear, depending on the TTL set earlier and the provider. See DNS TTLs and authentication changes. Retry in the background, and show "Checking…" with a "Check again" button, rather than failing instantly.
Accept harmless variations.
- Names are case-insensitive.
- A TXT value may be split into several quoted strings, which is normal for long DKIM keys. Join them before comparing. See 2048-bit DKIM keys and TXT strings.
- Trailing dots, extra spaces and surrounding quotes may appear. Normalise before comparing.
- Some providers add the domain to a record name automatically, producing
kx1._domainkey.example.com.example.com. Detect that pattern and say so.
Be strict about what matters. A DKIM key with a missing character will not verify mail, so require an exact match for the key.
SPF: the check that gets complicated
SPF is where most verification logic grows.
- One record only. Two separate SPF records cause a permanent error. Detect this and tell the customer to merge them. See multiple SPF records.
- Merge, do not replace. If a record exists, show them the combined value with your include added.
- Look for your include, not an exact string match on the whole record.
- The ten-lookup limit. Each include and similar term counts. A record that already uses many services can fail after you add yours. See the SPF 10-lookup limit. Count the lookups and warn when the total gets near the limit.
- The all mechanism. Do not tell customers to remove a strict ending without understanding it. Explain what they have and what you recommend.
DMARC: guide, do not force
You may want DMARC in place, but a customer's existing policy is theirs.
- If they have a valid DMARC record, keep it. Do not ask them to replace it.
- If none exists, suggest a starting policy, usually monitoring or quarantine, and explain what it does.
- Never tell a customer to jump straight to the strictest policy without reading reports. See moving DMARC from none to reject.
How to word failures
The difference between a good and a bad flow is the error message. Give each failure a specific cause and a specific next step.
| Bad message | Better message |
|---|---|
| "DNS verification failed." | "We could not find a TXT record at _example with the value we gave you. DNS changes can take up to an hour. Check again in a few minutes." |
| "SPF invalid." | "Your domain has two SPF records. Combine them into one, and add include:spf.example.net. Here is the combined value." |
| "DKIM mismatch." | "The DKIM record at selector._domainkey is missing part of the key. Copy it again with the Copy button and paste it in one go." |
| "Unknown error." | "Your DNS provider did not answer in time. We will retry automatically." |
Good messages share a pattern:
- Name the record and where it should be.
- Say what you saw. "Found a different value", "found nothing", "found two".
- Say what to do, with the exact value and a copy button.
- Say how long to wait, if relevant.
Show where to add records for the common providers, with short screenshots or links, and show the short host name (selector._domainkey) as well as the full name.
Make the status visible and calm
- Show each record as pending, verified or needs attention, with a short reason.
- Check automatically in the background and update the screen.
- Keep a Check now button, rate limited.
- Send an email when verification succeeds or when a previously verified record breaks.
- Keep legacy setups working. If you introduce better records later, show them as a recommended upgrade rather than turning mail off.
For an example of a five-record flow, see adding a domain to Koltrix: the five records, and for the sending side of customer domains, sending for customer domains.
Test with real mess
Build tests using DNS responses you have seen:
- a value split into two strings;
- a doubled domain name;
- two SPF records;
- a DKIM key with one wrong character;
- a lookup timeout;
- a record that exists but at the wrong name.
Each should produce a different, correct message.
Key takeaways
- Treat ownership as the gate, with a unique token and a clear rule for conflicts.
- Retry in the background, normalise harmless differences and be strict only where it matters.
- Detect two SPF records, count lookups and keep customers' existing DMARC.
- Write failures that name the record, say what you found and give the exact fix.
- Re-check periodically, and keep older setups working while you suggest upgrades.
Start with Koltrix
Your domain, one inbox, and an API that sends.
A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.
