Demo
Demo

Knowledge base

PMTA knowledge base›Block <virtual-mta>›Directive§ 3.3.12.13

rewrite-list

<virtual-mta>

The rewrite rule list for this sending address
in the configuration this is a linerewrite-listinside the block <virtual-mta>
The same name 1:<virtual-mta><virtual-mta-pool>— some of them are other settings, some are the same one
Rewriting tied to a sending address

The line names a declared rule list. Messages leaving through this sending address go through it.

The manual’s main way of attaching it is different. § 3.3.18 says directly: to use a list, you name it in the <source> block — and its own example shows exactly that. Attaching it here ties rewriting to the sending address, not to submission.

The difference is practical. The source is selected when the message is accepted, the sending address afterwards; so attaching it here rewrites the address later and depends on which stream the message takes. For the same return address across the whole node this is an unnecessary dependency.

🔎 The catalog has no rewrite-list entry for <source> — the manual’s directive index lists it only for <virtual-mta> and <virtual-mta-pool>, even though section § 3.3.18 attaches the list precisely to a source. The catalog follows the index item for item, so this is the fourth known gap in the vendor index.

The main trap is thinking this is the only place. A list attached in <source> works independently of this line and is applied earlier. When setting up rewriting “in the sending address,” it is easy to miss that the same thing is already done at acceptance — and the address will be rewritten twice.
What the Hub does. It does not write it here. The Hub builds the bounce-rw list when return address rewriting is enabled in the generator, and attaches it to sources — where the manual advises: to the general 0/0 in the main configuration file and to each login-based submission source in the address file. The attachment is duplicated on purpose: the general source’s directives do not carry over to an authenticated connection, and without the second line the return address would stay unchanged.
Recommended values

The value is the name of a declared list. The choice here is where to attach it:

Where When it applies Who it suits
<source> when the message is accepted, before the stream is selected the same return address for all submission — the usual case
here after the sending address is selected when the return address depends specifically on the stream
<virtual-mta-pool> the same for the whole group the same rules for a wave of addresses

In a fleet it is almost always the first option. The return address is tied to the sending domain, not to the node address — and that has to be decided at acceptance.

The requirement to attach the list to a source comes from the manual (§ 3.3.18). The breakdown by attachment points and the conclusion “the first option in a fleet” are ours.
Example configuration
# rewriting tied to a stream, not to submission
<rewrite-list abc>
    mail-from foo@*  *@bar.com
</rewrite-list>

<virtual-mta mta1>
    rewrite-list abc</virtual-mta>
The manual’s example for this section. The manual attaches the same list to <source> too — and in the section on the list itself it shows exactly that form as mandatory.
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▶

Attaching it here without noticing the attachment in the source

§ 3.3.18

What it costsThe lists apply independently: first at acceptance, then when the sending address is selected. The address is rewritten twice, and the result matches neither of the two expectations.
How to spot itThe return address field in accounting holds something that neither list describes on its own.
How to do it rightKeep rewriting in one place. For a fleet that is <source>: the return address depends on the sending domain, not on the stream.

Adding a list to a pool member, expecting them to add up

§ 3.3.13

What it costsA member’s own line replaces the pool one entirely. The pool’s rules stop applying to this sending address at once.
How to spot itOne address in the group rewrites the envelope differently from the others.
How to do it rightGather the needed rules into one list for this member — lists do not add up through inheritance.
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
rewrite-list <name>
Values
the name of a declared rewrite rule list
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<virtual-mta>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The line is inherited in the usual order of sending addresses: written in <virtual-mta-pool>, it goes to each member, and a member’s own line overrides the pool one entirely — lists do not add up. Attaching it in <source> is separate and independent: it applies earlier and does not depend on this line.
⇄

Related directives

2 relations

Does not work without

Rules for rewriting the return address and the From headerThe rule list itself; it is declared separately and named here. § 3.3.12.13

Applies to

The sending address — what it is made ofOne of the sending address settings: which rule list its messages go through. § 3.3.12.13

Referenced from

rewrite-list<virtual-mta-pool>The manual gives the definition for a sending address; here is only what writing it at the pool level changes. § 3.3.12.13mail-from<rewrite-list>The rule works only if the list is attached; the manual attaches it to a source, and a reference from a sending address is the second way. § 3.3.12.13

How to check on the node
What actually went out in the envelope is visible in accounting — the return address field:
pmtaacctfind --output csv[orig,vmta,rcpt] /var/log/pmta/acct-*.csv | head -20
If the address is rewritten differently than expected, look for a second list — in the <source> block that the submission address falls under. It applies earlier and knows nothing about this line.
◇

What else to read

3 articles

◇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.◇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.◇Warm-up built into the engineA warmed-up address hands the first N messages of the day for each receiver to its cold partner; the partner sends them itself and builds history.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation
Neighboring settings of the block <virtual-mta>:host-namedomain-keysmtp-source-hostsmtp-proxy-source-hostproxy-protocolAll 15 directives of the block →