email-deliverability — make mail authenticate and land in the inbox
This skill owns one layer: why mail you already send gets filtered, deferred, or rejected, and the DNS + reputation work that fixes it. It starts where the send technically succeeds but the message never reaches the inbox.
The lever is almost never the sending code. It is three DNS records that must align, a complaint rate you must hold down, and a reputation you build slowly and lose fast. Treat this as ops on a domain, not a code change.
Not this skill
- Sending the mail at all — provider SDK,
sendEmail()seam, templates, retries, batch caps, bounce/complaint webhooks →../email-connector/SKILL.md. That skill feeds the suppression list; this one explains the reputation it protects. - Subject lines, open/click optimization, list growth →
newsletter. - Outbound prospecting sequences, lead lists →
cold-outreach(deliverability is a constraint on it, not the same job). - Consent, lawful basis, retention of the address list →
gdpr-privacyanddata-policy. Unsubscribe mechanics live here; consent law does not. - Handling the DKIM private key and provider API secrets →
../secure-coding/SKILL.md.
The three records that must align
SPF, DKIM, and DMARC are not three ways to do the same thing. DMARC is the
policy; it passes only when SPF or DKIM both authenticate and align with
the visible From: domain. Most "SPF is set but DMARC fails" tickets are an
alignment miss, not a missing record.
| Record | What it asserts | Common break |
|---|---|---|
| SPF (TXT) | This IP/host is allowed to send for the domain | Lists the provider but the Return-Path is a different domain → no alignment |
| DKIM (TXT) | This message body+headers are signed by a key the domain published | Provider signs with provider.net, not your domain → no alignment; or a deprecated 1024-bit key (publish 2048-bit, rotate periodically) |
DMARC (TXT at _dmarc) | What to do when neither aligns, plus where to send reports | Policy left at p=none forever; never tightened |
dns; DMARC — start at none to collect reports, then tighten to quarantine/reject. _dmarc.acme.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc@acme.com; fo=1"
Alignment rule, stated once: the domain in From: must match the domain SPF
authenticated (the Return-Path/envelope domain) or the domain in the DKIM
d= tag. Use a custom Return-Path and a domain-keyed DKIM selector through your
provider so at least one aligns. Verifying SPF alone passing is the classic
false comfort.
Gmail / Yahoo bulk-sender rules
If you send more than ~5,000 messages/day to Gmail or Yahoo accounts, these are enforced, not advisory. Enforcement ramped from late 2025; failures now draw temporary and permanent rejections, not silent spam-foldering.
- SPF + DKIM both set, and DMARC present at minimum
p=none. At least one of SPF/DKIM must align withFrom:. - One-click unsubscribe (
List-Unsubscribe+List-Unsubscribe-Post) on marketing/promotional mail, honored within 2 days. Transactional mail (password reset, receipt, shipping) is exempt. - Spam-complaint rate kept low. The hard threshold where filtering kicks in is 0.3% (Postmaster Tools); Google's reliable-inbox target is below 0.1%. Treat 0.3% as the cliff, 0.1% as the speed limit.
textList-Unsubscribe: <https://acme.com/u/abc123>, <mailto:unsub@acme.com?subject=unsub> List-Unsubscribe-Post: List-Unsubscribe=One-Click
BIMI — the verified logo, last
BIMI shows your brand logo (and on Gmail a blue verified checkmark) next to the message. It is the last step, never a fix for placement: it requires you have already passed DMARC at enforcement, and it changes how a delivered message looks, not whether it gets delivered.
Hard prerequisite: DMARC at p=quarantine or p=reject with pct=100. A record
left at p=none does not qualify — that is why "add BIMI to escape the spam
folder" is backwards; you cannot publish it until the auth work is done.
Whether the logo (and checkmark) actually render depends on the certificate:
| Approach | Cost / proof | Where it shows |
|---|---|---|
| Self-asserted (no certificate) | Free; logo only | Yahoo, Fastmail — not Gmail |
| CMC (Common Mark Certificate) | Cheaper; ~12 months of public logo use, no registered trademark | Gmail + the rest, with checkmark |
| VMC (Verified Mark Certificate) | ~$749–$1,500/yr; needs a registered (or government-modified) trademark | Gmail + the rest, with checkmark |
Active mark-certificate issuers in 2026: DigiCert, GlobalSign, SSL.com (Sectigo resells; Entrust exited mark certificates in 2025). The logo file must be SVG Tiny PS 1.2, square, with no scripts or external references.
dns; BIMI — only valid once DMARC is at quarantine/reject with pct=100. ; a= is the VMC/CMC PEM; omit it for a self-asserted (non-Gmail) logo. default._bimi.acme.com. IN TXT "v=BIMI1; l=https://acme.com/logo.svg; a=https://acme.com/vmc.pem"
Do BIMI only after weeks of clean, enforced DMARC. It amplifies a good reputation; it does not create one.
Warm a cold domain (decision flow)
A brand-new domain has zero reputation; blasting volume on day one looks exactly like a spammer. Warm only if the domain genuinely has no history.
- New domain, no send history → warm: start ~20-50/day to engaged recipients, roughly double every few days over 4-6 weeks, watch Postmaster reputation before each step up. Send your most-opened content first.
- Established domain, new provider/IP → warm the IP path, not the domain; migrate a slice of volume and ramp.
- Established domain, same IP, sudden spam folder → do NOT warm; this is a reputation or auth regression. Read the rejection code and Postmaster trend first (see the error table).
Skipping warmup to "just send the campaign" is the most common self-inflicted blacklisting. There is no fast path; reputation is earned by consistent, low-complaint sending.
Read the rejection, then act
| Signal | Likely cause | Fix |
|---|---|---|
550 5.7.26 | Message unauthenticated — SPF and DKIM both failed/missing | Publish SPF + DKIM through the provider; confirm at least one aligns |
dmarc=fail in headers, SPF=pass | Alignment miss: Return-Path ≠ From: domain | Set a custom Return-Path on your domain, or align the DKIM d= |
421/451 deferral, then later delivery | Receiver throttling an unwarmed/spiky sender | Slow the ramp; spread volume; warm the domain |
| Postmaster "Bad" domain reputation | Sustained complaints / spam-trap hits | Cut volume, prune unengaged, fix consent, hold under 0.1% complaints |
| Lands in Promotions (not Spam) | Not a failure — bulk/marketing classification | Leave it; do not chase the Primary tab by faking transactional headers |
Anti-patterns
| Anti-pattern | Why it breaks | Do instead |
|---|---|---|
| "SPF passes, so we're authenticated" | DMARC needs alignment; SPF on a mismatched Return-Path still fails DMARC | Verify DMARC result in headers, not SPF alone; align Return-Path or DKIM |
Leaving DMARC at p=none forever | Publishes intent to enforce nothing; spoofers and filters both notice | Collect rua reports, then move to quarantine then reject |
p=reject on day one with no report review | Silently drops your own legitimate sub-streams (CRM, support tools) | Stage none → quarantine → reject, reading reports at each step |
| Blasting full volume from a new domain | Looks like spam; gets throttled/blacklisted with no recovery for weeks | Warm: tiny start to engaged users, ramp over 4-6 weeks |
| Buying/scraping a list to hit volume | Spam traps + complaints spike past 0.3% → domain reputation tanks | Send only to opted-in, engaged recipients; prune the unengaged |
| Faking transactional headers to dodge Promotions | Violates bulk rules; risks rejection, not just foldering | Accept Promotions placement; earn Primary via engagement |
| Routing the unsubscribe to a form that takes a week | Breaks the 2-day one-click honor rule; raises complaints | Honor List-Unsubscribe-Post one-click within 2 days, automatically |
| Adding BIMI to fix spam-foldering | BIMI needs DMARC enforcement you do not have yet, and it changes logo display, not placement | Fix auth + reputation first; add BIMI last as a branding layer |
