Email Diagnostics

Email Diagnostics

The starting point for any email problem or project. This skill routes you to the right diagnostic steps and the right specialized skills - so you fix the actual cause, not the symptom you noticed first.

When to use this skill

• Something is wrong with your email and you don't know where to start
• Emails are landing in spam
• Bounce rate or complaint rate is climbing
• You got listed on a blocklist
• Open rates are dropping
• Provider is throttling or deferring your sends (421 errors)
• You need to set up email infrastructure from scratch
• You're migrating between email providers
• You need to scale sending volume
• An AI agent is sending email and something's going wrong
• You need to choose between a traditional ESP and an agent-native inbox provider
• You need to handle inbound email for the first time
• You received a compliance complaint or data deletion request
• You want to audit your current email health

Related skills

This skill references all other skills in this collection. Each diagnostic path tells you exactly which skills to load for the detailed guidance.

Quick routing: find your situation

Emails landing in spam

The most common email problem. Work through these checks in order - each step is cheaper than the next, and most problems are caught in the first three.

Step 1: Check authentication (5 minutes)

Run these DNS checks against your sending domain:

dig TXT example.com           # SPF record
dig TXT sel._domainkey.example.com  # DKIM (replace sel with your selector)
dig TXT _dmarc.example.com    # DMARC record

Send a test email and check the headers for:

• spf=pass
• dkim=pass
• dmarc=pass

If anything fails, stop here. Load domain-authentication and fix it before investigating further. Authentication failures cause immediate spam placement or rejection at most providers since November 2025.

Step 2: Check reputation (10 minutes)

Check these in order:

1. Google Postmaster Tools - look at domain reputation and spam rate. If spam rate is above 0.10%, that's the problem. Above 0.30% is critical.
2. Blocklists - check Spamhaus (SBL, DBL, XBL), Barracuda, SpamCop at MXToolbox. If listed, jump to Blocklist response.
3. Microsoft SNDS - check IP reputation. Red status = stop sending and investigate.

If reputation is damaged, load sender-reputation for the recovery playbook.

Step 3: Check content (10 minutes)

Content is only ~10% of the placement decision, but it can be the tipping point:

1. Image-only email? Single image with no text is the strongest content-based spam signal. Add real text content.
2. URL shorteners? bit.ly and tinyurl get 2-4 SpamAssassin points. Use full URLs or a branded short domain.
3. Spam phrases? Check for "Act now", "Free", "Click here", "Guaranteed" - especially in subject lines.
4. HTML quality? Broken tags, JavaScript, embedded forms, missing DOCTYPE all correlate with spam placement.
5. Link count? More than 7 links with minimal text looks like phishing.

Load spam-filter-avoidance for the full content checklist.

Step 4: Check engagement (ongoing)

If authentication, reputation, and content all look clean, the problem is almost certainly engagement:

• Are you sending to people who haven't opened in 90+ days? Stop.
• Is your list purchased or scraped? You're hitting spam traps.
• Are you sending the same content to everyone regardless of engagement? Segment.

Load inbox-placement for the engagement signal hierarchy and fatigue scoring model. Load suppression-lists for list hygiene.

Skill loading order for spam problems

1. domain-authentication - fix any auth failures first
2. sender-reputation - if reputation is damaged
3. spam-filter-avoidance - if content triggers are present
4. inbox-placement - for engagement optimization
5. suppression-lists - for list hygiene
6. email-warmup - if you need to rebuild after fixing root cause

Bounce rate spiking

Healthy bounce rate is under 1%. Warning at 1-2%. Above 2% is dangerous - providers will throttle or block you.

Classify the bounces first

The fix depends entirely on whether they're hard or soft:

Hard bounce spike diagnostic

If hard bounces are climbing:

1. Did you import a new list? Purchased/scraped lists are the #1 cause. Validate the list with a verification service before any more sends.
2. Did you email a stale segment? Addresses go bad over time. If you haven't sent to a segment in 6+ months, verify first.
3. Is one recipient domain bouncing everything? Check per-domain bounce rates. A single domain problem needs domain-level suppression, not panic.
4. Are you generating addresses programmatically? AI agents guessing contact@company.com produce bounces that count against you.

Soft bounce spike diagnostic

If soft bounces are piling up:

