A user signs up, waits for the 6-digit code, and nothing shows up. They check spam: there it is. Or worse, it isn't anywhere.
Verification emails are the most important mail your app sends, and they're also the easiest to break without noticing, because your test inbox usually still gets them. This is the checklist I go through, in order, whenever someone reports "I never got the code". I learned most of it while setting up outbound mail for a small email service I run, where every mistake shows up in a real user's spam folder within a day.
The short version: don't guess. Read the headers of one email that went to spam, and they'll tell you which of the five problems below you have.
Step 0: get one bad email and read its headers
Ask the user (or reproduce with your own Gmail/Outlook account) for one message that landed in spam.
- Gmail: open the message → ⋮ → Show original.
- Outlook.com: open the message → ⋯ → View → View message source.
At the top, Gmail shows a small summary like this:
SPF: PASS with IP 203.0.113.10 DKIM: 'PASS' with domain mail.example.com DMARC: 'PASS' Further down, the Authentication-Results header has the details:
Authentication-Results: mx.google.com; dkim=pass header.i=@mail.example.com header.s=s1; spf=pass smtp.mailfrom=bounces.example-esp.com; dmarc=pass (p=NONE) header.from=example.com Write down three things: SPF result, DKIM result (and which domain signed it), DMARC result. Now go through the list.
1. SPF or DKIM fails
If either says fail, softfail, none or neutral, start here. Usual causes:
- You added a new sending service and forgot SPF. Your SPF record must
include:every service that sends as your domain: your email provider, your transactional ESP, your helpdesk, your marketing tool. There's a limit of 10 DNS lookups in one SPF check; go over it and SPF returnspermerror, which counts as a failure. - Two SPF records. A domain must have exactly one
v=spf1TXT record. Two records =permerror. This happens a lot when someone "adds" SPF for a new tool instead of editing the existing record. - DKIM was never enabled. Most ESPs give you 2–3 CNAME or TXT records to publish and a "verify" button. Until you click it, mail goes out unsigned or signed with the ESP's own domain.
- The DKIM key record got truncated. Long TXT values pasted into some DNS panels get cut or get stray quotes. Look the record up with
digand compare it to what the ESP shows:
dig +short TXT example.com # SPF dig +short TXT s1._domainkey.example.com # DKIM, "s1" is the selector from header.s= dig +short TXT _dmarc.example.com # DMARC 2. SPF and DKIM pass, but DMARC fails: alignment
This one confuses everybody. SPF and DKIM can both say pass and DMARC still fails, because DMARC also checks that the passing domain matches the domain in the visible From: address.
Look at the headers again:
-
header.from=example.com← what the user sees -
smtp.mailfrom=bounces.example-esp.com← SPF checked this domain -
header.i=@example-esp.com← DKIM signed with this domain
If neither SPF's domain nor DKIM's domain is example.com (or a subdomain of it, under the default relaxed alignment), DMARC fails, even though both "passed".
Fixes:
- DKIM: set up the ESP's custom domain signing so it signs as
example.com(that's what the CNAME records in step 1 are for). This is the fix that matters most, because DKIM survives forwarding and SPF doesn't. - SPF: many ESPs let you set a custom return-path/bounce domain like
bounces.example.com. That makes SPF aligned too.
Since February 2024, Gmail and Yahoo require SPF or DKIM on all mail, and an aligned DMARC pass for bulk senders. Verification email from a growing app gets caught by this sooner than people expect.
3. Authentication is fine, but the domain or IP has a bad reputation
If everything passes and mail still goes to spam, the receiver doesn't trust the sender. Common reasons:
- Brand-new domain. A domain registered last week sending its first email has no history. Start with low volume and real users, not a burst of test sign-ups.
- Shared IP reputation. On an ESP's shared pool, other customers' behavior affects you. Most ESPs have a status or "deliverability" page per account; check it.
- The same domain sends marketing. If your newsletter gets marked as spam, your verification codes from the same domain suffer too. Send transactional mail from a subdomain (
notify.example.com) so its reputation is separate. - Blocklists. If you run your own mail server, check your sending IP on a few DNS blocklists (MXToolbox's blacklist check covers the common ones) and make sure the IP has a reverse DNS (PTR) record that matches the hostname your server announces. Mail from an IP without PTR is treated very badly by large providers.
- Gmail-specific: register the domain in Google Postmaster Tools. Once you send enough volume, it shows your domain's reputation and spam rate as Gmail sees them. Keep the user-reported spam rate well under 0.3%.
4. The content looks like phishing
Verification emails look like phishing by design: "Click here to confirm your account". A few things push them over the edge:
- Link domains that don't match the sender. From
example.combut the button goes toclick.someesp.net/ls/...or a URL shortener. Use your ESP's branded link domain, or turn off click tracking for transactional mail. You don't need click stats on a password reset. - HTML-only email. Always send a plain-text part as well.
- An image instead of text. The code as an image, or a whole email that's one image, is a classic spam pattern.
- A subject that says nothing. "Your Example code is 482913" is better than "Action required!!".
- A
no-reply@that bounces. Users who reply to ask for help get a bounce; that's not a spam signal directly, but a monitored reply address costs nothing.
5. It never arrived at all (not even spam)
If it's not in spam either, it was probably rejected or delayed before the inbox:
- Check your ESP's logs for that recipient. You'll see
bounced,deferredordropped, usually with the receiving server's reason (e.g.550 5.7.26 unauthenticated email, which points back to step 1). - Greylisting delays the first message from a new sender by a few minutes. Your code may expire first. Make codes valid for at least 10 minutes and let users resend.
- Corporate filters (Microsoft 365, Mimecast, Proofpoint) sometimes quarantine mail the user never sees. Their IT admin can find it; the user can't.
- The user typed the address wrong. Show the address on the "check your email" screen with an "edit" link. It solves a surprising number of tickets.
A quick test before you ship a change
Whenever you change ESPs, DNS or templates:
- Send a real verification email to a Gmail and an Outlook.com address you control.
- Open Show original and check that SPF, DKIM and DMARC all say
PASSand that DKIM's domain is yours. - Run your domain's records through a checker. I use the free SPF, DKIM and DMARC checkers on FreeDomainMail (disclosure: I built that site), but any DNS checker or plain
digworks. - Start DMARC with
p=noneplus a reporting address, read the aggregate reports for a week or two, and only then move toquarantineorreject.
Summary
| Symptom in headers | Likely cause | Fix |
|---|---|---|
spf=fail / permerror | missing include, two SPF records, >10 lookups | one SPF record listing every sender |
dkim=none or fail | DKIM not enabled or key truncated | publish the ESP's DKIM records, verify with dig |
SPF + DKIM pass, dmarc=fail | alignment: signed by the ESP's domain | custom-domain DKIM, custom return-path |
| all pass, still spam | reputation or content | subdomain for transactional mail, no tracking links, Postmaster Tools |
| not in spam either | bounced, deferred, quarantined | ESP logs, longer code expiry, show the address |
Read the headers first. Nine times out of ten they tell you exactly which row you're in.
