# Email Deliverability Troubleshooting

> Use when performing email deliverability troubleshooting — email delivery issues investigation workflow covering bounce analysis, spam filter diagnosis, SPF/DKIM/DMARC validation, mail flow tracing, and mailbox quota management. Guides helpdesk agents through systematic diagnosis of email delivery failures for both sending and receiving issues.

- Skill: `cloudthinker-ai/email-deliverability-troubleshooting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cloudthinker-ai/email-deliverability-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cloudthinker-ai/email-deliverability-troubleshooting/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: cloudthinker-ai (https://skillmd.com/u/cloudthinker-ai)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/cloudthinker-ai/email-deliverability-troubleshooting

---


# Email Deliverability Troubleshooting

Investigating email issue for **{{ user_name }}**
Direction: **{{ email_direction }}** | Platform: {{ email_platform }}
Other party: {{ recipient_or_sender }}

## Decision Tree

```
START: What is the email issue?
│
├─ Emails Not Being SENT
│  ├─ Bounce-back / NDR received?
│  │  ├─ Yes → Analyze NDR error code (see below)
│  │  └─ No → Check outbox, stuck in queue?
│  ├─ Sending to all recipients or specific ones?
│  │  ├─ All → Account or server issue
│  │  └─ Specific → Recipient-side issue
│  └─ Attachment issues?
│     └─ Check size limits (typically 25-35MB)
│
├─ Emails Not Being RECEIVED
│  ├─ From all senders or specific?
│  │  ├─ All → Mailbox or routing issue
│  │  └─ Specific → Spam filter or sender issue
│  ├─ Check spam/junk folder
│  ├─ Mailbox full?
│  └─ Mail flow rules blocking?
│
└─ Emails Delayed
   ├─ Internal or external?
   ├─ Check mail queue on server
   └─ DNS/MX record issues?
```

## Diagnostic Steps

### Step 1 — Basic Checks
- [ ] Verify {{ user_name }}'s mailbox is active and not over quota
- [ ] Check mailbox size: current usage vs limit
- [ ] Verify {{ user_name }} can log into webmail (rules out client-only issues)
- [ ] Check for any active mail flow rules / inbox rules that might redirect or delete emails

### Step 2 — Bounce / NDR Analysis

Common NDR codes and meanings:
| Code | Meaning | Action |
|------|---------|--------|
| 550 5.1.1 | Recipient does not exist | Verify recipient address spelling |
| 550 5.7.1 | Relay denied / not authorized | Check authentication, connector config |
| 552 5.2.2 | Mailbox full | Recipient needs to clear space |
| 554 5.7.1 | Message rejected (spam) | Check SPF/DKIM/DMARC, content filters |
| 421 4.7.0 | Temporary failure, try later | Server greylisting, retry automatically |
| 550 5.4.1 | Recipient domain not found | Verify domain exists, check MX records |

### Step 3 — DNS & Authentication Records
- [ ] Verify MX records point to correct mail servers
- [ ] Validate SPF record: `nslookup -type=txt domain.com` — look for `v=spf1`
- [ ] Validate DKIM: check selector records in DNS
- [ ] Validate DMARC: `nslookup -type=txt _dmarc.domain.com`
- [ ] If records are missing or incorrect, escalate to DNS administrator

### Step 4 — Message Trace
- [ ] Run message trace in {{ email_platform }} admin console
- [ ] Search by sender, recipient, date range, and message ID
- [ ] Check trace results for:
  - Delivery status (delivered, failed, pending, filtered)
  - Transport rules applied
  - Spam filter verdict and confidence level
  - Connector routing path

### Step 5 — Spam Filter Investigation
- [ ] Check if message was quarantined
- [ ] Review spam filter logs for the specific message
- [ ] If legitimate email was blocked:
  - Whitelist sender domain or address
  - Adjust spam filter sensitivity if false positives are frequent
  - Release message from quarantine
- [ ] If company emails are being marked as spam by recipients:
  - Verify SPF/DKIM/DMARC alignment
  - Check if company domain/IP is on any blacklists
  - Review email content for spam trigger words

## Escalation Criteria

Escalate to email/messaging team if:
- Mail server queue is backed up
- DNS record changes are needed
- Domain is blacklisted
- Transport rules need modification
- Multiple users affected simultaneously

## Counter-Rationalizations

| Shortcut | Counter | Why |
|----------|---------|-----|
| "We can skip some steps for this case" | Adapt the workflow steps, don't skip them | Skipped steps are where incidents and oversights originate |
| "The user seems to already know what to do" | Complete all workflow phases with the user | The workflow catches blind spots that experience alone misses |
| "This is a minor case, full process is overkill" | Scale the process down, don't turn it off | Minor cases become major when unstructured; the process scales, not disappears |
| "I'll fill in the details later" | Complete each section before moving on | Deferred details are forgotten; real-time capture is more accurate |
| "The template output isn't necessary" | Always produce the structured output format | Structured output enables comparison, audit trails, and handoff to other teams |

## Output Format

Generate a diagnostic report with:
1. **Issue summary** (user, direction, platform)
2. **Diagnostic findings** from each step
3. **Root cause** identified
4. **Resolution** applied or **escalation** with details