Mail Server Series — Part 11

Throughout the previous ten articles, we have built a fully modular, enterprise-grade mail system from the ground up:

Postfix, Dovecot, Amavis, SpamAssassin, ClamAV, Piler, Manticore, Pilermilter, Roundcube, MariaDB, Docker networking, Let’s Encrypt, and more.

In this final chapter, we will provide a comprehensive Troubleshooting Guide and FAQ you can rely on during long-term maintenance.

This is your Mail Server “Medical Handbook.”

---

🔶 1. How to Identify Which Component Is Failing? (Overview)

Most email problems fall into eight categories:

Symptom	Most Likely Component
Cannot send email (Outbound → Internet)	Postfix → Amavis → DNS → Firewall
Cannot receive email (Internet → Inbound)	DNS → MX → Postfix → Amavis
Webmail login failure	Dovecot, TLS, firewall
IMAP/SMTP login from clients fails	Dovecot, SASL, TLS
Virus/Spam scanning not working	Amavis, SpamAssassin, ClamAV
Anti-spam accuracy is low	SpamAssassin rules, Bayes DB
Search results incomplete	Manticore index, Piler config
Piler login fails	IMAP Auth, config-site.php

The following sections break down the troubleshooting process for each subsystem.

---

🔶 2. Outbound Delivery Issues (Cannot Send Email)

🔍 Typical symptoms:

• Messages stuck in mail queue
• Bounce messages (5.7.1, 5.4.4, 4.4.3)
• Gmail/Outlook rejects emails

🔧 Step-by-step troubleshooting

Step 1 — Check Postfix queue

postqueue -p

If many messages are deferred:

mailq | less

---

Step 2 — Test outbound delivery using swaks

swaks --to your@gmail.com --server postfix --port 25

If it hangs → firewall is blocking outbound SMTP.

---

Step 3 — Validate DNS

dig A mail.yourdomain.com
dig MX yourdomain.com
dig TXT yourdomain.com

Incorrect DNS is the most common cause.

---

Step 4 — Check Amavis connectivity

nc -z amavis 10024
nc -z amavis 10026

---

Step 5 — Validate SPF, DKIM, DMARC

Use mail-tester.com or:

dig TXT default._domainkey.yourdomain.com

---

🔶 3. Inbound Delivery Issues (Cannot Receive Email)

🔍 Symptoms:

• Remote server reports “Connection timed out”
• Gmail shows “Recipient server not responding”
• No inbound logs on Postfix

🔧 Troubleshooting

Step 1 — Verify MX record

dig MX yourdomain.com

Should point to your mail server, not a web server.

---

Step 2 — Test incoming port 25 from the Internet

nc -zv mail.yourdomain.com 25

Timeout → firewall issue.

---

Step 3 — Check inbound Postfix logs

tail -f /var/log/postfix/postfix.log

If empty → connection does not reach Postfix.

---

Step 4 — Verify Amavis reinjection

Search for traffic on port 10025:

grep 10025 /var/log/postfix/postfix.log

If stuck → Amavis/SpamAssassin bottleneck.

---

🔶 4. Webmail (Roundcube) Login Issues

🔍 Common errors:

• “Connection to IMAP server failed”
• “Login failed”
• HTTP 502/504

🔧 Troubleshooting

Step 1 — Check Roundcube → Dovecot connectivity

docker exec -it webmail ping dovecot

---

Step 2 — Test IMAP TLS

openssl s_client -connect dovecot:993

If output contains:

unknown protocol

→ You exposed non-TLS port as TLS port.

---

Step 3 — Check firewall rules

Roundcube must access:

• Dovecot (993 / 143)
• SMTP Submission (587)

If packets blocked on host firewall:

iptables -I DOCKER-USER 1 -s 172.18.0.0/16 -d 172.18.0.1 -j ACCEPT

---

🔶 5. Dovecot Troubleshooting

🔍 5.1 Login failures

Check logs:

tail -f /var/log/dovecot/dovecot.log

Common causes:

• Wrong MySQL credentials
• Dovecot cannot reach MySQL
• TLS/SNI misconfiguration

---

🔍 5.2 LMTP delivery failures (Postfix → Dovecot)

nc -z dovecot 24

If not reachable → LMTP is not running or misconfigured.

---

🔶 6. SpamAssassin / Amavis Issues

❗ 6.1 Amavis hangs (emails freeze)

tail -f /var/log/amavis/amavis.log

Typical messages:

• “timed out waiting for SA”
• “ClamAV not responding”

Restart:

docker restart amavis spamd clamav

---

❗ 6.2 SpamAssassin not learning HAM/SPAM

Test spamd:

nc -z spamassassin 783

If the global sieve scripts do not execute:

Check:

pipe :copy "sa-remote-learn-ham.sh"

---

🔶 7. Piler Troubleshooting

🔍 7.1 Cannot log in (IMAP auth failure)

Check:

tail -f /var/log/apache2/archive_error.log

Or Piler logs.

Validate config:

$config['ENABLE_IMAP_AUTH'] = 1;
$config['IMAP_HOST']        = 'dovecot';
$config['IMAP_PORT']        = 993;

---

🔍 7.2 Chinese search not working

Check manticore logs:

docker logs manticore | grep chinese

If ICU tokenizer not loaded → wrong image.

---

🔍 7.3 Piler not receiving archive emails

Postfix must have:

always_bcc = piler@archive.local

Check hostname resolution:

docker exec postfix ping archive.local

If unresolved, add to postfix:

--add-host archive.local:172.18.0.1

---

🔶 8. Manticore Troubleshooting

🔍 8.1 Cannot connect to 9306

mysql -h manticore -P 9306

If failed:

• data folder permission incorrect
• corrupted index → clean folder and reinit

---

🔶 9. Postfix Common Errors

❗ Error: “5.4.4 relay access denied”

• relay_domains not configured
• recipient restrictions wrong
• transport_maps missing entry

---

❗ Error: “Name or service not known”

Container name not resolvable → wrong network.

---

❗ Error: “connection refused 10024”

Amavis crashed.

---

❗ DKIM fail

Check amavis log:

grep DKIM /var/log/amavis/amavis.log

---

🔶 10. FAQ — Frequently Asked Questions

---

Q1: Why do my emails always land in Gmail/Outlook spam folder?

Check:

• SPF
• DKIM
• DMARC
• Reverse DNS

---

Q2: Users report missing emails, but server is normal?

Common reasons:

• Sender’s DNS error
• Sender blacklisted your IP
• Bounce messages filtered by sender

---

Q3: Can users send EXE or ZIP attachments?

Amavis blocks them by default.

Modify:

$banned_filename_re

---

Q4: Can I add more domains?

Yes — add domains using PostfixAdmin.

---

Q5: Does Webmail support OAuth/2FA?

Yes, with additional plugins or reverse-proxy OAuth solutions.

---

🔶 11. Final Words — Your Mail System Is Now Truly Enterprise-Grade

With this series completed, you now operate a system that is:

• Fully modular
• Highly secure
• Virus-/Spam-protected
• Multi-domain ready
• Docker-orchestrated
• Supports full-text Chinese search
• Properly archived with Piler
• Equipped with logging, monitoring, and automation

This is no longer “just an email server.”
It is a complete enterprise messaging platform, fully under your control.