Demo
Demo

Knowledge base

PMTA knowledge base›Block <rewrite-list>›Directive§ 3.3.18.1

mail-from

<rewrite-list>set by the Hub

A rule for replacing the envelope return address
in the configuration this is a linemail-frominside the block <rewrite-list>
The same name 1:<pattern-list><rewrite-list>— some of them are other settings, some are the same one
Where a bounce will come back to

A line of two addresses: what we replace and with what. What changes is the envelope — the address of the MAIL FROM command, invisible to the recipient; bounces arrive at it, and the receiving server checks SPF against it.

The asterisk means different things on the left and on the right. On the left it is “match anything,” on the right — “take from the original address.” mail-from foo@* *@bar.com turns foo@xyz.com into foo@bar.com: the local part stays its own, the domain is substituted.

An empty address is written as <> — that is what the envelope of a delivery report looks like. It can be caught on the left and set on the right; only one thing is not allowed: an asterisk on the right when the left is empty — there is nothing to take from an empty address.

The target address must be ASCII. A domain like bücher.de is not allowed on the right side.

The main trap is SPF. The receiving server checks a rewritten envelope against the new domain. If bounce.example.com has no SPF record of its own allowing the node’s addresses, everything leaving with the rewritten envelope gets fail — even though the sending domain’s own zone is fine.
What the Hub does. It writes it — one rule per sending domain: mail-from *@<domain> bounce@bounce.<domain>. This is what it is all for: asynchronous non-delivery reports arrive at bounce@bounce.<domain>, where <bounce-processor> parses them and hands them to the Hub via webhook. It is enabled with a checkbox in the configuration generator; along with it an SPF record for bounce.<domain> is needed — a warning about this is right in the configuration template.
Recommended values

The forms of the left and right sides — and this is the manual’s most useful table:

Left (what we catch) Matches
abcd@xyz.com exactly this address
abcd@* this local part in any domain
*@xyz.com any address in this domain
*@* everything except the empty one
<> the empty envelope address
Right (what we replace with) Result
abcd@xyz.com exactly this address
abcd@* this local part, the domain from the original
*@xyz.com the local part from the original, this domain
<> the empty address

What to write in a fleet. *@<domain> bounce@bounce.<domain> — one rule per sending domain: bounces are collected on their own subdomain and can be analyzed by the original recipient’s domain.

Both form tables, the ban on non-ASCII on the right side and the ban on an asterisk on the right with an empty address on the left come from the manual (§ 3.3.18.1). The rule for a fleet is ours.
Example configuration
# the envelope goes to its own bounce subdomain — one rule per domain
<rewrite-list mta-hub-return>
    mail-from *@shop.example.com  bounce@bounce.shop.example.com    mail-from *@news.example.com  bounce@bounce.news.example.com
</rewrite-list>
This is how the Hub assembles the list. The From header does not change — the recipient still sees the sender’s address; only the envelope is rewritten. Each bounce.<domain> needs its own SPF record.
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▶

Rewriting the envelope without setting up SPF for the new domain

our experience

What it costsThe receiving server checks SPF against the envelope domain. Without a record for bounce.<domain> every message gets fail, and this is the worst possible case: the main domain’s zone is fine, yet the check fails.
How to spot itA sharp drop in deliverability right after rewriting is turned on; DMARC reports show a failure on the SPF axis.
How to do it rightSet up an SPF record for each bounce.<domain> before ticking the checkbox. The Hub warns about this in the configuration template.

Confusing the envelope with the From header

§ 3.3.18.1

What it costsThe line changes the envelope, which the recipient does not see. The expectation “the recipient will see a different address” is not met, and the rule seems not to work.
How to spot itIn the delivered message From is unchanged, while bounces arrive at the new address.
How to do it rightFor the visible address there is from-domain. These are two different lines and two different addresses.

Putting an asterisk on the right with an empty address on the left

§ 3.3.18.1

What it costsThe rule is invalid: there is nothing to take from an empty address. The manual gives exactly this case as an example of an invalid rule.
How to spot itThe configuration is not applied after editing the list.
How to do it rightFor an empty envelope, set a specific complete address on the right, or <> again.
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
mail-from <rewrite-rule>
Values
a pattern address and a replacement address; an asterisk on the left means “any,” on the right — “take from the original”
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<rewrite-list>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The rule has no inheritance: it applies inside its <rewrite-list> block. What is inherited is the reference to the list. The manual attaches the list to <source>; references from <virtual-mta> and <virtual-mta-pool> also exist and are inherited in the usual order — the pool one goes to the members, and a member’s own line overrides it.
⇄

Related directives

3 relations

Does not work without

rewrite-list<virtual-mta>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

Conflicts with

verp-default<source>Both lines rewrite the envelope return address, and enabling them together is pointless: one will rewrite after the other. § 3.3.7.17

Affects

check-spf-outbound<domain>SPF has to be checked against the rewritten address: that is the one the receiving server will see. § 3.3.10.2

Referenced from

from-domain<rewrite-list>The neighboring line changes the envelope; this one what the recipient sees. § 3.3.18.2

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,rcpt,vmta] /var/log/pmta/acct-*.csv | head -20
The orig field must hold the rewritten address. Next, check SPF for its domain specifically: dig TXT bounce.shop.example.com +short must return a record that allows the node’s addresses.
◇

What else to read

3 articles

◇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.◇A return address with the recipient written into itThe bounce arrives at a unique address, and there is no need to parse its content.◇What to return in a bounce reportWhat to enclose in a bounce report: the whole message or only its headers.

In the Hub
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Bounce classification · Message signing and authentication
Neighboring settings of the block <rewrite-list>:from-domainAll 2 directives of the block →