1. Are you seeing 421 codes? Jump to Getting throttled.
2. Is it one provider? Gmail, Microsoft, and Yahoo throttle independently. A spike at one provider while others are fine usually means reputation damage with that specific provider.
3. Did your volume spike suddenly? More than 2x your normal daily volume triggers defensive filtering at most providers.

Load bounce-handling for SMTP code reference, retry strategies, and provider-specific webhook formats. Load suppression-lists for automated suppression workflows.

Blocklist listing

A Spamhaus SBL listing can drop delivery rates by 90% within hours. This is an emergency.

Immediate response (first hour)

1. Identify which list. Check Spamhaus, Barracuda, SpamCop, SORBS at MXToolbox.
2. Stop non-essential sending. Keep transactional email (password resets, order confirmations) flowing if possible, but pause all marketing and outreach.
3. Find the cause. Common triggers: sending to spam traps (list quality), complaint spike, compromised account sending spam, open relay.
4. Fix the root cause before requesting removal. Requesting delisting without fixing the problem gets you re-listed faster and makes future removals harder.

Delisting process

After delisting

You need to re-warm. Your reputation took a hit and sending at full volume immediately will put you right back.

1. Load sender-reputation for the recovery playbook (timeline: 2-12+ weeks depending on damage).
2. Load email-warmup - start at 25% of normal volume with your most engaged segment.
3. Load sender-monitoring - set up alerts so you catch the next problem before it becomes a blocklist event.

Open rates dropping

Declining open rates over 2+ weeks usually means placement is degrading. This is the slow-motion version of going to spam - your emails are being deprioritized, not outright filtered.

Quick checks

1. Is it one provider or all of them? Check per-provider breakdown (Gmail vs Microsoft vs Yahoo). If it's one provider, the problem is usually reputation with that specific provider.
2. Apple Mail Privacy Protection. iOS 15+ auto-loads tracking pixels, inflating open rates. If your audience is consumer-heavy, apparent "drops" might be a shift in audience composition, not real. Weight click rates more heavily.
3. Check Google Postmaster Tools. Is your domain reputation declining? Is spam rate creeping up?
4. Did something change? New template, new content strategy, new sending frequency, new list segment. Roll back the change and see if rates recover.

Common causes and fixes

Getting throttled

421 SMTP responses mean the receiving provider is telling you to slow down. Retrying at the same rate makes it worse.

Identify the throttle type

Fix

1. Back off immediately. Exponential backoff: 2 min, 4 min, 8 min, 16 min, max 1 hour.
2. Check your per-domain send rate. Conservative default: 50-100 messages/hour to any single recipient domain. If you're above this, add per-domain throttling.
3. Check volume patterns. Did you send your entire daily allocation in 10 minutes? Spread sends evenly across the day.
4. Is this a warmup issue? New domains and IPs without warmup get throttled aggressively. Load email-warmup.

Load rate-limiting for multi-window rate limit implementation and per-domain throttling. Load bounce-handling for soft bounce retry strategies.

Complaint rate rising

Google enforces 0.3% as a hard limit. Above 0.1% is already a warning. Complaints are the single most damaging signal to your reputation.

Immediate actions

1. Check which emails are generating complaints. Most ESPs show complaint source by campaign or template.
2. Is your unsubscribe link working? Broken or hidden unsubscribe links force people to use the spam button. Test it.
3. Are List-Unsubscribe headers present? Required since June 2024 for Gmail/Yahoo, May 2025 for Microsoft. Missing headers mean the only "unsubscribe" option recipients see is the spam button.
4. Did you recently change frequency? Going from weekly to daily without recipient opt-in causes complaint spikes.
5. Did you add a new segment? Emailing people who didn't expect to hear from you is the top complaint driver.

Structural fixes

• Load email-compliance for unsubscribe requirements (RFC 8058, one-click) and consent management.
• Load suppression-lists for automated complaint suppression (suppress immediately on complaint, permanently).
• Load notification-design if the problem is frequency-related - implement preference centers and digests.

Setting up email from scratch

The correct sequence matters. Skipping steps or doing them out of order creates problems that are expensive to fix later.

If you're building for an AI agent that needs to send and receive autonomously, consider an agent-native inbox provider instead of wiring up a traditional ESP. Load inbox-providers for the comparison. If you go the agent-native route, the provider handles most of phases 1-2 below. If you're building on a traditional ESP, follow the full sequence.

