email-deliverability

# 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 | ```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. 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. ```text 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. ```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 |