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.

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

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

Anti-patterns