Diagnose and fix email delivery problems including bounces, spam filtering, authentication failures, and blacklisting. Includes step-by-step troubleshooting workflows and common solutions.
By Inventive Software•
Email Delivery Troubleshooting Guide
Email delivery issues can range from simple configuration problems to complex reputation issues. This guide provides systematic troubleshooting workflows to diagnose and fix the most common email delivery problems.
┌─────────────────────────────────────────────────────────────────────────────┐
│ SPF TROUBLESHOOTING WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: Check Current SPF Record │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ $ dig +short TXT example.com | grep spf │ │
│ │ "v=spf1 include:_spf.google.com ~all" │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ STEP 2: Identify Sending IP │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Check email headers for "Received: from" - look for your server IP │ │
│ │ Or check Authentication-Results for smtp.mailfrom IP │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ STEP 3: Verify IP is Authorized │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Use SPF checker: mxtoolbox.com/spf.aspx │ │
│ │ Enter: example.com and sending IP │ │
│ │ │ │
│ │ Expected: PASS │ │
│ │ If FAIL: IP not authorized → Add to SPF record │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ COMMON SPF FIXES: │
│ │
│ Problem: IP not in SPF │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Before: v=spf1 include:_spf.google.com ~all │ │
│ │ After: v=spf1 ip4:203.0.113.10 include:_spf.google.com ~all │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ Problem: Missing include for email service │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Before: v=spf1 include:_spf.google.com ~all │ │
│ │ After: v=spf1 include:_spf.google.com include:sendgrid.net ~all │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ Problem: Too many DNS lookups (>10) │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Solutions: │ │
│ │ • Flatten SPF record (replace includes with IPs) │ │
│ │ • Use SPF macro syntax │ │
│ │ • Split across subdomains │ │
│ │ See: /blog/spf-10-dns-lookup-limit │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
DKIM Failures
# Check DKIM record exists
dig +short TXT selector._domainkey.example.com
# Common DKIM issues:
# 1. Selector not found
# Error: DKIM-Result: permerror (no key for signature)
# Fix: Verify selector name matches what's configured in mail server
# 2. Key mismatch
# Error: DKIM-Result: fail (signature verification failed)
# Fix: Regenerate key pair, update DNS with new public key
# 3. Body hash mismatch
# Error: DKIM-Result: fail (body hash did not verify)
# Fix: Check if email is being modified in transit (mailing lists, forwarding)
# 4. Signature expired
# Error: DKIM-Result: fail (signature is expired)
# Fix: Check server clock synchronization (NTP)
DMARC Failures
┌─────────────────────────────────────────────────────────────────────────────┐
│ DMARC TROUBLESHOOTING │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ DMARC requires: (SPF Pass + SPF Aligned) OR (DKIM Pass + DKIM Aligned) │
│ │
│ ALIGNMENT CHECK: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ From: [email protected] ← RFC5322.From (visible to user) │ │
│ │ │ │
│ │ SPF Alignment (aspf): │ │
│ │ Return-Path: [email protected] ← Must match From domain │ │
│ │ [email protected] ← Works with aspf=r (relaxed) │ │
│ │ [email protected] ← FAILS alignment │ │
│ │ │ │
│ │ DKIM Alignment (adkim): │ │
│ │ DKIM d=example.com ← Must match From domain │ │
│ │ d=mail.example.com ← Works with adkim=r (relaxed) │ │
│ │ d=different.com ← FAILS alignment │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ COMMON DMARC FIXES: │
│ │
│ Problem: Third-party sender not aligned │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ SendGrid sends with: │ │
│ │ Return-Path: [email protected] (SPF passes for sendgrid.net) │ │
│ │ DKIM d=sendgrid.net │ │
│ │ From: [email protected] │ │
│ │ │ │
│ │ DMARC fails because neither aligns with example.com! │ │
│ │ │ │
│ │ Fix: Configure custom domain for DKIM signing │ │
│ │ - In SendGrid, set up domain authentication for example.com │ │
│ │ - SendGrid will then sign with d=example.com → DKIM aligns │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ Problem: Forwarded email fails DMARC │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ When email is forwarded: │ │
│ │ - SPF fails (forwarding server IP not in sender's SPF) │ │
│ │ - DKIM may survive if message unchanged │ │
│ │ │ │
│ │ Solutions: │ │
│ │ - Rely on DKIM for alignment (ensure DKIM survives forwarding) │ │
│ │ - Use ARC (Authenticated Received Chain) if supported │ │
│ │ - Consider relaxed DMARC policy for mailing lists │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Blacklist Troubleshooting
Checking Blacklist Status
# Check multiple blacklists at once
# Option 1: MXToolbox
# Visit: https://mxtoolbox.com/blacklists.aspx
# Enter: Your sending IP or domain
# Option 2: Command line check
# Reverse the IP octets for DNSBL query
IP="203.0.113.10"
REVERSED=$(echo $IP | awk -F. '{print $4"."$3"."$2"."$1}')
# Query common blacklists
for BL in zen.spamhaus.org bl.spamcop.net b.barracudacentral.org; do
dig +short $REVERSED.$BL
done
# If returns an IP (like 127.0.0.2), you're listed
# Empty result = not listed
Common Blacklists and Delisting
Blacklist
Check URL
Delisting Process
Spamhaus
spamhaus.org/lookup
Submit removal request, fix issue
Barracuda
barracudacentral.org/lookups
Register, request removal
SpamCop
spamcop.net/bl.shtml
Usually auto-expires in 24h
SORBS
sorbs.net
Request delisting via web form
Proofpoint
ipcheck.proofpoint.com
Contact Proofpoint support
Microsoft
sender.office.com
Submit through portal
Delisting Steps
┌─────────────────────────────────────────────────────────────────────────────┐
│ BLACKLIST REMOVAL PROCESS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: Identify the Cause │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Common reasons for blacklisting: │ │
│ │ • Compromised server sending spam │ │
│ │ • Compromised user account │ │
│ │ • Open relay configuration │ │
│ │ • Sending to spam traps (old/invalid addresses) │ │
│ │ • High complaint rate from recipients │ │
│ │ • Malware on the network │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ STEP 2: Fix the Underlying Issue │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ • Scan servers for malware/compromise │ │
│ │ • Reset compromised passwords │ │
│ │ • Close open relays │ │
│ │ • Clean email lists (remove invalids, unsubscribes) │ │
│ │ • Implement rate limiting │ │
│ │ • Add SPF, DKIM, DMARC if missing │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ STEP 3: Document the Fix │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Prepare for delisting request: │ │
│ │ • What was the issue │ │
│ │ • When it was discovered │ │
│ │ • What was done to fix it │ │
│ │ • What measures prevent recurrence │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ STEP 4: Request Delisting │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ • Visit blacklist's removal page │ │
│ │ • Submit IP address and explanation │ │
│ │ • Provide contact information │ │
│ │ • Wait for processing (hours to days) │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ STEP 5: Monitor for Re-listing │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ • Set up automated blacklist monitoring │ │
│ │ • Continue monitoring mail logs │ │
│ │ • Watch for spam complaints │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Spam Folder Issues
Why Emails Land in Spam
┌─────────────────────────────────────────────────────────────────────────────┐
│ SPAM FOLDER CAUSES & FIXES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ AUTHENTICATION ISSUES (Most Common) │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Problem │ Check │ Fix │ │
│ ├────────────────────────┼────────────────────────┼──────────────────────┤ │
│ │ SPF not passing │ Auth headers show fail │ Update SPF record │ │
│ │ DKIM not signing │ No DKIM-Signature │ Configure DKIM │ │
│ │ DMARC not passing │ dmarc=fail in headers │ Fix alignment │ │
│ │ No reverse DNS (PTR) │ dig -x <IP> │ Configure PTR record │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ REPUTATION ISSUES │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Problem │ Check │ Fix │ │
│ ├────────────────────────┼────────────────────────┼──────────────────────┤ │
│ │ IP blacklisted │ Blacklist checkers │ Delist + fix cause │ │
│ │ Poor sender score │ SenderScore.org │ Improve practices │ │
│ │ Domain reputation │ Google Postmaster │ Reduce complaints │ │
│ │ Shared IP issues │ Check IP neighbors │ Get dedicated IP │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ CONTENT ISSUES │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Spam Triggers: │ │
│ │ • ALL CAPS SUBJECT LINES │ │
│ │ • Excessive exclamation marks!!! │ │
│ │ • Spam phrases: "Act now!", "Free!", "Click here" │ │
│ │ • Image-only emails (no text) │ │
│ │ • Poor HTML formatting │ │
│ │ • Unsubscribe link missing │ │
│ │ • URL shorteners (bit.ly, etc.) │ │
│ │ • Suspicious attachments │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ENGAGEMENT ISSUES │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Problem │ Impact │ Fix │ │
│ ├────────────────────────┼────────────────────────┼──────────────────────┤ │
│ │ Low open rates │ Signals unwanted mail │ Better subject lines │ │
│ │ High bounce rates │ Poor list quality │ Clean list regularly │ │
│ │ Many spam reports │ Direct negative signal │ Make unsub easy │ │
│ │ Low interaction │ Low priority for inbox │ Engage users more │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Gmail Deliverability
# Check Gmail deliverability using Postmaster Tools
# https://postmaster.google.com/
# Key metrics to monitor:
# - Domain reputation (High/Medium/Low/Bad)
# - IP reputation
# - Spam rate (target: <0.1%)
# - Authentication rates
# Gmail-specific requirements:
# 1. Valid SPF or DKIM (one required)
# 2. DMARC recommended
# 3. PTR record for sending IP
# 4. TLS encryption
# 5. One-click unsubscribe for bulk senders
# 6. Keep spam complaints under 0.3%
Microsoft 365 Deliverability
# Check reputation at:
# https://sender.office.com/
# Microsoft SNDS (Smart Network Data Services)
# https://sendersupport.olc.protection.outlook.com/snds/
# Key requirements:
# - Valid SPF, DKIM, DMARC
# - Proper reverse DNS
# - Not on Microsoft's block list
# - Compliance with email sending best practices
# Test SMTP connection
nc -v mail.example.com 25
# Or with openssl for TLS
openssl s_client -connect mail.example.com:25 -starttls smtp
# Send test email via telnet (basic test)
telnet mail.example.com 25
HELO test.example.com
MAIL FROM: <[email protected]>
RCPT TO: <[email protected]>
DATA
Subject: Test email
This is a test.
.
QUIT
Email Header Analysis
# Check authentication results in headers
# Look for these lines in email source:
#
# Authentication-Results: ... spf=pass ... dkim=pass ... dmarc=pass
# Received-SPF: pass
# DKIM-Signature: v=1; a=rsa-sha256; d=example.com; ...
# Tools for analysis:
# - MXToolbox Header Analyzer: mxtoolbox.com/EmailHeaders.aspx
# - Google Toolbox: toolbox.googleapps.com/apps/messageheader/
Prevention Best Practices
Email Infrastructure Checklist
┌─────────────────────────────────────────────────────────────────────────────┐
│ EMAIL DELIVERABILITY CHECKLIST │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ AUTHENTICATION (Essential) │
│ [ ] SPF record configured and includes all sending IPs/services │
│ [ ] DKIM signing enabled for all outbound email │
│ [ ] DMARC policy set (start with p=none, monitor, then enforce) │
│ [ ] PTR (reverse DNS) configured for sending IPs │
│ [ ] All authentication passing in test emails │
│ │
│ INFRASTRUCTURE │
│ [ ] Dedicated IP for high-volume sending (>50k/month) │
│ [ ] Proper HELO/EHLO hostname matching PTR │
│ [ ] TLS enabled for sending and receiving │
│ [ ] Rate limiting configured to prevent abuse │
│ [ ] Logs retained for troubleshooting (30+ days) │
│ │
│ LIST MANAGEMENT │
│ [ ] Double opt-in for marketing lists │
│ [ ] Bounce handling (remove hard bounces immediately) │
│ [ ] Unsubscribe handling (honor within 10 days per CAN-SPAM) │
│ [ ] Regular list cleaning (remove inactive 6+ months) │
│ [ ] Never purchase email lists │
│ │
│ MONITORING │
│ [ ] Blacklist monitoring automated │
│ [ ] DMARC reports analyzed regularly │
│ [ ] Google Postmaster Tools configured │
│ [ ] Microsoft SNDS enrolled │
│ [ ] Bounce rates tracked (<2% target) │
│ [ ] Spam complaint rates tracked (<0.1% target) │
│ │
│ CONTENT │
│ [ ] Text and HTML versions of marketing emails │
│ [ ] Proper unsubscribe link in all marketing emails │
│ [ ] Physical address included (CAN-SPAM requirement) │
│ [ ] Avoid spam trigger words and formatting │
│ [ ] Test emails before sending campaigns │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Monitoring Setup
# Simple blacklist monitoring script
#!/bin/bash
IP="203.0.113.10"
REVERSED=$(echo $IP | awk -F. '{print $4"."$3"."$2"."$1}')
EMAIL="[email protected]"
BLACKLISTS=(
"zen.spamhaus.org"
"bl.spamcop.net"
"b.barracudacentral.org"
"dnsbl.sorbs.net"
"bl.spameatingmonkey.net"
)
for BL in "${BLACKLISTS[@]}"; do
RESULT=$(dig +short $REVERSED.$BL)
if [ -n "$RESULT" ]; then
echo "ALERT: $IP listed on $BL" | mail -s "Blacklist Alert" $EMAIL
fi
done
