Why PowerMTA categorizes bounces numerically
SMTP responses come back from receiving mail servers as text strings. The text is human-readable, sometimes idiosyncratic, and often inconsistent across providers. Gmail says one thing; Outlook says another; a small ISP in Brazil says a third. Treating those strings directly is fragile. PowerMTA solves the problem by parsing the response and assigning a category code: a small integer that summarizes what kind of failure occurred, regardless of how the recipient phrased it.
The category is written to the accounting log as the bounceCat field. Combined with the bounce type (Hard, Soft, Block, Admin, Undetermined), it gives you a stable surface to write suppression rules and reputation analysis against. Your code looks at the integer; PowerMTA handles the text-parsing complexity.
The bounceCat field is available in the accounting log record types b (bounce notifications generated to the original sender) and d (delivery attempts that resulted in a non-2xx final response). Configure it in your <acct-file> directive's record-fields list to include it in the CSV output your suppression and analytics pipeline reads from.
The complete bounce category table
PowerMTA defines roughly twenty distinct categories. They have been stable across major versions, including PowerMTA 5.x. The table below is the canonical reference, with action guidance added.
Suppression strategy by bounce type
The bounce type tells you whether the failure is permanent, temporary, or signals something else entirely. The right suppression rule depends on the type, not just the numeric code.
Hard bounces (10, 30, 90)
Suppress immediately on first occurrence. The recipient is not receiving this message and will not receive future ones. Continued sending damages reputation. The bounce-to-suppression latency should be measured in minutes, not hours.
Admin bounces (25, 80)
Suppress immediately. Code 25 (admin failure) means PowerMTA's own configuration prevented delivery: an internal policy match, a bounce rule, a rate cap. Code 80 (subscribe request) is administrative metadata, not a delivery problem.
Soft bounces (20, 21, 22, 23, 24, 40, 60, 70, 100)
PowerMTA retries automatically with exponential backoff. Suppression should kick in only after a threshold: a common rule is suppress after five consecutive soft bounces over thirty days. Mailbox-full bounces (22) and DNS failures (21) deserve closer monitoring; a recipient whose mailbox has been full for two months is effectively a hard bounce.
Block events (50, 51, 52, 53, 54)
These are the most operationally important codes for active deliverability work. A block event signals that the recipient ISP made a filtering decision. The recipient address itself is fine; the message or sender failed a filter. Suppressing the recipient is the wrong response. Investigating the cause (content, IP reputation, authentication) is the right one.
If your block rate at a single recipient ISP exceeds 1% of attempts to that ISP over an hour, you have an active reputation incident. Pause that ISP's traffic, check Postmaster Tools and SNDS, identify the cause, fix it, then resume.
Undetermined (1)
PowerMTA could not parse the response. Treat as soft. If the rate is more than a few percent, sample the original SMTP responses (also logged) and consider whether you need a custom bounce-categorizer pattern in your PMTA configuration.
Reading bounceCat from the accounting log
A typical accounting configuration that includes the bounce category looks like this in /etc/pmta/config:
records b,d
record-fields b type,timeQueued,timeLogged,orig,rcpt,header_Message-Id,jobId,vmta,bounceCat,dsnStatus,dsnDiag
record-fields d type,timeQueued,timeLogged,orig,rcpt,header_Message-Id,jobId,vmta,bounceCat,dsnStatus,dsnDiag,delay,dlvSourceIp
rolling-period hourly
max-size 1G
</acct-file>
Each row in the resulting CSV will contain the bounceCat value as one of its columns. Your suppression-list pipeline reads the CSV (or tails it in near-real-time) and applies your rules. For high-volume operations, the CSV is fed into a queue and processed by workers; for smaller operations, a cron job that runs every five minutes is enough.
Bounce categorization and sender reputation
Bounce data is one of the strongest signals available for proactive reputation management. Three patterns to monitor weekly:
- Hard bounce rate trend. A growing hard bounce rate over weeks signals list quality decay. Above 2% sustained, you have a list hygiene problem that will cascade into reputation problems at major ISPs.
- Block event distribution per ISP. Plot block events grouped by recipient domain. A spike at one ISP is a targeted reputation incident; a uniform rise across many ISPs is a sender-side problem (IP, content, authentication).
- Spam-content blocks (52) by template or campaign. If you can correlate the bounce category back to the template that generated the message (via the
jobIdfield), you can identify which content generates filtering and adjust before launching the next variant.
For broader context on the deliverability stack that uses these signals, see our glossary entries on sender reputation, DMARC, and the implementation guide at IP warming.
Need bounce processing implemented for you?
Our managed PowerMTA plans include real-time bounce categorization, automated suppression, and weekly bounce-trend reports. If your current setup misses bounces or processes them slowly, we can audit the configuration.