PowerMTA Domain Block Configuration Reference: Complete 2026 Operator Guide

Why this reference exists

PowerMTA's reputation as a precision delivery engine rests almost entirely on the domain block. The domain block is the configuration construct where operators express "this is how I want PowerMTA to behave when delivering to this specific recipient domain" and the granularity available inside the block is the substantive difference between PowerMTA and most other MTAs. Postfix has nothing comparable in its native configuration; Exim requires elaborate router and transport chains to approximate the same controls; only KumoMTA and a handful of other commercial MTAs (MailerQ, Halon, GreenArrow) match PowerMTA's per-destination expressiveness.

This reference exists because the official Bird documentation lists the directives but rarely shows the production patterns operators actually deploy, and operators reach for domain block configuration most often during throttling incidents when documentation reading time is at a premium. The structure: a quick anatomy of how a domain block fits into the broader config, then each significant directive group, then the queue-to pattern that handles Microsoft and Apple domain proliferation, then production-tested configurations for Gmail, Outlook, Yahoo, iCloud, then the diagnostic workflow operators run when 421 throttling errors start appearing.

Verified against PowerMTA 5.5 and 5.6 documentation as of early 2026. The configuration syntax has been stable across the 5.x line. Specific features added in 4.5 (per-IP rate limiting via source-ip-max-msg-rate and source-ip-max-connect-rate) are noted where relevant.

Anatomy of a domain block

A domain block is a configuration container declared in /etc/pmta/config that holds delivery directives for one specific recipient domain. The basic syntax:

domain gmail.com {
    max-msg-rate 1000/h
    max-conn-rate 20/m
    max-smtp-out 10
    retry-after 10m
    backoff-retry 30m
}

This block tells PowerMTA: when delivering to gmail.com, attempt at most 1000 messages per hour, open at most 20 new connections per minute, hold at most 10 concurrent SMTP connections open at any moment, wait 10 minutes before retrying transient failures, and shift to a 30-minute retry interval when the domain enters backoff mode after sustained errors.

Domain blocks are read top to bottom and the first matching block applies. PowerMTA also supports wildcards (domain *.gmail.com) and the special domain default block that catches anything not matched by a more specific block. The order matters: more specific blocks should appear before more general ones to ensure the right block matches.

Domain blocks can inherit from other domain blocks using the like directive, which is useful when many related domains share most policies but differ in a few specifics. The queue-to directive (covered separately below) redirects messages for one domain into another domain's queue, which is the standard pattern for collapsing related domains.

Rate limiting directives

Rate limiting controls how fast PowerMTA attempts to deliver to a domain. The three time bases (per-second, per-minute, per-hour) cover different needs and operators typically use one or two together.

Directive	Meaning	Example
max-msg-rate N/s	Maximum messages per second	max-msg-rate 5/s
max-msg-rate N/m	Maximum messages per minute	max-msg-rate 100/m
max-msg-rate N/h	Maximum messages per hour	max-msg-rate 5000/h

Operators frequently combine per-minute and per-hour limits to control both burst behavior and sustained rate. A configuration like max-msg-rate 100/m plus max-msg-rate 5000/h caps bursts at 100/minute but limits total sustained rate to 5000/hour, which is more sender-reputation-friendly than allowing 100/minute sustained (which would equal 6000/hour and exceed the per-hour cap quickly).

The per-second limit is most useful for ISPs with extremely tight per-connection limits or for testing scenarios where deterministic message pacing matters. Most production configurations use per-minute and per-hour primarily.

Connection control directives

Connection limits control how PowerMTA opens and maintains SMTP connections to the receiving MTA. The directives:

Directive	Meaning	Typical range
max-conn-rate N/m	Maximum new connections per minute	5-50/m
max-smtp-out N	Maximum concurrent connections	2-20
max-conn-msgs N	Max messages per connection before disconnect	50-500
conn-life-time N	Maximum connection lifetime	5m-30m

The most important is max-smtp-out, which controls concurrent connection count. Receiving MTAs typically reject when concurrent connections from a single sender IP exceed their threshold (Microsoft particularly enforces this), so setting max-smtp-out too high produces "exceeded the connection limit" errors. The correlation that matters most is concurrent connections, not connection rate, despite what intuition suggests. Operators investigating connection-limit errors should adjust max-smtp-out downward before adjusting max-conn-rate.

A conservative starting point for unfamiliar destinations: max-smtp-out 5, max-conn-rate 10/m, conn-life-time 10m. These values rarely cause problems and can be tuned upward as data accumulates. Aggressive values like max-smtp-out 30 are appropriate only for destinations known to accept high concurrency (Gmail, large transactional providers) on properly warmed IPs with established reputation.

Retry and backoff policies

Retry and backoff control how PowerMTA handles transient failures. The default behavior retries with increasing delays for up to 5 days before giving up; operators tune this to match the specific destination's behavior.

