Demo
Demo

Knowledge base

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

retry-upon-new-mail

<domain>

Whether to try delivery right away when a new message arrives in a stalled queue
in the configuration this is a lineretry-upon-new-mail falseinside the block <domain>
Bypassing the schedule when a new message is submitted

A queue is in retry mode, waiting for the next attempt per retry-after. A new message is submitted to it. This line decides what happens: wait for the schedule — the vendor default false — or schedule an attempt immediately.

The point of enabling it lies in transactional mail. A message submitted just now is usually more important and fresher than what has been sitting in the queue for an hour; making it wait out the common pause means punishing the new message for the old one.

The point of disabling it lies in mailings. There submission flows continuously, and every new message resets the pause: the schedule stops existing, and the node contacts the receiver exactly as often as messages are submitted.

The main trap. On a continuous stream an enabled line cancels the retry schedule entirely. The receiver answered “come back later,” the queue stalled for half an hour — and immediately got a new message, and another, and another. Instead of a half-hour pause the receiver sees a continuous stream of attempts from a sender it has just asked to back off.
What the Hub does. It does not write it — the vendor’s false remains. For a mailing that is the right value: submission flows continuously, and bypassing the schedule here would mean having no schedule at all.
Recommended values

For mailings — only disabled. On a continuous stream enabling it is equivalent to giving up the retry schedule.

For transactional mail — it can be enabled, but only where submission is rare and one-off: an order confirmation, a login code. Such mail is sensibly handled by a separate VirtualMTA anyway — and then this line will not affect the mailing either.

Check it together with the rate. Bypassing the schedule does not cancel rate limits: the attempt will be scheduled immediately but will go out when max-msg-rate allows.

The split “disabled for mailings, can be enabled for transactional mail” is ours. From the manual here come the false default and the fact that when enabled a new message schedules delivery immediately.
Example configuration
# a mailing: the schedule must work
<domain *>
    retry-after 30m
</domain>

# a transactional stream: a fresh message does not wait for someone else's pause
<virtual-mta transactional>
    <domain *>
        retry-upon-new-mail true        retry-after 2m
    </domain>
</virtual-mta>
The separation by streams matters more here than the value itself: enabled in the general block, this line would reset the schedule for the mailing too.
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▶

Enabling it in the general block

§ 3.3.10.96

What it costsOn a submission stream the retry schedule stops working: every new message schedules an attempt immediately, and the receiver sees continuous pressure instead of the pause it asked for.
How to spot itThe queue is listed as being in retry mode, yet attempts go on constantly.
How to do it rightKeep false in the general block, enable it only inside a separate VirtualMTA for transactional mail.

Expecting a speed-up where the rate is the limit

our experience

What it costsBypassing the schedule schedules an attempt but does not raise ceilings. If the queue is stalled because of max-msg-rate, enabling it changes nothing, while the retry schedule is broken.
How to spot itThe line was enabled, and delivery did not speed up.
How to do it rightFirst look at what limits the queue: the retry schedule or the rate.
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
retry-upon-new-mail <boolean>
Values
yes or no; true and false are accepted on a par with them
Default
false § 3.3.10.96
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. A <domain> block can be nested in <virtual-mta> — then bypassing the schedule applies only in that stream. It is picked up by pmta reload.
⇄

Related directives

1 relation

Affects

retry-after<domain>The schedule this line bypasses: when enabled, a new message schedules an attempt without waiting for the pause. § 3.3.10.96

How to check on the node
The value is printed by the queue settings command; the result is visible from whether attempts match the schedule:
pmta show settings gmail.com/vmta1 | grep -i retry-upon-new-mail
pmta show queues --mode=retry --maxitems=20
If a queue is in retry mode while attempts happen more often than the schedule, this line is usually to blame. The Hub does not show such a discrepancy.
◇

What else to read

3 articles

◇Four value types the whole config is written inBoolean, domain pattern, regular expression and time interval — defined once in § 3.2 and then used by all directives.◇Two inbound report processors and what to do with themBounces by message and complaints are parsed by two identically structured blocks; each has its own address list and its own pair of decisions about the message’s fate.◇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
Cost of a mistake
reversible: harms only while it is set
Scenarios
Bounce classification · Tune the pace for a provider
Neighboring settings of the block <domain>:connect-timeoutauth-usernamecommandallow-cancel-during-transferassume-delivery-upon-data-termination-timeoutAll 135 directives of the block →