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:

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 returns permerror, which counts as a failure.
  • Two SPF records. A domain must have exactly one v=spf1 TXT 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 dig and 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.com but the button goes to click.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, deferred or dropped, 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:

  1. Send a real verification email to a Gmail and an Outlook.com address you control.
  2. Open Show original and check that SPF, DKIM and DMARC all say PASS and that DKIM's domain is yours.
  3. 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 dig works.
  4. Start DMARC with p=none plus a reporting address, read the aggregate reports for a week or two, and only then move to quarantine or reject.

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.