Directive	Meaning	Typical value
retry-after N	Initial wait before first retry	5m-15m
backoff-retry N	Wait when in backoff mode	30m-2h
backoff-after N errors	Enter backoff after N consecutive errors	5-20
retry-max-time N	Give up after this total elapsed time	2d-5d
retry-sequence list	Exponential retry sequence (PowerMTA 4.5+)	5m,10m,30m,1h,4h

The retry-sequence directive introduced in PowerMTA 4.5 lets operators specify exponential retry intervals directly rather than relying on PowerMTA's built-in linear retry. The example sequence 5m,10m,30m,1h,4h means: first retry after 5 minutes, second after another 10 minutes, third after 30 more minutes, fourth after an hour, fifth after 4 hours. This pattern matches receiving MTA behavior better than fixed intervals because the likelihood of delivery success decreases over time and aggressive early retries are more valuable than aggressive late retries.

Per-IP throttling added in 4.5

PowerMTA 4.5 introduced two directives that let operators throttle per source IP rather than per VirtualMTA. This matters when a single VMTA contains multiple IPs and each IP needs independent throttling to the same destination domain.

Directive	Meaning
source-ip-max-msg-rate N/h	Per-IP message rate within the VMTA
source-ip-max-connect-rate N/m	Per-IP connection rate within the VMTA

The use case: a VirtualMTA contains 5 IPs in round-robin rotation, and the operator wants each IP individually limited to 200/h to Gmail (total 1000/h across the VMTA). Without per-IP throttling, max-msg-rate 1000/h would apply to the VMTA as a whole and would not prevent one IP from getting most of the volume if the rotation drifted. With source-ip-max-msg-rate 200/h, each IP is capped independently regardless of rotation behavior.

The per-IP directives complement (not replace) the per-VMTA directives. The intended pattern is both: max-msg-rate 1000/h limits VMTA total, source-ip-max-msg-rate 200/h limits each IP within the VMTA. PowerMTA enforces both and the more restrictive applies at any moment.

The queue-to pattern for collapsing domains

Microsoft operates dozens of related domains (hotmail.com, hotmail.co.uk, hotmail.de, live.com, live.nl, live.be, msn.com, outlook.com, outlook.de, and many more) all delivered to the same mail servers. PowerMTA's default behavior creates a separate queue per recipient domain, which means each Microsoft variant gets its own throttling counters. Microsoft's reputation systems look at all traffic from a sender IP regardless of recipient domain, so per-domain throttling does not match the reputation reality.

The solution: the queue-to directive collapses related domains into a single queue. The pattern:

domain hotmail.com {
    max-msg-rate 5000/h
    max-conn-rate 10/m
    max-smtp-out 5
    retry-after 15m
    backoff-retry 1h
}

domain hotmail.co.uk { queue-to hotmail.com }
domain hotmail.de    { queue-to hotmail.com }
domain hotmail.fr    { queue-to hotmail.com }
domain live.com      { queue-to hotmail.com }
domain live.co.uk    { queue-to hotmail.com }
domain live.de       { queue-to hotmail.com }
domain live.nl       { queue-to hotmail.com }
domain live.be       { queue-to hotmail.com }
domain msn.com       { queue-to hotmail.com }
domain outlook.com   { queue-to hotmail.com }
domain outlook.co.uk { queue-to hotmail.com }
domain outlook.de    { queue-to hotmail.com }
domain outlook.fr    { queue-to hotmail.com }

All messages flow through the hotmail.com queue regardless of recipient variant. The unified throttling counters correspond to what Microsoft actually sees from the sender IP, and Microsoft's reputation thresholds become predictable.

The queue-to directive is technically undocumented in the standard PowerMTA manual but is well known in the operator community and is the standard pattern for handling Microsoft's domain proliferation. Similar patterns apply to Yahoo (yahoo.com, ymail.com, rocketmail.com, yahoo.co.uk, yahoo.fr, etc.) and Apple iCloud (icloud.com, me.com, mac.com).

smtp-pattern-list for ISP-specific detection

The smtp-pattern-list directive lets operators define response patterns that trigger specific behaviors when the receiving MTA returns matching responses. The classic use case is automatic backoff when ISP returns specific throttling indicators.

<smtp-pattern-list name="ms-throttle">
    pattern "S3140"        backoff
    pattern "S3150"        backoff
    pattern "OU-002"       backoff
</smtp-pattern-list>

<smtp-pattern-list name="gmail-throttle">
    pattern "421-4.7.0 [.*] Our system has detected"  backoff
    pattern "421-4.7.28"                              backoff
</smtp-pattern-list>

<smtp-pattern-list name="yahoo-tss">
    pattern "TSS04"        backoff
</smtp-pattern-list>

domain hotmail.com {
    max-msg-rate 5000/h
    smtp-pattern-list ms-throttle
}

domain gmail.com {
    max-msg-rate 3000/h
    smtp-pattern-list gmail-throttle
}

domain yahoo.com {
    max-msg-rate 2000/h
    smtp-pattern-list yahoo-tss
}

