Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.51

backoff-notify

<domain>set by the Hub

Whom to notify when a queue enters or leaves backoff
in the configuration this is a linebackoff-notifyinside the block <domain>
How to find out that a queue has slowed down

A comma-separated list of addresses the engine writes to when any of this receiver’s queues enters or leaves backoff mode. Both events, with no choice.

Why. Going into backoff is neither an error nor a failure: the queue simply starts working under different limits. Nothing changes in the configuration, the process is alive, messages flow. It can be noticed by the dropped rate — that is, well after the event. The message arrives immediately.

Per domain, not per queue. The notification concerns the receiver, and it has as many queues as there are sending addresses. If three queues go into backoff in a row, there will be three messages.

An empty string clears the inherited value. “” in a specific block cancels the value from the general one.

The main trap. The notification goes out through the same node that is currently having delivery problems. If the notification recipient lives on the same domain as the slowed-down queue, the message will join that very queue and arrive together with the rest — that is, when it is no longer needed. The addressee must be on a third-party domain.
What the Hub does. It writes it — conditionally: the line appears for a receiver only when a notification address is set for the node. If it is not set, there is no line at all, and that is intentional: an address leading nowhere is worse than no line.

A duplicate channel is not superfluous here. The Hub picks up queue modes by polling the node and shows them in monitoring, but the message from the engine arrives at the moment of the event — and will arrive even when polling did not go through that minute.

Recommended values

Set it in the general block. The event is of interest for any receiver, not for selected ones.

The addressee should be on a third-party domain. Otherwise the message will go into the very queue it reports on.

Be ready for pairs. Every entry comes with an exit: if a queue “breathes” — goes into backoff and returns several times a day — there will be twice as many messages as events. That is a sign you need to deal not with notifications but with limits.

The addressee requirements and the note about pairs are ours. From the manual here are the list format, clearing with an empty string and the fact that a message arrives for both events.
Example configuration
# an event about any receiver — so the general block
<domain *>
    backoff-notify ops@example.net,dev@example.net    backoff-to-normal-after 1h
</domain>
The notification domain is deliberately a different one. The second line is there for a reason: without it the queue may stay in backoff for a long time, and the second message — about the exit — will never arrive.
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 ends2 mistakes▶

Specifying a mailbox on the same domain you send to

our experience

What it costsThe notification about a slowed-down queue lands in that same queue and goes out under its limits — that is, slowly. The point of an early warning is completely lost.
How to spot itThere are queues in backoff, and the messages arrive very late or not at all.
How to do it rightA mailbox on a third-party domain that the node delivers at a normal rate.

Expecting messages only about the problem

§ 3.3.10.51

What it costsA message also arrives on leaving the mode. On a fleet where queues regularly enter and leave, the flow doubles, and people quickly stop reading the notifications.
How to spot itThe mailbox is flooded with “entered — left” pairs for the same receivers.
How to do it rightThis is a signal not about notifications but about limits: a queue that “breathes” is set too close to the receiving server’s threshold.
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.
Reference data
Syntax
backoff-notify <email-list>
Values
comma-separated addresses; an empty string clears the inherited value
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The value merges across <domain> blocks from general to specific: the best-matching block wins, not the last one in the file. An empty string “” clears the inherited value — otherwise there would be no way to cancel a general value in a specific block. It is picked up by pmta reload; no restart is needed.
⇄

Related directives

2 relations

Applies to

Backoff mode — the queue's second personalityThe event the message is about: entering backoff mode and leaving it. § 3.3.10.51

Often used with

The watchdog that restarts the engineA second channel for learning that something is wrong: the watchdog watches the engine itself, the notification watches queue behavior. § 2.3

How to check on the node
The line is checked by reading the configuration, and for real — by an event. Queue modes are visible separately:
grep -rn backoff-notify /etc/pmta/
pmta show queues --mode=backoff
The second command shows the queues currently in backoff mode. If there are some but no messages arrived, check the addressee: most likely it is on the same domain, and the message is sitting in that same queue.
◇

What else to read

3 articles

◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.◇The watchdog that restarts the engineKeeps an eye on the engine and brings it back up after a crash by itself, sending a crash report to the postmaster address.◇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.

In the Hub
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Troubleshoot deliverability
Neighboring settings of the block <domain>:disabled-source-ip-notifymax-events-recordedtrack-recipient-eventsdisable-acct-recordsdkim-signAll 135 directives of the block →