PowerMTA Bounce Patterns

Why Custom Bounce Patterns Are Necessary

PowerMTA ships with a built-in bounce pattern library covering standard SMTP response codes. But ISPs and corporate mail servers frequently return non-standard diagnostic messages that the default patterns do not classify correctly. Without custom pattern matching, these responses are treated as generic deferrals or unknown bounces — leading to repeated delivery attempts to permanently invalid addresses, or premature bouncing of messages that should be retried.

Custom smtp-pattern-list entries address this gap by matching ISP-specific diagnostic text strings to the correct bounce type or retry behavior. Building and maintaining these patterns is an ongoing operational task — ISPs change their error messages, and patterns that worked last year may no longer match current responses.

smtp-pattern-list Configuration Syntax

# /etc/pmta/config — custom bounce pattern configuration
smtp-pattern-list custom-isp-patterns {
    # Format: "MATCH_STRING" action [parameters]
    
    # Permanent failures — bounce immediately, suppress address
    "mailbox unavailable"       bounce type=bad-mailbox
    "user unknown"              bounce type=bad-mailbox
    "does not exist"            bounce type=bad-mailbox
    "invalid address"           bounce type=bad-mailbox
    "no such user"              bounce type=bad-mailbox
    "account has been disabled" bounce type=bad-mailbox
    "account suspended"         bounce type=bad-mailbox
    
    # Domain-level failures — bounce domain
    "domain not found"          bounce type=bad-domain
    "host not found"            bounce type=bad-domain
    "no mx record"              bounce type=bad-domain
    
    # Spam rejections — bounce as spam type
    "spam detected"             bounce type=spam
    "message rejected as spam"  bounce type=spam
    "content policy violation"  bounce type=spam
    
    # Quota failures — retry for several days
    "over quota"                bounce type=quota
    "mailbox full"              bounce type=quota
    "storage limit exceeded"    bounce type=quota
    
    # Greylisting — retry with longer interval
    "greylisted"                retry-after=30m
    "try again later"           retry-after=20m
    "please retry"              retry-after=25m
    
    # Rate limiting — back off
    "too many connections"      retry-after=60m max-smtp-out=2
    "rate limit exceeded"       retry-after=45m
}

# Apply to all destinations

    smtp-pattern-list custom-isp-patterns

ISP-Specific Pattern Tables

Building an ISP-Specific Pattern Library

Effective custom pattern libraries are built from accounting log data, not guesswork. The dsnDiag field in the PowerMTA CSV accounting log contains the exact diagnostic text received from every remote MTA. Analyzing this field across bounce records identifies which patterns appear most frequently and which are being misclassified.

# Extract all unique bounce diagnostic messages from accounting log
awk -F, 'NR>1 && $1=="b" {print substr($10,1,70)}' \
  /var/log/pmta/accounting-YYYYMMDD.csv | \
  sort | uniq -c | sort -rn | head -30

# Identify patterns NOT matched by current classification
# (These show up as generic bounce type with unusual dsnDiag text)
awk -F, 'NR>1 && $1=="b" && $9=="unknown" {print substr($10,1,70)}' \
  /var/log/pmta/accounting-YYYYMMDD.csv | \
  sort | uniq -c | sort -rn | head -20

Pattern Testing and Validation

# Test pattern matching without affecting live traffic
pmta test-pattern "user does not exist" custom-isp-patterns
# Output: matched rule "does not exist" → type=bad-mailbox

# Validate pattern file syntax before reload
pmta check-config /etc/pmta/config
# Output: config OK — no syntax errors

# Apply pattern updates without restart
pmta reload
# Verify: pmta show status — no downtime during reload

Handling Complex Pattern Matching

# Patterns support case-insensitive matching (default)
# Multiple patterns can match the same message — first match wins
# Order patterns from most specific to least specific

smtp-pattern-list precise-patterns {
    # Most specific first (full phrase)
    "The email account that you tried to reach does not exist" bounce type=bad-mailbox
    
    # Medium specificity (partial phrase)
    "does not exist"    bounce type=bad-mailbox
    
    # Least specific (keyword) — catches remainder
    "unknown"           bounce type=bad-mailbox
}

# Important: "unknown" would also match "unknown error" or "unknown host"
# Overly broad patterns cause misclassification — be specific
# Test each pattern against accounting log samples before deploying

Building a Custom Pattern Library from Accounting Logs

Extract unclassified dsnDiag patterns monthly: awk -F, '$1=="b" && $9=="unknown"' accounting.csv | sort | uniq -c | sort -rn | head -20. Any pattern appearing more than 50 times per day that is misclassified should be added to the smtp-pattern-list. ISPs change their error messages periodically — patterns that worked six months ago may no longer match current diagnostics.

Accounting Log Analysis for This Configuration

Monitor this configuration area through the PowerMTA accounting log's dsnDiag field. Filter accounting records for the specific ISP domains affected by this configuration and group dsnDiag responses by first 60 characters to identify the dominant error patterns. A deferral rate above 5% at any single ISP warrants investigation; above 15% requires immediate volume reduction and configuration review.

The dlvSourceIp field in the accounting log enables per-IP analysis within this configuration context. Comparing per-IP deferral rates identifies whether a configuration issue affects all IPs in a pool uniformly (configuration problem) or just specific IPs (reputation or IP-specific problem). This distinction determines the correct remediation path.

Calibrating to Your Current Environment

The parameter values documented in this reference are appropriate for established, warmed IPs with HIGH reputation at the target ISP. New or warming IPs, and IPs with MEDIUM or LOW reputation, require more conservative values. Move up incrementally as reputation signals confirm the infrastructure can sustain additional throughput. Review ISP-specific configuration monthly — Postmaster Tools reputation tier changes and SNDS status changes are the primary triggers.

Production Deployment Summary

Implementing this PowerMTA configuration correctly in production requires testing the specific parameter values against your actual IP reputation history, ISP distribution, and sending volume. The values documented here represent proven starting points, not fixed constants — your optimal configuration may differ based on your infrastructure's operational history.

After applying any configuration change, monitor the accounting log for the first 2-4 hours to verify the change produced the expected effect on deferral rates. A configuration change that was expected to reduce deferrals but shows no change (or increased deferrals) indicates either: the change addressed the wrong variable, or there is a confounding factor that needs investigation before continuing.

The Cloud Server for Email infrastructure team manages PowerMTA environments daily, applying the configuration principles documented in this reference series across clients with varied volume levels, ISP distributions, and reputation histories. Contact us at infrastructure@cloudserverforemail.com for a technical assessment of your specific PowerMTA configuration requirements.