Every mail server produces bounces. A bounce that goes nowhere is wasted information; a bounce that lands in a manual support inbox is a half-day of human triage. This article is the bounce-analysis pattern we run on production mail edges — pipe Postfix’s bounce messages through Sisimai (the maintained successor to BounceHammer), classify hard vs soft, and feed a suppression list back into Postfix or the ESP so the same dead address doesn’t get repeatedly mailed.
How to verify
Look at what bounces today and where they go.
sudo postconf | grep -E 'bounce|notify|double_bounce'
ls -l /var/spool/postfix/bounce/ /var/spool/postfix/defer/
sudo postqueue -p | head -30
which sisimai 2>/dev/null || pip3 list 2>/dev/null | grep -i sisi
Postfix generates bounces in two cases: a permanent delivery failure (5xx) and an aging temporary failure (4xx repeatedly until maximal_queue_lifetime is reached, default 5 days). The bounce arrives back at the original sender, or at postmaster@ if it’s a double-bounce.
What’s happening
A bounce is itself a piece of mail. The Internet has a sort-of-standard for it called DSN (Delivery Status Notification, RFC 3461-3464) — multipart/report messages with a message/delivery-status part containing structured fields like Action: failed, Status: 5.1.1, Diagnostic-Code: smtp; 550 5.1.1 User unknown. In practice, half the world’s bouncers ignore the standard and produce free-text English (or worse, free-text Russian or Chinese).
The classification you actually want:
- Hard bounce (permanent) —
5xxSMTP code or5.x.yenhanced status. The recipient does not exist. Stop sending to this address forever. - Soft bounce (transient) —
4xxSMTP code or4.x.y. Mailbox full, server temporarily unreachable, greylisting. Retry on schedule; suppress only after a threshold (we use 3 soft bounces over 30 days). - Spam-block bounce —
550 5.7.1and similar from receiver content filters. Different from “user unknown” — the address is real but the content tripped a filter. Action depends on whether your content is genuinely flagged or the receiver is overzealous.
Sisimai is a Perl/Ruby/Python library that parses bounce messages into structured records regardless of which MTA produced them. We use the Python binding (pip install sisimai) for the easiest integration with whatever pipeline already runs.
The procedure
-
Install Sisimai:
sudo apt install -y python3-pip sudo pip3 install sisimai python3 -c "import sisimai; print(sisimai.__version__)" -
Capture bounces in a parseable location. Postfix sends bounces to the original sender by default. For analysis, set up a
postmasteralias that BCCs to a dedicated archive mailbox, or read directly from thedouble-bouncequarantine.Option A — alias the bounce sender to a mailbox you read:
# /etc/postfix/virtual MAILER-DAEMON@example.com bounces-archive@example.comOption B — use
notify_classesto forward bounces to postmaster too:# /etc/postfix/main.cf notify_classes = resource, software, bounce, 2bounce, protocol bounce_notice_recipient = bounces-archive@example.com 2bounce_notice_recipient = bounces-archive@example.comReload Postfix after either change.
-
Write a parser script. Sisimai’s API takes a mailbox file or a directory of message files:
#!/usr/bin/env python3 # /usr/local/bin/parse-bounces.py import sisimai, json, sys path = sys.argv[1] v = sisimai.rise(path) if v is None: sys.exit(0) for r in v: print(json.dumps({ "timestamp": r.timestamp.timestamptz.isoformat(), "recipient": r.recipient.address, "sender": r.addresser.address, "smtp_status": r.deliverystatus, "diagnostic_code": r.diagnosticcode, "reason": r.reason, # "userunknown", "filtered", "expired", etc. "hardbounce": r.hardbounce, # boolean }))Run against a Maildir:
chmod +x /usr/local/bin/parse-bounces.py /usr/local/bin/parse-bounces.py /var/vmail/example.com/bounces-archive/Maildir/cur/Output is one JSON record per parsed bounce, suitable for piping into jq, an ELK stack, or a flat suppression-list file.
-
Build a suppression list. A simple sqlite-backed model —
suppression.dbwith columnsemail,first_seen,last_seen,soft_count,is_suppressed. The logic:if reason == "userunknown" or hardbounce: INSERT OR REPLACE INTO suppress (email, first_seen, last_seen, is_suppressed) VALUES (?, COALESCE((SELECT first_seen FROM suppress WHERE email=?), ?), ?, 1) elif reason in ("mailboxfull", "expired") and not hardbounce: UPDATE suppress SET soft_count = soft_count + 1, last_seen = ? WHERE email = ? # promote to suppressed if soft_count > 3 in last 30 days UPDATE suppress SET is_suppressed = 1 WHERE email = ? AND soft_count > 3The suppression list is what you feed back to Postfix or your ESP. For Postfix:
sqlite3 suppression.db "SELECT email FROM suppress WHERE is_suppressed=1" \ | awk '{print $1 " REJECT 5.1.1 Address in suppression list"}' \ > /etc/postfix/suppression.txt sudo postmap hash:/etc/postfix/suppression.txtThen in
main.cf:smtpd_recipient_restrictions = check_recipient_access hash:/etc/postfix/suppression.txt ... -
Schedule the parser. A cron job every 15 minutes is enough for most volumes:
*/15 * * * * /usr/local/bin/parse-bounces.py /var/vmail/example.com/bounces-archive/Maildir/new/ \ | /usr/local/bin/load-suppressions.py */15 * * * * postmap hash:/etc/postfix/suppression.txt
ESP integration
When relaying via an ESP (Mailgun, SendGrid, SES — see relay-via-mailgun-sendgrid-pattern), bounces go to the ESP first. The ESP exposes:
- A webhook that POSTs bounce events to your endpoint in real time.
- An API to query bounce events.
- The ESP’s own suppression list — which you should keep in sync with yours.
In the engagements we run, we mirror the ESP’s bounce data into the same Sisimai-fed suppression DB so a single source of truth covers both direct and relayed traffic.
Common pitfalls
- The
MAILER-DAEMON@alias points to a real mailbox that nobody reads — bounces pile up forever; archive but parse, don’t just archive. - Sisimai’s regex pack is comprehensive but not infinite — exotic ESPs (some Russian and Chinese ISPs) produce bounce text that doesn’t parse cleanly; expect a 1-3% “unknown” rate.
- The suppression list grows unbounded and starts to slow
postmaplookups — periodically purge entries older than 365 days or move them to a “permanent” table. - Soft-bounce thresholds set too low (1 soft = suppress) cause aggressive list erosion — a real user’s mailbox briefly full shouldn’t permanently drop them; use ≥3 soft bounces over 30 days.
- The bounce mailbox itself fills up because there’s no rotation —
bounces-archiveshould have a Sieve rule that auto-archives anything older than 90 days, or a cron that prunes parsed files.
Stack Harbor runs bounce analysis as the deliverability feedback loop on managed mail edges — Sisimai parsing every bounce into structured records, the suppression list synced between Postfix and any ESP relay, and the threshold for soft-bounce promotion tuned per tenant. If your Postfix produces bounces that nobody reads and your sender reputation is sliding, that closed loop is part of our Managed Operations practice.