Contents
- Why domain blocks matter
- What a domain block is
- How PowerMTA matches domains to blocks
- Message rate limits versus connection limits
- The throttling directives
- The domain default block
- Per-ISP throttling values
- queue-to for ISP families
- Throttling and backoff interaction
- Why the ISP is the real bottleneck
- When throttling does not behave as configured
Why domain blocks matter
The major mailbox providers do not all accept mail the same way. Gmail, Yahoo, Microsoft, and the rest each have their own tolerances for how fast a sender may deliver, how many connections it may open, and how aggressively it may push. A sending pace Gmail accepts smoothly can trip Yahoo into throttling. A connection pattern fine for one receiver is wrong for another. PowerMTA's domain blocks are the mechanism by which an operator tunes delivery behavior to each receiver individually, rather than sending to everyone with one undifferentiated set of rules.
This guide exists because domain block throttling is one of the highest-leverage parts of a PowerMTA configuration: get it right and PowerMTA delivers smoothly within each receiver's tolerance, get it wrong and PowerMTA pushes receivers into throttling that caps the real delivery rate. The structure of this guide: what a domain block is, how PowerMTA matches recipient domains to blocks, the distinction between message rate limits and connection limits, the throttling directives in detail, the domain default block as the catch-all, per-ISP throttling values, the queue-to directive for ISP families, how throttling interacts with backoff, why the ISP and not PowerMTA is the real bottleneck, and the diagnostic workflow when throttling does not behave as configured.
What a domain block is
A domain block is a configuration section defining how PowerMTA delivers mail to a specific recipient domain. The most important content of a domain block is the throttling that controls the pace and aggressiveness of delivery to that domain.
A basic domain block:
<domain gmail.com>
max-msg-rate 3000/h
max-smtp-out 15
max-conn-rate 20/m
virtual-mta gmail-vmta
</domain>Inside the block, the operator sets directives governing delivery to that destination: the message rate limit, the connection limits, the retry behavior, the VMTA assignment, the smtp-pattern-list, and others. Everything between the opening domain tag and the closing tag applies specifically to the named recipient domain.
The value of per-domain blocks is precision: each block is tuned to one receiver's known characteristics. A complete configuration has a block for each major receiver the operator sends substantial volume to, each tuned appropriately, plus a default block for everything else.
How PowerMTA matches domains to blocks
PowerMTA matches each outbound message to a domain block by the message's recipient domain. A message addressed to someone at gmail.com is governed by the gmail.com domain block; a message to a yahoo.com address by the yahoo.com block.
The matching is by the domain part of the recipient address. This has a consequence operators must account for: a domain block named gmail.com matches gmail.com and nothing else. It does not match googlemail.com, a Gmail alias domain, and it does not match any other domain. If an operator wants googlemail.com mail governed by the same rules as gmail.com, the configuration must arrange that, either with a separate block or with the queue-to directive described below.
When a message's recipient domain matches no specific domain block, PowerMTA uses the domain default block. The default is the catch-all for every domain the operator has not written a specific block for.
The matching is exact and predictable: recipient domain to domain block, or to the default if no specific block matches. An operator who understands this knows exactly which block governs any given message, which is essential for both configuration and diagnosis.
Message rate limits versus connection limits
The throttling directives fall into two groups that control fundamentally different things, and an operator should understand the distinction before tuning either.
| Group | Controls | The question it answers |
|---|---|---|
| Message rate limit | Raw delivery throughput | How many messages per hour? |
| Connection limits | How throughput is spread over connections | How many connections, how fast? |
The message rate limit caps how many messages PowerMTA delivers to the domain per unit of time. It is the headline throttle, the control on raw sending pace.
The connection limits control how PowerMTA uses SMTP connections: how many simultaneous connections it opens to the domain, and how fast it opens new ones.
Both matter because ISPs evaluate both. A receiver cares how many messages arrive per hour, and it also cares how many connections a sender opens and how quickly. A sender that respects the message rate but opens too many connections too fast can still trigger throttling, because the connection pattern itself looks aggressive. Tuning only the message rate and ignoring the connection limits leaves half the throttling picture unmanaged.
The throttling directives
The specific throttling directives in a domain block:
| Directive | Controls | Example value |
|---|---|---|
| max-msg-rate | Messages per unit time to the domain | 3000/h |
| max-smtp-out | Simultaneous SMTP connections to the domain | 15 |
| max-conn-rate | Rate of opening new connections | 20/m |
| max-connections | Concurrent connection control | Set per receiver |
| max-msg-per-connection | Messages sent over one connection before reconnecting | Set per receiver |
max-msg-rate is the message rate cap, expressed as a count per time unit such as 3000/h. PowerMTA paces deliveries so the rate to the domain does not exceed this.
max-smtp-out caps the number of simultaneous SMTP connections PowerMTA opens to the domain. More connections allow more parallel delivery, but receivers limit how many connections they want from one sender.
max-conn-rate caps how fast PowerMTA opens new connections, expressed as a count per time unit such as 20/m. This prevents PowerMTA from opening a burst of connections all at once, which receivers can read as aggressive.
max-connections relates to the concurrent connection control, and max-msg-per-connection governs how many messages PowerMTA sends over a single connection before opening a fresh one; some receivers prefer connections be recycled after a certain number of messages.
The retry directives (retry-after, backoff-after, and related) and the routing directives (virtual-mta, virtual-mta-pool) and the smtp-pattern-list also live in the domain block, but the throttling core is max-msg-rate plus the connection limits.
The domain default block
The domain default block is the catch-all that governs every recipient domain without a specific block.
<domain default>
max-msg-rate 500/h
max-smtp-out 5
max-conn-rate 10/m
virtual-mta general-vmta
</domain>The default block is essential, and a configuration without one leaves unmatched domains to PowerMTA's built-in default handling, which may not be what the operator intends. Every complete configuration has an explicit domain default block.
The default block should be conservative. It governs a long tail of receiving domains the operator has not specifically tuned for, many of them smaller mail systems whose tolerances are unknown. A conservative default, a modest message rate, modest connection limits, sends to these unknown receivers at a pace unlikely to trigger problems. A default set too aggressively risks pushing some unknown small receiver into throttling or worse.
The relationship between the specific blocks and the default: the specific blocks handle the major receivers where the operator knows the tolerances and can tune precisely, the default handles everyone else conservatively. As the operator observes a particular non-major domain receiving meaningful volume, that domain can graduate to its own specific block.
Per-ISP throttling values
The right throttling values are ISP-specific, because the major receivers have different tolerances. The values also depend on the sender's reputation with each receiver, a well-established sender with good reputation can send faster than a new or troubled one.
| Receiver | Throttling character |
|---|---|
| Gmail | Tolerates substantial volume with good reputation; sensitive to engagement and complaints |
| Yahoo | Throttles aggressively; conservative rates and connection limits warranted |
| Microsoft | Tolerates reasonable volume; SNDS reputation governs |
| Default / unknown | Conservative across the board |
Gmail tolerates substantial volume from a sender with good reputation, but it weighs engagement and complaints heavily. The Gmail block can carry a reasonable message rate, adjusted to the sender's reputation.
Yahoo throttles aggressively and responds to volume increases sharply with its TSS codes. The Yahoo block warrants conservative rates and conservative connection limits, Yahoo is sensitive to too many connections in particular.
Microsoft tolerates a reasonable rate, with the SNDS reputation governing how much. The Microsoft block is tuned to the sender's SNDS standing.
The specific numbers are not universal constants; they depend on the sender's reputation and volume, and they should be tuned from observation. The starting point is conservative values, then the operator watches the accounting log for throttle codes and adjusts: if a receiver is not throttling and the queues are draining well, the rate can rise; if throttle codes appear, the rate is too high. Tuning the per-ISP values is an ongoing process of matching PowerMTA's pace to each receiver's observed tolerance.
queue-to for ISP families
Several mailbox providers operate families of recipient domains that share backend infrastructure, and these families should be throttled together. The queue-to directive collapses a family into a shared queue.
<domain yahoo.com>
max-msg-rate 2500/h
max-smtp-out 5
virtual-mta yahoo-vmta
</domain>
<domain ymail.com> { queue-to yahoo.com }
<domain aol.com> { queue-to yahoo.com }
<domain comcast.net> { queue-to yahoo.com }With queue-to, mail to ymail.com, aol.com, and comcast.net all routes into the yahoo.com queue, sharing the yahoo.com block's throttling, VMTA, and retry behavior. PowerMTA accounts for the whole family together.
This matters because the ISP evaluates the family together. The Yahoo infrastructure handles the whole Yahoo family, so the sender's pace to Yahoo is what Yahoo sees across all those domains combined. Throttling each Yahoo-family domain separately would let the combined rate exceed what Yahoo tolerates, even if each individual domain block looked conservative. Collapsing the family with queue-to makes the throttling reflect the reality that Yahoo sees one combined stream.
The major families to collapse: the Yahoo family (yahoo.com, ymail.com, aol.com, and after the 2025 consolidation comcast.net and the AT&T domains att.net, sbcglobal.net, bellsouth.net), and the Microsoft family (hotmail.com, outlook.com, live.com, msn.com). The queue-to target's domain block carries the throttling and the rest of the family inherits it.
Throttling and backoff interaction
Domain block throttling and PowerMTA's backoff mechanism work together, and the relationship is worth understanding.
The domain block throttling sets the intended sending pace, the rate PowerMTA aims for when things are going well. Backoff is what happens when a receiver throttles anyway: PowerMTA detects the throttling (the 4xx deferrals, the throttle codes) and puts the queue into backoff mode, slowing to a more cautious retry pace below the configured rate.
So the configured max-msg-rate is the pace PowerMTA targets, and backoff is the automatic reduction below that pace when a receiver signals it wants less. A well-tuned domain block sets a rate the receiver accepts, so backoff rarely triggers; a domain block with the rate too high pushes the receiver into throttling, backoff triggers frequently, and the effective rate ends up the backoff rate rather than the configured rate.
This is the feedback that tuning relies on. If a domain's queue is frequently in backoff, the domain block's rate is set higher than the receiver tolerates, and the rate should come down. If a domain's queue rarely or never enters backoff and is draining well, there may be room to raise the rate. Backoff frequency is a direct signal about whether the domain block throttling matches the receiver's tolerance.
Why the ISP is the real bottleneck
A foundational point about throttling: the ISP, not PowerMTA, is the real bottleneck for high-volume sending.
PowerMTA itself can deliver enormous volumes; on capable hardware it is not the limiting factor. But PowerMTA delivers to receivers, and each receiver accepts mail from a given sender at a pace governed by that sender's reputation and the receiver's own policies. Push faster than the receiver wants, and the receiver throttles, deferring mail with 4xx codes, which caps the effective delivery rate regardless of how fast PowerMTA could theoretically send.
There is a tempting but wrong intuition that setting max-msg-rate higher makes mail deliver faster. Above the rate a receiver tolerates, the opposite happens. A domain block rate set above the receiver's tolerance pushes the receiver into throttling, the queue enters backoff, and the effective delivery rate drops to the backoff pace, which is lower than a correctly conservative configured rate would have achieved. The configured rate is not a target to maximize; it is a setting to match to the receiver's actual tolerance. The fastest real delivery comes from a rate the receiver accepts smoothly, not from the highest number the operator can type into max-msg-rate.
This is why domain block throttling exists and why tuning it matters. The throttling directives are not there to constrain PowerMTA for its own sake; they are there to keep PowerMTA's pace within what each receiver will accept. The art of tuning domain blocks is matching the configured rates to the ISPs' acceptance, which depends on the sender's reputation with each receiver. The ISPs set the real ceiling; the domain block configuration is the operator's tool for sending right up to that ceiling without crashing into it.
When throttling does not behave as configured
When domain block throttling does not behave as expected, the diagnostic workflow:
Step 1: confirm which block governs the mail. Verify the recipient domain matches the domain block the operator thinks governs it. A common surprise is mail to a domain variant (googlemail.com when only gmail.com has a block) falling to the default block instead of the intended specific block.
Step 2: check the queue-to chain. If the domain uses queue-to, the throttling comes from the queue-to target's block, not the domain's own block. Verify the chain leads to the intended block with the intended throttling.
Step 3: verify the configured values took effect. Run pmta show settings after any config change to confirm the throttling values are what the operator set. A config that parsed is not guaranteed to apply exactly as intended.
Step 4: check whether the queue is in backoff. If the effective rate is below the configured rate, the queue may be in backoff because the receiver is throttling. Run pmta show queues and look for BACKOFF status. A queue in backoff is sending below the configured rate by design.
Step 5: check the accounting log for throttle codes. If the queue is in backoff, the accounting dsnDiag shows the receiver's throttle codes. This confirms the receiver is throttling and tells which condition (TSS04, S3140, a Gmail rate phrase).
Step 6: assess whether the rate is too high. Frequent backoff and throttle codes mean the domain block rate is set above the receiver's tolerance. The fix is to lower the rate, and the connection limits if those are also too aggressive, to a level the receiver accepts.
Step 7: check the connection limits, not just the rate. If the message rate seems reasonable but the receiver still throttles, the connection limits may be the problem, too many connections or opening them too fast. Tighten max-smtp-out and max-conn-rate.
Step 8: reload and observe. After adjusting, pmta reload to apply, then watch the accounting log and the backoff behavior to confirm the new values match the receiver's tolerance.
An operator we worked with had carefully tuned a domain block for a major receiver: a sensible message rate, conservative connection limits, the result of real observation and adjustment over time. Yet that receiver kept throttling their mail, and the operator could not understand why, the rates were demonstrably conservative. They spent time lowering the rates further, with no improvement, the throttling persisted even at rates that should have been far below any reasonable tolerance. The cause turned out to be a domain-matching problem. The receiver in question operated a family of domains, and the operator had written a specific, carefully tuned block for the primary domain of the family but had not used queue-to to bring the rest of the family onto that block. So mail to the primary domain was governed by the conservative tuned block, but mail to the other domains of the same family fell through to the domain default block, which had a much higher rate. The receiver's infrastructure handled the whole family together, so what the receiver saw was the combined stream: the conservative rate to the primary domain plus the much higher default-block rate to all the family's other domains. The combined pace was well above the receiver's tolerance, and the receiver throttled the whole sender. The carefully tuned block was working perfectly, it just only governed a fraction of the mail the receiver actually attributed to the sender. The fix was to add queue-to directives bringing the entire family onto the tuned block, so the whole family shared the conservative throttling. Once the family was collapsed, the receiver saw a combined stream within its tolerance, and the throttling stopped. The lesson is the diagnostic step about confirming which block governs the mail and checking the queue-to chain. A perfectly tuned domain block delivers nothing if the mail is not actually matching it, and for ISP families, the family must be collapsed with queue-to or the receiver sees a combined rate the operator never intended to send.
PowerMTA domain blocks are where an operator tunes delivery to each receiver's individual tolerance, and the throttling directives within them are among the highest-leverage settings in the configuration. The core throttling is the message rate limit plus the connection limits, two groups controlling different things, both of which receivers evaluate. The domain default block catches everything without a specific block and should be conservative. Per-ISP values are tuned from observation, with backoff frequency as the feedback signal. The queue-to directive collapses ISP families so the throttling reflects the combined stream the receiver actually sees. And the foundational truth is that the ISP, not PowerMTA, sets the real ceiling: the fastest delivery comes from rates matched to each receiver's tolerance, not from the highest numbers the operator can configure. Operators who write specific blocks for their major receivers, collapse the families with queue-to, set a conservative default, and tune from the backoff feedback, get PowerMTA delivering smoothly at each receiver's real capacity; operators who set rates too high, or leave family domains falling to an aggressive default, push their receivers into the throttling that caps their delivery below what careful tuning would have achieved.