PowerMTA smtp-pattern-list: Complete 2026 Operator Guide to Conditional Response Handling

Why conditional response handling matters

PowerMTA's default response handling is binary: 4xx responses get retried, 5xx responses get bounced. This works as a baseline but ignores the substantial variation within those categories. Not all 4xx responses are equal: a 421 service-temporarily-unavailable is genuinely transient and should be retried, while a 452 mailbox-full from a provider with enormous mailbox sizes is effectively permanent and retrying it for days wastes resources. Not all retry-eligible responses should be retried at full pace: a Yahoo TSS04 throttle code is a signal to slow down immediately, not to keep retrying at normal cadence.

The smtp-pattern-list directive is PowerMTA's mechanism for handling this variation. It lets operators define response patterns and the action PowerMTA should take when a response matches, overriding the general 4xx-retry, 5xx-bounce default for recognized cases. This is one of PowerMTA's most valuable features and one of the most underused, because the default configuration includes no pattern lists and operators frequently never set them up.

This guide exists to make smtp-pattern-list practical. The structure: the directive syntax, the available actions, how pattern matching works, building automatic backoff patterns for throttle codes, converting 4xx responses to bounces, ISP-specific pattern lists for the major receivers, the interaction with retry directives, tuning pattern lists from accounting log analysis, and a full configuration example.

The smtp-pattern-list directive syntax

The smtp-pattern-list is defined as a named block containing pattern-action pairs, then referenced from domain blocks.

<smtp-pattern-list name="example-list">
    pattern "TSS04"            backoff
    pattern "mailbox is full"  bounce
    pattern "try again later"  retry
</smtp-pattern-list>

domain yahoo.com {
    max-msg-rate 2500/h
    smtp-pattern-list example-list
}

The structure: the named block declares the list with a name attribute; each pattern line specifies a text pattern in quotes followed by an action; the smtp-pattern-list directive inside a domain block attaches the named list to that domain.

Multiple domain blocks can reference the same named pattern list, and an operator typically maintains a few named lists (one per major ISP, or a shared general list) referenced from the appropriate domain blocks.

The pattern lists are read top to bottom and the first matching pattern applies. Order patterns from most specific to most general so a specific pattern is not preempted by a broader one.

The available actions

Each pattern entry specifies an action PowerMTA takes when a response matches the pattern:

Action	Effect
backoff	Put the queue into backoff mode immediately
bounce	Bounce the message as permanent failure
retry	Retry the message normally
success	Treat the response as a successful delivery

backoff is the most-used action. When a response matches a backoff pattern, PowerMTA puts the queue into backoff mode immediately, switching to the slower backoff-retry interval. This is the correct response to throttle codes: the receiving MTA is signaling slow down, and backoff mode does exactly that without waiting for the backoff-after error count to accumulate.

bounce converts a response into a permanent failure. The main use is 4xx responses that actually signal permanent failure, where retrying for days is pointless. The message bounces immediately and the recipient can be suppressed.

retry forces normal retry handling. The main use is overriding a response that PowerMTA might otherwise bounce: if a receiving MTA returns a 5xx code for a situation that is actually transient, a retry pattern keeps PowerMTA retrying.

success treats a response as successful delivery. This is rare and used in unusual situations where a receiving MTA returns a non-2xx response for a message that was actually accepted; operators use it carefully because incorrectly marking failures as successes hides delivery problems.

How pattern matching works

Pattern matching is substring matching against the SMTP response text. When PowerMTA receives a response from a receiving MTA, it checks whether the response text contains any of the patterns in the attached pattern list.

The SMTP response that PowerMTA matches against includes the response code and the response text. For a response like:

421 4.7.0 [TSS04] Messages from 203.0.113.42 temporarily deferred due to user complaints

A pattern of "TSS04" matches because the substring TSS04 appears in the response. A pattern of "temporarily deferred" also matches. A pattern of "421 4.7.0" matches the code portion.

The substring matching is straightforward but operators should choose patterns carefully. A pattern that is too broad matches responses it should not: a pattern of just "deferred" would match many different deferral responses, possibly including some that should be handled differently. A pattern that is too specific may miss variations: receiving MTAs occasionally vary their response text, so a pattern matching the exact full response text is fragile. The sweet spot is a distinctive substring that reliably identifies the response type without over-matching: a code like TSS04 or S3140, or a distinctive phrase like "mailbox is full".

Pattern matching is generally case-sensitive, so patterns should match the case the receiving MTA actually uses. When uncertain, check the accounting log dsnDiag field to see the exact response text.

Automatic backoff patterns

The most valuable use of smtp-pattern-list is automatic backoff on throttle codes. Each major ISP returns recognizable throttle codes, and a backoff pattern for each makes PowerMTA respond correctly without waiting for error counts.