Phase 1: Infrastructure (week 1)

1. Choose a sending subdomain. Never send from your root domain. Use mail.example.com for transactional, news.example.com for marketing. Load provider-setup for the full decision framework.
2. Set up authentication. SPF, DKIM, and DMARC on every sending subdomain. Start with p=none on DMARC. Load domain-authentication.
3. Choose a provider. Decision depends on volume, use case, and whether you need dedicated IPs. Load provider-setup.
4. Configure webhooks. You need bounce, complaint, and delivery event processing from day one. Load webhook-processing.

Phase 2: Warmup (weeks 2-5)

5. Warm your domain. Start at 50/day, ramp gradually, never more than 2x day-over-day. Send to your most engaged recipients first. Load email-warmup.
6. Set up monitoring. Google Postmaster Tools, Microsoft SNDS, blocklist checks. Set alert thresholds. Load sender-monitoring.
7. Implement rate limiting. Multi-window (hourly, daily, monthly). Per-domain throttling. Load rate-limiting.

Phase 3: Sending (weeks 3+, overlapping with warmup)

8. Build suppression infrastructure. Hard bounce suppression, complaint suppression, unsubscribe handling. Load suppression-lists.
9. Set up compliance. CAN-SPAM, GDPR, or CASL depending on your audience's jurisdiction. Consent collection and records. Load email-compliance.
10. Build your first email flow. Which skill to load depends on your use case:

11. Write the content. Load email-copywriting for copy and template-design for HTML.

Phase 4: Optimize (ongoing)

12. Test and iterate. Load ab-testing once you have enough volume (minimum 200-300 sends per variant for meaningful results).
13. Monitor continuously. Weekly review of metrics, monthly review of list health, quarterly holdout tests.

Migrating email providers

Provider migrations are where most reputation damage happens - because people forget to carry their suppression lists.

Pre-migration (1-2 weeks before)

1. Export your suppression list from the old provider. This is the most critical step. Hard bounces, complaints, unsubscribes - all of them. Load suppression-lists.
2. Set up the new provider. DNS records (SPF include swap, new DKIM selector), webhook endpoints, API keys. Load provider-setup.
3. Import suppressions into the new provider. Verify with spot-checks on specific addresses.
4. Test end-to-end. Send test messages through the new provider, verify authentication headers pass.

Cutover (2-4 weeks)

5. Warm the new provider. Even with an established domain, a new provider relationship needs warming. Start at 5-10% of volume, send to engaged recipients first. Load email-warmup.
6. Gradual ramp. 25% -> 50% -> 75% -> 100%. Monitor bounce and complaint rates at each step. Hold at each level for 2-3 days minimum.
7. Keep old provider as failover. Don't decommission until new provider is at 100% for at least 2 weeks with clean metrics.

Post-migration

8. Remove old SPF include after 30 days at full volume on the new provider.
9. Monitor closely for 4 weeks. Load sender-monitoring.

Scaling send volume

Scaling too fast damages reputation. Scaling too slowly costs opportunity. Here's how to do it right.

Determine your current position

Rules for scaling

• Never increase more than 30-50% per week.
• Send new volume to your most engaged recipients first.
• Monitor complaint rate (stay under 0.1%) and bounce rate (stay under 1%) at each step.
• If either metric crosses the warning threshold, hold volume for an extra week before increasing.

When you need dedicated IPs

If your consistent volume will exceed 50K/month, load provider-setup for the shared vs dedicated IP decision. Below 50K/month, dedicated IPs are counterproductive - low volume makes them look suspicious.

Infrastructure to have in place before scaling

• Multi-window rate limiting (rate-limiting)
• Automated bounce/complaint suppression (suppression-lists, bounce-handling)
• Per-domain throttling (rate-limiting)
• Monitoring and alerts (sender-monitoring)
• Separate mail streams for transactional vs marketing (provider-setup)

Setting up inbound email

Receiving and processing email is a different problem from sending. Here's the setup sequence.

Step 1: Choose inbound method

Load inbound-processing for provider setup, MIME parsing, and content extraction.

Step 2: Build classification

Once you can receive and parse email, you need to classify it:

