How to Troubleshoot Email Delivery Issues

How to Troubleshoot Email Delivery Issues

Email delivery problems are among the most common issues on self-hosted mail servers. Whether messages are bouncing, landing in spam folders, or silently disappearing, a systematic approach to diagnosis will help you identify and resolve the root cause on your Breeze server.

Step 1: Check the Mail Queue

Start by examining whether messages are stuck in the Postfix queue:

# View the mail queue
mailq

# Count queued messages
mailq | tail -1

# View details of a specific queued message
postcat -q MESSAGE_ID

# Flush the queue (attempt redelivery)
sudo postqueue -f

If the queue is large, check for a common pattern in the deferred messages — often a single misconfiguration causes all of them.

Step 2: Examine Mail Logs

The mail log is your primary diagnostic tool:

# Follow the log in real time
sudo tail -f /var/log/mail.log

# Search for a specific recipient
sudo grep "recipient@example.com" /var/log/mail.log

# Look for errors and warnings
sudo grep -iE "(error|warning|reject|bounce)" /var/log/mail.log | tail -50

Step 3: Verify DNS Records

Missing or incorrect DNS records are a frequent cause of delivery failures:

# Check MX records
dig +short MX yourdomain.com

# Verify SPF record
dig +short TXT yourdomain.com | grep spf

# Check DKIM record
dig +short TXT default._domainkey.yourdomain.com

# Verify DMARC policy
dig +short TXT _dmarc.yourdomain.com

# Confirm reverse DNS (PTR)
dig +short -x YOUR_SERVER_IP

Every mail server should have all five: MX, SPF, DKIM, DMARC, and a matching PTR record.

Step 4: Test SMTP Connectivity

Verify your server can establish outbound SMTP connections:

# Test connection to a remote mail server
openssl s_client -connect gmail-smtp-in.l.google.com:25 -starttls smtp

# Check if port 25 outbound is blocked
telnet gmail-smtp-in.l.google.com 25

# Send a test message via command line
echo "Test body" | mail -s "Delivery test" test@example.com

Step 5: Check Blacklist Status

If your server IP is blacklisted, major providers will reject your mail:

# Check common blacklists (or use an online tool like mxtoolbox.com)
dig +short YOUR_IP.zen.spamhaus.org
dig +short YOUR_IP.bl.spamcop.net

If listed, follow the delisting process for each blacklist. Common causes include open relays, compromised accounts, or high bounce rates.

Step 6: Verify Authentication

Check that DKIM signing is working correctly:

# Verify OpenDKIM is running
sudo systemctl status opendkim

# Check the DKIM key permissions
sudo ls -la /etc/opendkim/keys/yourdomain.com/

# Test DKIM signing
opendkim-testkey -d yourdomain.com -s default -vvv

Common Issues and Solutions

• Connection refused on port 25 — check firewall rules and ensure Postfix is listening: ss -tlnp | grep 25
• Relay access denied — verify mynetworks and SASL authentication in main.cf
• Messages marked as spam — ensure SPF, DKIM, and DMARC are all correctly configured and aligned
• Timeout errors — check network connectivity and DNS resolution from the server
• Mailbox full bounces — increase quota or notify the user to clean their mailbox
• TLS handshake failures — verify certificates are valid and not expired with openssl s_client

Preventive Monitoring

Set up ongoing monitoring to catch issues early:

# Monitor queue size
mailq | tail -1

# Alert on high bounce rates
sudo grep "status=bounced" /var/log/mail.log | wc -l

# Check certificate expiry
openssl x509 -in /etc/ssl/certs/mail.pem -noout -enddate

Regular monitoring of these metrics will help you detect and resolve email delivery problems before they affect your users.