<smtp-pattern-list name="throttle-backoff">
    # Yahoo throttle codes
    pattern "TSS04"  backoff
    pattern "TSS09"  backoff
    pattern "TS01"   backoff
    # Microsoft throttle codes
    pattern "S3140"  backoff
    pattern "S3150"  backoff
    pattern "OU-002" backoff
    # Gmail throttle phrases
    pattern "unusual rate of unsolicited mail"  backoff
    pattern "421-4.7.28"  backoff
</smtp-pattern-list>

This pattern list, attached to the relevant domain blocks, makes PowerMTA enter backoff mode the moment a recognized throttle code appears. The benefit over relying solely on backoff-after error counting: the backoff happens on the first throttle signal rather than after N errors accumulate. When an ISP starts throttling, the faster PowerMTA backs off, the less the throttling escalates, so the immediate pattern-based backoff is meaningfully better than counting errors first.

The backoff patterns are ISP-specific because each ISP's throttle codes differ. Yahoo uses the TSS family, Microsoft uses S-codes and OU-codes, Gmail uses descriptive phrases and specific 421 sub-codes. The pattern list should cover the throttle codes for whichever ISPs the operator sends substantial volume to.

Converting 4xx to bounces

The second valuable use is converting 4xx responses that signal permanent failure into immediate bounces.

The SMTP standard says 4xx responses should be retried. But some 4xx responses are effectively permanent: a mailbox-full response from a provider with very large mailbox sizes typically means an abandoned account; an account-inactive response means a permanently disabled account; some providers return 4xx for non-existent addresses to avoid revealing account validity to spammers.

<smtp-pattern-list name="bounce-permanent-4xx">
    pattern "mailbox is full"          bounce
    pattern "account is inactive"      bounce
    pattern "mailbox has been suspended"  bounce
    pattern "user is over quota"       bounce
    pattern "account has been disabled"   bounce
    pattern "no longer accepting mail"    bounce
</smtp-pattern-list>

When PowerMTA receives a 4xx response matching one of these patterns, it bounces the message immediately rather than retrying for days. The benefits: reduced queue depth (no accumulation of messages that will never deliver), accelerated suppression list updates (the bounce triggers suppression processing immediately), and conserved retry budget (retry attempts go to messages that might actually deliver).

ISP-specific pattern lists

The practical pattern is one named pattern list per major ISP, each covering that ISP's recognizable codes.

Yahoo pattern list:

<smtp-pattern-list name="yahoo-patterns">
    pattern "TSS04"  backoff
    pattern "TSS09"  backoff
    pattern "TS01"   backoff
    pattern "421 4.7.0"  backoff
</smtp-pattern-list>

Microsoft pattern list:

<smtp-pattern-list name="microsoft-patterns">
    pattern "S3140"  backoff
    pattern "S3150"  backoff
    pattern "OU-002" backoff
    pattern "S3115"  backoff
</smtp-pattern-list>

Gmail pattern list:

<smtp-pattern-list name="gmail-patterns">
    pattern "unusual rate of unsolicited mail"  backoff
    pattern "421-4.7.28"  backoff
    pattern "421-4.7.0"   backoff
</smtp-pattern-list>

Attach each list to the matching domain block:

domain yahoo.com   { smtp-pattern-list yahoo-patterns; max-msg-rate 2500/h }
domain hotmail.com { smtp-pattern-list microsoft-patterns; max-msg-rate 5000/h }
domain gmail.com   { smtp-pattern-list gmail-patterns; max-msg-rate 3000/h }

When domains are collapsed with queue-to (Yahoo family, Microsoft family), the pattern list is attached to the queue-target domain and applies to all the collapsed variants.

Interaction with retry directives

The smtp-pattern-list interacts with PowerMTA's retry directives. Understanding the interaction prevents confusion.

The retry directives (retry-after, retry-sequence, backoff-retry, backoff-after) control retry timing and escalation based on the general response category and the count of consecutive errors. The smtp-pattern-list overrides this general handling for specific recognized patterns.

Situation	Without pattern list	With pattern list
Yahoo TSS04 received	Retry per retry-after; backoff after backoff-after errors	Backoff immediately on first TSS04
4xx mailbox-full received	Retry until retry-max-time	Bounce immediately if matched
Unrecognized 4xx received	Retry per retry-after	Retry per retry-after (no pattern match)
Unrecognized 5xx received	Bounce	Bounce (no pattern match)

The design principle: retry directives set the general policy, smtp-pattern-list handles the recognized exceptions. A response that does not match any pattern falls through to the general retry handling. A response that matches a pattern gets the pattern's action instead.

The pattern-based backoff is faster than backoff-after counting: backoff-after waits for N consecutive errors before entering backoff, while a backoff pattern enters backoff on the first matching response. For throttle codes, the faster pattern-based backoff is better because it slows sending before the throttling escalates. Operators typically keep backoff-after configured as a fallback for throttle situations the pattern list does not recognize, while the pattern list handles the recognized codes immediately.

Tuning pattern lists from accounting logs

Pattern lists are tuned from accounting log analysis. The process:

Step 1: identify recurring response patterns. Query the accounting log for the dsnDiag field of t-type and b-type records, grouped to find the common response patterns:

SELECT
    substring(dsnDiag, 1, 80) AS diag_pattern,
    count() AS occurrences
FROM pmta_accounting
WHERE type IN ('t', 'b')
  AND timeLogged >= now() - INTERVAL 7 DAY
GROUP BY diag_pattern
ORDER BY occurrences DESC
LIMIT 50;

Step 2: identify throttle codes that should trigger backoff. Among the common patterns, find the throttle codes (TSS04, S3140, Gmail rate phrases). These should be backoff patterns if not already.

Step 3: identify 4xx responses that never deliver. Find 4xx response patterns that recur for the same recipients without ever producing a d-type delivery record. These are candidates for bounce patterns.

-- Find recipients with repeated 4xx but no delivery
SELECT
    rcpt,
    substring(dsnDiag, 1, 60) AS diag,
    count() AS retry_count
FROM pmta_accounting
WHERE type = 't'
  AND timeLogged >= now() - INTERVAL 14 DAY
GROUP BY rcpt, diag
HAVING retry_count >= 5
ORDER BY retry_count DESC;

Step 4: verify before adding bounce patterns. For each candidate 4xx bounce pattern, confirm the response genuinely never delivers. Only add to the bounce list patterns confirmed as effectively permanent.

Step 5: add patterns and reload. Update the smtp-pattern-list definitions, then pmta reload to apply.

Step 6: monitor effect. After adding patterns, watch the accounting log to confirm the backoff patterns trigger backoff appropriately and the bounce patterns convert the targeted responses to bounces.

Pattern list tuning is an ongoing process. ISPs occasionally change response text, new throttle codes appear, and the operator's recipient base shifts. Periodic accounting log review keeps the pattern lists matched to current reality.

Full configuration example

A complete smtp-pattern-list configuration for an operator sending to the major ISPs:

# Throttle backoff patterns - one shared list
<smtp-pattern-list name="isp-throttle">
    # Yahoo
    pattern "TSS04"  backoff
    pattern "TSS09"  backoff
    pattern "TS01"   backoff
    # Microsoft
    pattern "S3140"  backoff
    pattern "S3150"  backoff
    pattern "S3115"  backoff
    pattern "OU-002" backoff
    # Gmail
    pattern "unusual rate of unsolicited mail"  backoff
    pattern "421-4.7.28"  backoff
</smtp-pattern-list>

# Permanent 4xx bounce patterns - shared list
<smtp-pattern-list name="bounce-permanent">
    pattern "mailbox is full"             bounce
    pattern "account is inactive"         bounce
    pattern "mailbox has been suspended"  bounce
    pattern "account has been disabled"   bounce
    pattern "user is over quota"          bounce
    pattern "no longer accepting mail"    bounce
</smtp-pattern-list>

# Domain blocks reference the pattern lists
domain gmail.com {
    max-msg-rate 3000/h
    max-conn-rate 20/m
    max-smtp-out 15
    retry-sequence 5m,10m,15m,30m,1h,4h
    backoff-retry 30m
    backoff-after 10 errors
    smtp-pattern-list isp-throttle
    smtp-pattern-list bounce-permanent
}

domain yahoo.com {
    max-msg-rate 2500/h
    max-conn-rate 15/m
    max-smtp-out 5
    retry-sequence 15m,30m,1h,4h,8h
    backoff-retry 1h
    backoff-after 5 errors
    smtp-pattern-list isp-throttle
    smtp-pattern-list bounce-permanent
}

domain hotmail.com {
    max-msg-rate 5000/h
    max-conn-rate 10/m
    max-smtp-out 5
    retry-sequence 10m,15m,30m,1h,2h,6h
    backoff-retry 1h
    backoff-after 5 errors
    smtp-pattern-list isp-throttle
    smtp-pattern-list bounce-permanent
}

domain default {
    max-msg-rate 500/h
    retry-sequence 15m,30m,1h,2h,6h
    smtp-pattern-list bounce-permanent
}

This configuration: the isp-throttle list provides automatic backoff on recognized throttle codes from Yahoo, Microsoft, and Gmail; the bounce-permanent list converts known-permanent 4xx responses to bounces; each domain block references both lists so it gets both behaviors. A domain can reference multiple pattern lists, and PowerMTA applies all of them.

The smtp-pattern-list directive is one of PowerMTA's most valuable and most underused features. It lets delivery behavior match actual receiving MTA signals: automatic backoff the moment a throttle code appears, immediate bounce for 4xx responses that signal permanent failure, normal retry for everything else. The configuration is straightforward, the pattern lists tune cleanly from accounting log analysis, and the operational benefits (faster backoff response, reduced queue depth, accelerated suppression) are substantial. Operators running PowerMTA without any smtp-pattern-list configuration are leaving meaningful delivery improvement on the table. Building ISP-specific pattern lists and a permanent-4xx bounce list, attached to the appropriate domain blocks, is a high-value configuration investment that pays back in better delivery behavior and cleaner queue dynamics.