Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 3.3.10.41

Backoff mode — the queue's second personality

critical

backoff mode
Not an emergency brake but a second set of settings

Every queue has two states. In the normal one the usual limits apply; in backoff their twins apply — separate directives with the backoff- prefix. Everything essential has a twin: the message rate, the data volume, the connection rate, the number of connections and the retry schedule.

A queue is a “receiving server plus sending address” pair. The mode switches on for the pair, not for the domain: gmail.com from one address can be in backoff mode while from another it is in normal mode.

The mode does not switch on by itself. Entry happens when the receiving server’s reply matches a pattern from <smtp-pattern-list> that carries the mode=backoff action. No pattern list, no entry: the mechanism is present but inert. The manual walks through this with its own example of an AOL error list.

What happens on entry. Everything that is configured: a notification message (backoff-notify), a different retry schedule (backoff-retry-after), a lowered pace (backoff-max-msg-rate) and, if set, rerouting messages to another sending address (backoff-reroute-to-virtual-mta).

Rerouting is the strongest of these measures. Messages move to the queue of the same receiving server but a different address, and from then on that address’s settings apply in full. New messages go there too while the original queue is in backoff mode. Chains are supported: one address diverts to a second, the second to a third. The engine detects loops by itself and silently ignores the rerouting.

Exit is configured separately — and by default it is not configured at all.

The main trap is entry without exit. Both return conditions are off by default: backoff-to-normal-after is never, backoff-to-normal-after-delivery is false. A queue that has entered backoff mode stays in it indefinitely — until the pmta set queue –mode=normal command, until a pattern with mode=normal matches, or until the engine restarts. The manual warns about this separately where it suggests enabling the mode when all of a source’s addresses are disabled: addresses that come back will not lift the mode by themselves.
What the Hub does. It writes the full backoff mode set from the node preset — four lines always and three depending on circumstances. For the “Balanced” preset these are:

backoff-max-msg-rate 5/h · backoff-retry-after 1h,3h,6h,12h · backoff-to-normal-after 1h · backoff-to-normal-after-delivery yes; plus backoff-max-smtp-out 2, backoff-notify and rerouting to a backup address when those are set. None of these lines is written for addresses under warm-up.

Both return conditions are enabled on purpose — for us backoff mode means “almost stop and wait,” not “freeze forever.”

The Hub generates the backup address itself — as a separate block with a suffix in its name, and rerouting to it works only because the domain’s SPF allows all of the node’s addresses in advance. Otherwise the rerouted messages would leave from an address that is not in the SPF record.

🔴 What is unresolved. Inside the node the mode is managed by the engine — it reacts right in the connection. Outside, the Hub’s scheduler does the same job, but from telemetry that arrives seconds and minutes later. Which of them is in charge when both have fired is not defined — this is a question about the product’s design, not about the configuration.

Recommended values

The mode has no values of its own — the twin directives set them. What matters is not which numbers to pick but the fact that each of them defaults to the normal value:

Twin Default What it means in practice
backoff-max-msg-rate same as the normal rate without its own line the mode is no slower than normal
backoff-retry-after same as the normal schedule retries are not spaced out
backoff-max-smtp-out 20 as many connections as before
backoff-to-normal-after never no way out
backoff-to-normal-after-delivery false no way out

Hence the rule: set twins in pairs with an exit. A set made of one lowered rate with no return condition is a queue that has slowed down forever. The Hub’s presets set both return conditions and lower the rate sharply: in “Balanced” it is 5/h versus 10/m in normal mode.

Backoff mode is not the same as retry mode. The manual says so directly: a queue that has gone into backoff mode does not go into retry mode automatically. If you need both, the pattern list has a separate defer-queue action.

The “set in pairs with an exit” rule and our numbers come from the Hub’s practice. From the manual here are the set of twins, all the defaults, the entry condition through the pattern list, the rerouting behavior with loop detection, and the warning that returning addresses do not lift the mode.
Example configuration
# entry — by pattern; exit — by two conditions; both are required
<smtp-pattern-list block-errors>
    reply /^421 .* too many errors/ mode=backoff</smtp-pattern-list>
<virtual-mta mta-news-1>
    <domain *>
        smtp-pattern-list block-errors
        max-msg-rate 500/h
        backoff-max-msg-rate 1/h
        backoff-to-normal-after 1h
        backoff-to-normal-after-delivery yes
        backoff-reroute-to-virtual-mta mta-news-1-backoff-vmta
    </domain>
