email-deliverability
Installation
SKILL.md
Run this when email performance breaks, or before it gets the chance to. It produces either a severity-ranked audit of the sending setup or a root-cause diagnosis with a dated recovery plan.
The play
- Pick the mode. Proactive review → audit the setup top to bottom. Active fire ("we're in spam") → diagnose.
- Scope first. Pull send volume, open rates by mailbox provider, shared vs dedicated IPs, and what changed right before the drop. An open rate below 10% at any provider confirms a deliverability problem, whatever anyone thinks of open tracking accuracy.
- Walk the four pillars, in order:
- Infrastructure. SPF, DKIM, DMARC present and verified recently — whole zone files disappear during migrations. The server's HELO announcement must match the IP's reverse DNS; a mismatch is an automatic blocklisting.
- Data. Hard bounces above 0.5% mean stop and clean. Soft bounces above 2% mean investigate before removing anything: Microsoft graylists legitimate senders heavily and ProofPoint soft-bounces on send rate, so both inflate the number with no list-quality problem behind it. Retry soft bounces three times across 72 hours, then treat what still fails as hard. After an ESP migration, check whether old bounces were accidentally re-imported.
- Content. Ask: how is this email distinguishable from a scam? Missing branding, HTML-only sends, bloated code, and mismatched sender identity all read as scam patterns to filters.
- Traffic shape. The big one — solving it at the pipe solves most of the problem. Throttle per provider, never raise volume more than 50% week over week, and spread large sends across 3-4 days.
- Classify and prescribe. Blocklisted → delist, but fix the root cause first or the listing comes back. Content filtered → pause that provider for 24-48 hours, fix, retest on an engaged segment. Broken authentication → fix DNS, wait for propagation before resuming. New or damaged sender → run the ramp in references/warmup-playbook.md.
- Define monitoring. Set thresholds that trigger a pause, not a postmortem: bounce spikes, complaint rate above 0.3%, one provider dropping while the others hold.
When the work goes deep, read references/warmup-playbook.md (week-by-week recovery ramp with per-provider volumes), references/shared-pool-management.md (pool contamination, compliance rails, high-risk verticals), and references/provider-specific-tactics.md (Gmail, Microsoft, Yahoo, iCloud, ProofPoint).