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-privacy and data-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

; 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.

1. SPF + DKIM both set, and DMARC present at minimum p=none. At least one of SPF/DKIM must align with From:.
2. One-click unsubscribe (List-Unsubscribe + List-Unsubscribe-Post) on marketing/promotional mail, honored within 2 days. Transactional mail (password reset, receipt, shipping) is exempt.
3. 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.

List-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.

; 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