1. Auto-reply/OOO detection - check headers first (Auto-Submitted, Precedence). This catches 20-40% of inbound with near-perfect accuracy.
2. Bounce detection - DSN messages (Content-Type: multipart/report).
3. Intent classification - interested, not_now, objection, support, billing, unsubscribe.

Load reply-classification for the full taxonomy, keyword scoring, confidence thresholds, and routing rules.

Step 3: Thread management

Link inbound messages to conversations:

1. Store outbound Message-IDs at send time.
2. Match inbound In-Reply-To headers against stored IDs.
3. Strip quoted reply content to extract only the new text.
4. Detect thread anomalies (new sender in existing thread, intent flips).

Load thread-management for threading headers, provider differences (Gmail vs Outlook), and quoted reply stripping.

Step 4: Security

Inbound email is an attack vector. Before any AI agent processes email content:

1. Sanitize HTML (allowlist, not blocklist).
2. Strip invisible Unicode characters.
3. Detect prompt injection patterns.
4. Validate URLs before following them.

Load email-security for the full security pipeline including prompt injection detection, BEC patterns, and attachment scanning.

Giving an AI agent its own inbox

If your AI agent needs to send and receive email autonomously, you have two paths: build on a traditional ESP or use an agent-native inbox provider.

Traditional ESP vs agent-native inbox provider

Use a traditional ESP if your agent only sends occasional transactional email, you already have email infrastructure, or volume is under 100 emails/day. Load provider-setup.

Use an agent-native inbox provider if your agent sends at scale, handles replies, or operates autonomously. The build-vs-buy calculation tips toward agent-native providers quickly when you factor in suppression, rate limiting, deduplication, and safety scanning. Load inbox-providers.

Quick decision

Load inbox-providers for full provider comparison, setup steps, and safety architecture.

AI agent email problems

AI agents have specific failure modes that humans don't. If an agent is sending email and something's going wrong, check these first.

Common agent failures

Agent-specific guardrails

If you're building these yourself on a traditional ESP, you need all of the following. Agent-native inbox providers (load inbox-providers) handle most of this at the infrastructure layer.

1. Rate limits at infrastructure layer, not application. Agents will find ways around application-level limits.
2. Per-recipient cooldowns. 10-minute minimum between emails to the same recipient per template.
3. Negative signal budgets. Auto-pause sending when bounce rate exceeds 3% or complaint rate exceeds 0.1%.
4. Fatigue scoring. Score above 70 = stop sending, 40-70 = reduce frequency, below 40 = safe. Load sender-reputation for the scoring model.
5. Start on an established domain. Don't put an agent on a brand-new domain. Warm with human-reviewed sends first, then hand over to the agent.

Compliance request or legal complaint

Legal email compliance spans three jurisdictions with different rules. Getting it wrong has real penalties.

Unsubscribe request

• Honor immediately. CAN-SPAM allows 10 business days, but Google/Yahoo require functional one-click unsubscribe, and best practice is seconds.
• Suppress the address - don't just remove from list. Removing allows re-addition. Suppressing prevents it.
• Don't send a "sorry to see you go" email. That's another email they didn't ask for.
• Load email-compliance and suppression-lists.

GDPR erasure request (right to be forgotten)

This creates a paradox: you must delete personal data, but you must also prevent future sending. The solution:

Keep: email address, suppression flag, reason code (legal_request), date, jurisdiction. Delete: name, company, demographics, send history, engagement data, CRM fields, consent records beyond what's needed for suppression.

Load suppression-lists for the full GDPR erasure workflow.

CAN-SPAM complaint

• Penalty: up to $51,744 per email.
• Check: accurate From address, honest subject line, physical postal address present, working unsubscribe mechanism, opt-outs honored within 10 days.
• Load email-compliance.

CASL complaint (Canada)

• Penalty: up to $10 million per violation.
• Check: did you have express or implied consent? Implied consent expires (purchase: 2 years, inquiry: 6 months). Were consent records retained (3-year requirement)?
• Load email-compliance.

The 5-minute health check

Run this periodically, or any time you want a quick snapshot of your email health. Each check takes under a minute.

1. Authentication (pass/fail)

Send a test email to yourself. Check headers for:

• spf=pass with alignment
• dkim=pass with alignment
• dmarc=pass

If anything fails, load domain-authentication.

2. Reputation (check three sources)