</virtual-mta>
The highlighted line is the only thing that switches the mode on at all: without it all the lines below stay dead. The two return lines are not a formality either: without them the queue stays in backoff mode until the engine is restarted.
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 ends4 mistakes▶

Configuring the entry and forgetting the exit

§ 3.3.10.53

What it costsBoth return conditions are off by default. The queue enters backoff mode and stays there indefinitely — until a manual command or an engine restart. The receiving server stopped refusing long ago, yet sending to it goes on at the lowered rate for weeks.
How to spot itThe queue shows as in backoff mode for months, the receiving server is not refusing, and the rate has stayed lowered.
How to do it rightSet backoff-to-normal-after and backoff-to-normal-after-delivery together with any twin. Check the queue mode in the node summary, not only by the refusals.

Writing twins without creating a pattern list

§ 11.5.2

What it costsThe mode switches on only when the receiving server’s reply matches a pattern that carries the entry action. Without a pattern list no prefixed line will ever fire — the configuration looks set up and does nothing.
How to spot itThe receiver block has the full set of twins, yet the queue has never once been in backoff mode.
How to do it rightCreate a <smtp-pattern-list> with the receiving server’s replies and the entry action, and reference it from the receiver block with a smtp-pattern-list line.

Leaving a twin unset, relying on the mode being “gentle”

§ 3.3.10.41

What it costsEach twin defaults to its normal value: the rate equals the normal rate, the schedule the normal schedule, connections are twenty. The mode switches, but the behavior changes in no way at all — the queue keeps pushing at the receiving server exactly when it asked to ease off.
How to spot itThe queue is in backoff mode, the share of refusals is the same, the rate is unchanged.
How to do it rightSet the twins explicitly and noticeably below the normal values. Compare the pairs with the queue settings command: normal and backoff being equal is exactly what means there is no line of its own.

Rerouting the queue to an address without configuring it

§ 3.3.10.59

What it costsAfter rerouting, the settings of the new address apply entirely, not the ones inherited from the original. A reroute target that has neither a source nor a signing key will send messages from the wrong IP and unsigned — precisely when the reputation has already suffered.
How to spot itOnce the queue enters backoff mode, messages leave from a different IP or arrive unsigned.
How to do it rightConfigure the backup address as a full-fledged one. And remember SPF: rerouting works only if the domain’s record allows all of the node’s addresses.
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.
Inheritance
The twin directives live in the receiver block and merge by the usual rule: from the general pattern to the exact one, and across levels — node, pool, sending address — where the narrowest is strongest. The mode itself is not inherited: it is the state of a specific queue, and a queue is a pair of receiving server and address. Rerouted messages land in another address’s queue and obey its settings entirely, not the ones inherited from the original.
⇄

Related entries

3 relations

Does not work without

backoff-to-normal-after<domain>The exit condition: without it the mode does not end on its own, and the manual warns about this separately. § 3.3.10.55

Depends on

Parsing receiver responsesThe only thing that switches the mode on: an action on a match of the receiving server’s reply. § 3.3.10.53

Applies to

How the policy for a receiver is assembledBackoff mode settings merge per receiver just like all the others. § 3.3.10

Referenced from

Four ways to say “slower”Each limit has a twin that replaces it while the queue is in backoff mode. § 3.3.10.41max-errors-per-connection<domain>Repeated errors are what backoff mode exists for; breaking the connection does not replace it. § 3.3.10.1bounce-after<domain>Backoff mode slows down retries but does not extend the deadline: a queue in backoff keeps the same amount of time and gets fewer attempts. § 3.3.10.10backoff-max-msg-rate<domain>The mode in which this value applies instead of the normal one. § 3.3.10.41backoff-max-data-volume-rate<domain>The mode in which this value applies instead of the normal one. § 3.3.10.45backoff-max-connect-rate<domain>The mode in which this value applies instead of the normal one. § 3.3.10.95

How to check on the node
A queue’s mode shows in the summary, and its settings in the queue settings:
pmta show queues
pmta show settings gmail.com/mta-news-1
pmta set queue --mode=normal gmail.com
The first prints queues with their mode — the web monitor can filter by it as well. The second shows all lines with the backoff prefix and lets you compare them with the normal ones: if they match, backoff mode will change nothing. The third returns the queue to normal mode by hand — the very command you have to use when no exit conditions are set.
◇

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.◇How the node responds to the receiving server's wordsMatches SMTP replies against regular expressions and changes the queue mode on a match — the very trigger that all of the backoff mode machinery waits for.◇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 · Sending address rotation · Tune the pace for a provider
Priority
critical