Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.73

bounce-category-patterns

<domain>

Which pattern list classifies this receiver's bounces first
in the configuration this is a linebounce-category-patternsinside the block <domain>
Your own reply parsing ahead of the general one

A bounce goes into accounting with a note about the cause — the bounceCat field. The node derives the cause from the receiving server’s reply by running the text through pattern lists. This line puts a list of your own, set specifically for this receiver, ahead of the general lists.

The parsing order has three steps: first the list named here, then the unnamed block from the configuration, then the set from the defaults file. Parsing does not stop on a mismatch: if your list recognized nothing, the general ones take over. This line cannot remove a category; it can only add your own or intercept someone else’s earlier.

The line decides nothing about the message’s fate. Whether it bounced is determined by entirely different settings; here only the label in accounting is assigned. The label, however, ends up in reports and statistics, and decisions about the address base are made from those.

The main trap. The line is taken for a way to control bounces. It only names them. A message bounced by the receiving server will stay bounced with any set of patterns — all that changes is which report column it lands in.
What the Hub does. It sets no named lists. The receiver policy template contains an unnamed parsing block — it applies to all receivers at once and covers the usual cases: spam, blocklists, a full mailbox. A separate list for one mailbox provider makes sense when its replies systematically diverge from the general ones.
Recommended values

Start with the unnamed block. It applies to everyone and covers most replies. A named list is needed when a specific receiving server words things its own way.

You can make up a category of your own. Names are not limited to the seventeen vendor ones — a new name simply appears in reports and in the bounceCat field.

The line is not printed in the queue settings. pmta show settings does not show it — you will have to check it in the configuration.

The advice to start with the unnamed block is ours. From the manual here are the three-step parsing order, the freedom in category names and the pattern entry form.
Example configuration
# your own parsing for one mailbox provider, ahead of the general one
<bounce-category-patterns custom>
    /no longer available/ quota-issues
    rcpt-to /invalid recipient/ recipient-related
</bounce-category-patterns>

<domain hotmail.com>
    bounce-category-patterns custom</domain>
The rcpt-to marker narrows the pattern to replies to the RCPT command — without it the pattern is compared with replies at all stages of the conversation.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Trying to cancel a bounce with a list

§ 11.7

What it costsPatterns assign a label, not a decision. A message bounced by the receiving server stays bounced; only the column in the report changes.
How to spot itThe list was configured, and the bounce rate did not change.
How to do it rightThe message’s fate is controlled by other lines — the bounce deadline, the conditions for early bounces, reply parsing for backoff mode.

Expecting your own list to replace the general ones

§ 11.7

What it costsOn a mismatch, parsing goes on — to the unnamed block and to the defaults file. A category you considered excluded is assigned by the general patterns.
How to spot itReports contain a category that is not in your list.
How to do it rightIntercept the replies you need with your own pattern earlier, rather than counting on a rule being absent.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
bounce-category-patterns <name>
Values
the name of a previously declared bounce parsing block; the general lists are applied after it in any case
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The value merges across <domain> blocks from general to specific: the best-matching block wins, not the last one in the file. What is inherited is the list name, not its contents: the parsing block itself is declared separately and at the configuration level, not inside <domain>. It is picked up by pmta reload; bounces already recorded are not recalculated.
⇄

Related directives

2 relations

Does not work without

Named selection rulesParsing works the same way as in reply pattern lists — and is described there in more detail. § 3.3.10.73

Affects

Bounce categoryThe accounting field all this is done for: the assigned category goes here. § 3.3.10.73

Referenced from

replace-smtp-421-service-response<domain>Bounce classification goes by the original text: the replacement does not interfere with it. § 3.3.10.68

How to check on the node
The queue settings do not have the line — what remains is the configuration and the category distribution in accounting:
grep -n bounce-category-patterns /etc/pmta/config
pmtastats bounce-categories --bounceCat all /var/log/pmta/acct-*.csv
The second command shows which categories the bounces were spread across: a large share of other means the patterns do not recognize this receiving server’s replies. The Hub collects the distribution by category; it does not write named lists — the policy template has a common unnamed block.
◇

What else to read

3 articles

◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.◇Reputation monitoring inside the nodeThe engine itself watches the receiving servers’ replies and changes the queue mode on a pattern match — a reaction within the connection, not through telemetry.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Troubleshoot deliverability · Tune the pace for a provider
Neighboring settings of the block <domain>:smtp-pattern-listsmtp-553-means-invalid-mailboxbounce-upon-5xx-greetingbounce-upon-no-mxbounce-upon-transfer-failureAll 135 directives of the block →