• Google Postmaster Tools: spam rate under 0.10%? Domain reputation Medium or High?
• MXToolbox blocklist check: listed on any blocklist?
• Microsoft SNDS: IP reputation green?

If reputation is degraded, load sender-reputation.

3. Bounce and complaint rates (check your ESP dashboard)

If any metric is in the "investigate" column, load sender-monitoring for alert configuration and bounce-handling or suppression-lists for the fix.

4. List hygiene (quick check)

• When did you last clean your list? If more than 3 months ago, verify before your next send.
• What percentage of your list has engaged (opened or clicked) in the last 90 days? If under 30%, you're carrying too much dead weight.

5. Compliance (quick check)

• Is there a working unsubscribe link in every marketing email?
• Are List-Unsubscribe and List-Unsubscribe-Post headers present?
• Is a physical postal address included (CAN-SPAM)?
• Are you tracking consent with timestamps and source?

If anything is missing, load email-compliance.

The diagnostic decision tree

When you're not sure where to start, walk this tree:

Is authentication passing? (SPF, DKIM, DMARC all pass)
  NO  --> Fix authentication first (domain-authentication)
  YES
    |
    v
Is your domain on any blocklist?
  YES --> Emergency: stop marketing sends, fix cause, request delisting
         (sender-reputation, sender-monitoring)
  NO
    |
    v
Is complaint rate above 0.1%?
  YES --> Fix unsubscribe flow, check consent, reduce frequency
         (email-compliance, suppression-lists, notification-design)
  NO
    |
    v
Is bounce rate above 2%?
  YES --> Classify hard vs soft, clean list, check for bad segments
         (bounce-handling, suppression-lists)
  NO
    |
    v
Is delivery rate below 95%?
  YES --> Check per-provider breakdown, look for throttling
         (sender-monitoring, rate-limiting)
  NO
    |
    v
Are open rates declining?
  YES --> Check engagement segments, content quality, tab placement
         (inbox-placement, email-copywriting, ab-testing)
  NO
    |
    v
Your email health looks good. Focus on optimization:
  - Test subject lines and content (ab-testing)
  - Optimize send timing (email-sequences)
  - Improve templates (template-design)
  - Build preference centers (notification-design)

Skill map: when to load what

Quick reference for all 26 skills organized by the problem you're solving.

Something is broken

Building something new

Common mistakes

1. Fixing content when the problem is reputation. Content is ~10% of the placement decision. If your reputation is bad, perfect content won't save you. Check authentication and reputation before touching copy.
2. Treating symptoms instead of causes. Open rates dropping is a symptom. The cause might be reputation, engagement, content, or tab placement. Diagnose before you treat.
3. No monitoring until something breaks. Set up Google Postmaster Tools, Microsoft SNDS, and blocklist monitoring before you need them. The time to build dashboards is not during an incident.
4. Skipping suppression list export during migration. This is the single most common cause of reputation damage during provider migrations. Hard bounces and complaints from your old provider don't automatically transfer.
5. Scaling volume without warming. Whether it's a new domain, new IP, new provider, or resuming after inactivity - you need to ramp gradually. More than 2x day-over-day increase triggers defensive filtering.
6. Separate mail streams? What's that? Mixing transactional and marketing on the same domain/IP means a bad marketing campaign can block your password reset emails. Use different subdomains at minimum.
7. Ignoring the agent-specific failure modes. AI agents don't get tired, don't notice patterns, and will happily retry 200 times in an hour. Infrastructure-level rate limits and negative signal budgets are not optional.
8. Treating the diagnostic tree as linear. Email problems are usually multi-causal. A bounce spike might be caused by a stale list (list hygiene) triggered by a new campaign (content) sent too fast (rate limiting) on a domain that wasn't warmed (warmup). Fix all the causes, not just the first one you find.

References

• Google Postmaster Tools
• Microsoft SNDS
• Yahoo Sender Hub
• Spamhaus Blocklist Lookup
• MXToolbox Blocklist Check
• M3AAWG Best Practices
• Google Bulk Sender Guidelines
• RFC 7208 - SPF
• RFC 6376 - DKIM
• RFC 7489 - DMARC
• RFC 8058 - One-Click Unsubscribe
• molted.email - email infrastructure with policy enforcement, deliverability protection, and inbound classification built in