This configuration tells PowerMTA: when delivering to hotmail.com, watch for Microsoft's S3140, S3150, or OU-002 in responses and enter backoff mode when detected; similar patterns for Gmail's 421-4.7.0 and 421-4.7.28 codes and Yahoo's TSS04. The backoff behavior is automatic and prevents PowerMTA from continuing to hammer a destination that is signaling throttling.

The pattern matching is substring against the dsnDiag field. Operators frequently expand these lists as they encounter new patterns in their accounting logs and want automatic response to recurring throttling signals.

Production configurations by ISP

The following configurations are starting points for warm dedicated IPs delivering legitimate marketing email to engaged subscribers. Adjust based on actual accounting data and IP reputation state.

Gmail (and Google Workspace).

domain gmail.com {
    max-msg-rate 3000/h
    max-msg-rate 100/m
    max-conn-rate 20/m
    max-smtp-out 15
    retry-after 10m
    backoff-retry 30m
    backoff-after 10 errors
    smtp-pattern-list gmail-throttle
}

domain googlemail.com { queue-to gmail.com }

Microsoft Outlook/Hotmail/Live/MSN.

domain hotmail.com {
    max-msg-rate 5000/h
    max-msg-rate 150/m
    max-conn-rate 10/m
    max-smtp-out 5
    retry-after 15m
    backoff-retry 1h
    backoff-after 5 errors
    smtp-pattern-list ms-throttle
}

domain outlook.com { queue-to hotmail.com }
domain live.com    { queue-to hotmail.com }
domain msn.com     { queue-to hotmail.com }
# ... all other Microsoft variants ...

Yahoo (and Verizon Media variants).

domain yahoo.com {
    max-msg-rate 2500/h
    max-msg-rate 75/m
    max-conn-rate 15/m
    max-smtp-out 5
    retry-after 15m
    backoff-retry 1h
    backoff-after 5 errors
    smtp-pattern-list yahoo-tss
}

domain ymail.com      { queue-to yahoo.com }
domain rocketmail.com { queue-to yahoo.com }
domain aol.com        { queue-to yahoo.com }

Apple iCloud.

domain icloud.com {
    max-msg-rate 2000/h
    max-msg-rate 50/m
    max-conn-rate 10/m
    max-smtp-out 5
    retry-after 20m
    backoff-retry 2h
    backoff-after 3 errors
}

domain me.com  { queue-to icloud.com }
domain mac.com { queue-to icloud.com }

Default block for unknown destinations.

domain default {
    max-msg-rate 500/h
    max-conn-rate 5/m
    max-smtp-out 3
    retry-after 15m
    backoff-retry 1h
    backoff-after 10 errors
}

The default block is conservative because unknown destinations might be small servers that cannot handle aggressive sending. Operators with substantial traffic to corporate B2B destinations may want a separate "corporate" pattern matching common business mail server hostnames rather than relying on the default.

Diagnostic workflow when throttling appears

When 421 throttling errors start appearing in accounting logs, the diagnostic workflow follows a predictable pattern:

Step 1: identify the affected destination. Query accounting logs for t records grouped by destination domain over the past hour. The domain with the spike is the suspect.

Step 2: identify the specific throttling response. Look at dsnDiag for the affected records. Patterns like TSS04 (Yahoo complaints), S3140 (Microsoft spam), 421-4.7.0 (Gmail volume), or destination-specific codes tell you what ISP is reporting.

Step 3: identify the affected source IP. Query the same records by coalesce(dlvProxyServerIp, dlvSourceIp) to find which outbound IP is being throttled. If multiple IPs in a VMTA are affected, the issue is reputation-wide; if only one IP, the issue is IP-specific.

Step 4: assess severity. Calculate the ratio of throttled to attempted deliveries over the past hour. Under 1% is noise; 1-5% is concerning; 5-20% is active throttling; over 20% is reputation crisis requiring immediate action.

Step 5: adjust throttling. Reduce the max-msg-rate for the affected domain by 30-50% as immediate response. If the response code suggests reputation rather than rate (TSS04, S3140), additionally reduce by another 30% and investigate complaint rates separately.

Step 6: monitor recovery. Watch transient rate over next 2-4 hours. Successful recovery shows transient rate dropping below 1% and delivery rate stable. Failed recovery shows transient rate flat or rising, indicating reputation issue rather than rate issue, requiring deeper investigation into list quality, content, or authentication.

Step 7: document and adjust permanent config. If the throttling was rate-induced and reducing max-msg-rate resolved it, the new lower rate becomes the permanent baseline. If the throttling was reputation-induced, address the underlying cause and gradually increase rate back to baseline over 1-2 weeks.

This reference covers the substantive PowerMTA domain block directives operators reach for in production. The configuration syntax is stable across PowerMTA 5.x and the patterns generalize to ISP throttling behavior more broadly. Operators running KumoMTA can apply the same conceptual patterns through Lua-based configuration with different syntax but identical operational outcomes.