Demo
Demo

Knowledge base

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

reroute-to-virtual-mta

<domain>

Move this recipient domain's messages to a different sending address
in the configuration this is a linereroute-to-virtual-mtainside the block <domain>
Change the sending address without touching the queue

A PowerMTA queue is a “recipient domain + sending address” pair. This line changes the second half: messages for the specified recipient domain go out through a different VirtualMTA or through a whole pool. The recipient is the same, the sender is different.

The optional after= clause delays the reroute. The message will leave through the original address, and only after sitting in the queue for the specified time (at least a minute) will it move to the new one. This gives the original address a chance and switches only when it has not coped.

The line can also be set at the node level — then it applies to everything for which it is not overridden. An empty string (“”) removes the inherited value.

The main trap is that a loop is ignored silently. The node checks the whole reroute chain, and if it closes on itself, the reroute simply is not performed: messages stay in the original queue. No error when parsing the configuration, no log entry. Rerouting an address to itself is also a loop, and it is also quietly ignored. For a pool, only the closed paths are excluded; the rest work.
What the Hub does. It writes — not this line, but its backoff twin backoff-reroute-to-virtual-mta: a reroute to a backup address where the queue has gone into backoff mode. The Hub does not set a regular, unconditional reroute: for it this is a decision based on the queue’s state, not its name.
Recommended values

after= is almost always appropriate. An unconditional reroute takes the original address’s own work away from it; a delayed one takes only the work it could not handle.

The after= clause counts only for the first reroute. If the chain goes further, it is ignored for the next links: the path is followed to the end. Setting it deeper in the chain is pointless.

A pool only as the first link. If a pool appears in the middle of the path, it is ignored; details are in the section on rerouting to a pool.

The advice to always delay the reroute is ours. From the manual here come the syntax, the one-minute minimum, silent ignoring of loops, the “after the first link the clause does not count” rule and clearing with an empty string.
Example configuration
# we give the original address ten minutes, then move to the backup one
<domain aol.com>
    reroute-to-virtual-mta vmta2, after=10m</domain>

# the same within one stream: only that stream is rerouted
<virtual-mta vmta1>
    <domain yahoo.com>
        reroute-to-virtual-mta pool, after=2m    </domain>
</virtual-mta>
In the second block the target is a pool: messages will be spread across its members. A pool is allowed only as the first link of a chain; further along the path it would be ignored.
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 ends3 mistakes▶

Closing the reroute chain into a loop

§ 3.3.10.58

What it costsThe node finds the loop and silently cancels the reroute: messages stay in the original queue. No error, no log entry — the setting looks like it works.
How to spot itThe line is set, but the messages are still sitting in the original queue.
How to do it rightWalk the reroute chain from start to finish and make sure it does not loop back anywhere.

Putting after= on the second link of the chain

§ 3.3.10.58

What it costsThe clause counts only for the first reroute. After that the path is followed to the end at once, and the intended delay never happens.
How to spot itMessages go to the final address instantly, even though a delay is set.
How to do it rightPut after= only on the first link — it is the one that decides when the chain kicks in.

Rerouting unconditionally, without after=

our experience

What it costsThe original address stops getting this recipient domain’s mail altogether. If it is under warm-up, the warm-up stops; if reputation is tracked by it, the statistics break off.
How to spot itThe address has zero volume for a recipient domain it used to send to.
How to do it rightAdd after= — the original address will try first, and the reroute will kick in only if it could not cope.
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
reroute-to-virtual-mta <name>
Values
a VirtualMTA or pool name; optionally, after a comma, after= and a time interval of at least a minute; an empty string removes 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. The line can also be set at the root of the file — then it applies to the whole node. A <domain> block can be nested in <virtual-mta>: this is how only one stream is rerouted. An empty string (“”) removes the inherited value. It is picked up by pmta reload; messages already in the queue are rerouted too — taking after= into account, counted from when they were queued.
⇄

Related directives

3 relations

Does not work without

Sending addressThe target address or pool must exist; the block itself is described on a separate page. § 3.3.10.58

Conflicts with

invalid-virtual-mta-fallbackGlobalThe fallback address for nonexistent names does not work with rerouting — the manual says so directly. § 3.3.1.55.2

Applies to

Spreading a stuck queue across several addressesThe pool form of this same line, with its own two rules — about chains and about loops. § 11.18

Referenced from

backoff-reroute-to-virtual-mta<domain>The same line with the same syntax and the same loop rules, only it applies while the queue is in backoff mode. § 3.3.10.59

How to check on the node
The result is visible in the queue list: no messages remain for the original pair, and they appear at the target address:
pmta show settings aol.com/vmta1 | grep -i reroute
pmta show queues | grep -i aol.com
If messages stayed in the original queue while the line is set, the node almost certainly found a loop and ignored the reroute: there will be no message about it anywhere. The Hub shows reroutes as ordinary queues.
◇

What else to read

3 articles

◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.◇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.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.

In the Hub
Cost of a mistake
disruptive: applying it interrupts the node
Scenarios
Sending address rotation · Tune the pace for a provider
Neighboring settings of the block <domain>:queue-tobackoff-reroute-to-virtual-mtasmtp-hostsdisable-mx-rolluprouteAll 135 directives of the block →