About

Imported from terminalskills/skills (skills/email-deliverability-debugger/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill email-deliverability-debugger. Copyright stays with the author (Apache-2.0).

Email Deliverability Debugger

Name: email-deliverability-debugger
Author: terminalskills

Overview

This skill systematically diagnoses why emails fail to reach inboxes by checking the entire delivery chain: DNS authentication (SPF, DKIM, DMARC), sending IP reputation, email content, headers, and provider-specific configuration. It produces actionable fixes ranked by impact.

Instructions

Step 1: Check DNS Authentication Records

# SPF record
dig +short TXT example.com | grep "v=spf1"

# DKIM (check common selectors)
for sel in s1 s2 k1 google default sendgrid; do
  dig +short TXT ${sel}._domainkey.example.com
done

# DMARC
dig +short TXT _dmarc.example.com

Validate each:

SPF: Must include all sending services, ≤10 DNS lookups, end with -all (hardfail)
DKIM: Each sending service needs its own selector with valid key
DMARC: Should have p=quarantine or p=reject; p=none provides no protection

Step 2: Count SPF Lookups

SPF has a hard limit of 10 DNS lookups. Count each include:, a:, mx:, and redirect= as 1 lookup. Nested includes count too.

# Check SPF record and count includes
dig +short TXT example.com | grep spf
# Then recursively check each include
dig +short TXT _spf.google.com
dig +short TXT sendgrid.net

If at or near 10, recommend SPF flattening or removing unused services.

Step 3: Analyze Email Headers (if provided)

Key headers to check:

Authentication-Results: Shows SPF, DKIM, DMARC pass/fail
X-MS-Exchange-Organization-SCL: Microsoft spam confidence (0-9, >5 = spam)
X-Spam-Score: Generic spam score
Received-SPF: SPF result with detail
DKIM-Signature: Which domain signed and which selector used
Return-Path: Must align with From domain for SPF alignment

Step 4: Check IP Reputation

Query major blacklists:

# Reverse IP for DNSBL queries (e.g., 1.2.3.4 becomes 4.3.2.1)
REVERSED="4.3.2.1"
for bl in zen.spamhaus.org b.barracudacentral.org bl.spamcop.net; do
  dig +short ${REVERSED}.${bl}
done
# Non-empty result = listed on that blacklist

Common blacklists to check: Spamhaus, Barracuda, SpamCop, SORBS, CBL, URIBL.

Step 5: Check Content Issues

Flag common spam triggers:

Subject line with ALL CAPS or excessive punctuation (!!!)
HTML-only email without text/plain alternative
High image-to-text ratio
URL shorteners (bit.ly, etc.) in email body
Missing unsubscribe header (required for bulk, good practice for all)
Missing List-Unsubscribe header

Step 6: Produce Fix Report

Organize by priority:

Critical: Authentication failures (SPF/DKIM/DMARC fail)
High: IP blacklisting
Medium: Content issues, missing headers
Low: Best practice improvements

Include exact DNS records to add/modify and provider-specific configuration steps.

Examples

Example 1: Full Deliverability Audit

User prompt:

Our emails to Gmail users are going to spam. Domain: notifications.myapp.com

Agent output:

Deliverability Audit — notifications.myapp.com

❌ CRITICAL: DMARC alignment failure
   From: notifications.myapp.com
   Return-Path: bounces.sendgrid.net (different domain)
   → SPF passes for sendgrid.net but doesn't align with From domain
   Fix: Configure SendGrid authenticated domain so Return-Path uses your domain

⚠  HIGH: DMARC policy too weak
   Current: v=DMARC1; p=none
   → Gmail honors DMARC but p=none means failures aren't acted on
   Fix: v=DMARC1; p=quarantine; rua=mailto:dmarc@myapp.com; pct=100

✅ SPF: Valid (7 lookups)
✅ DKIM: Valid (s1 selector, 2048-bit)
✅ IP reputation: Clean on all major blacklists

Priority fix order:
1. Configure SendGrid domain authentication (fixes Return-Path alignment)
2. Update DMARC to p=quarantine
3. Monitor DMARC reports for 2 weeks before moving to p=reject

Example 2: Specific Bounce Diagnosis

User prompt:

Getting 550 5.7.1 rejections from outlook.com. What's wrong?

Agent output:

550 5.7.1 from Outlook = message rejected due to content or policy

Diagnosis checklist:
1. ✅ SPF passes for your domain
2. ❌ DKIM signature uses d=sendgrid.net, not your domain
   → Microsoft strict mode rejects misaligned DKIM
3. ❌ Your sending IP 149.72.x.x is on Spamhaus PBL
   → This is a policy listing, not spam — means IP is flagged as dynamic/cloud

Fixes:
1. Set up DKIM custom domain in SendGrid (Settings → Sender Authentication)
   Add CNAMEs: s1._domainkey.yourdomain.com → s1.domainkey.u1234.wl.sendgrid.net
2. Request Spamhaus PBL removal at spamhaus.org/pbl/query/
3. After fixes, use mail-tester.com to verify score >8/10 before bulk sending

Guidelines

Check authentication FIRST — 80% of deliverability issues are DNS authentication failures
Alignment matters more than pass/fail — SPF can pass but still fail DMARC if domains don't align
Separate transactional from marketing — different subdomains and IPs protect transactional reputation
DMARC reports are gold — always recommend setting up rua aggregate reports
Don't recommend p=reject immediately — go none → quarantine → reject over 4-6 weeks while monitoring
IP reputation recovers slowly — blacklist removal is quick, but reputation rebuilding takes 2-4 weeks of clean sending
Test with real recipients — mail-tester.com, Gmail postmaster tools, and Microsoft SNDS are free and essential

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/terminalskills-skills-email-deliverability-debugger/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

terminalskills-skills-email-deliverability-debugger.ocm.jsonjson

{
  "ocm": "1",
  "id": "terminalskills-skills-email-deliverability-debugger",
  "kind": "skill",
  "name": "email-deliverability-debugger",
  "description": "Diagnoses email deliverability problems for transactional and marketing emails. Checks SPF/DKIM/DMARC alignment, sending IP reputation, email content spam triggers, and bounce patterns. Use when emails land in spam, go missing, or bounce unexpectedly. Trigger words: email spam, deliverability, emails not arriving, bounce rate, spam folder, email reputation, SPF fail, DKIM fail, DMARC, transactional email, SendGrid, Postmark, SES.",
  "publisher": "terminalskills",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "email",
      "deliverability",
      "spam",
      "authentication",
      "dns",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Diagnoses email deliverability problems for transactional and marketing emails. Checks SPF/DKIM/DMARC alignment, sending IP reputation, email content spam triggers, and bounce patterns. Use when emails land in spam, go missing, or bounce unexpectedly. Trigger words: email spam, deliverability, emails not arriving, bounce rate, spam folder, email reputation, SPF fail, DKIM fail, DMARC, transactional email, SendGrid, Postmark, SES."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/terminalskills/skills",
      "path": "skills/email-deliverability-debugger/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/terminalskills/skills/blob/HEAD/skills/email-deliverability-debugger/SKILL.md",
      "key": "terminalskills/skills/skills/email-deliverability-debugger/SKILL.md"
    },
    "compatibility": "Requires dig/nslookup for DNS checks; works with any email provider",
    "license": "Apache-2.0"
  },
  "instructions": "# Email Deliverability Debugger\n\n## Overview\n\nThis skill systematically diagnoses why emails fail to reach inboxes by checking the entire delivery chain: DNS authentication (SPF, DKIM, DMARC), sending IP reputation, email content, headers, and provider-specific configuration. It produces actionable fixes ranked by impact.\n\n## Instructions\n\n### Step 1: Check DNS Authentication Records\n\n```bash\n# SPF record\ndig +short TXT example.com | grep \"v=spf1\"\n\n# DKIM (check common selectors)\nfor sel in s1 s2 k1 google default sendgrid; do\n  dig +short TXT ${sel}._domainkey.example.com\ndone\n\n# DMARC\ndig +s",
  "cost": {
    "context_tokens": 1340
  }
}

Fetch it by URL: GET /api/v1/registry/terminalskills-skills-email-deliverability-debugger/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.