Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 13.9

Replacing a recipient with one or several others

aliases and forwarding
One address in, several out

The mechanism is simple: a declared address is replaced by one or several others, listed separated by commas. A message that arrives at example@yourdomain.com goes to all the named addresses.

Its place in the chain is named precisely. Expansion happens after the selection list is applied and the sending stream is chosen, but before the message is queued into that stream. The same applies to messages assigned a stream by a source default or a header.

An unobvious consequence follows: the stream is chosen by the original recipient, while the message leaves addressed to others. If the stream is chosen by a rule on the recipient domain, all expanded addresses will go out through the stream chosen for the original domain.

The short form is just the local part. Then forwarding triggers for addresses with that local part in any of the node’s local names. Matching by domain or by pattern is not supported — only an exact match.

The main trap is that expansion happens after the stream is chosen. Forwarding looks like “send it there too”, but in fact the message goes out through the stream chosen for the original recipient. A rule distributing mail across streams will not learn about the new addresses.

The second half is multiplication. One address in can become three out, and this is not visible anywhere except in the forwarding declaration. Volume, rate and limits are counted by the expanded addresses.

What the Hub does. It does not use it: it declares no forwarding, and its service incoming mail is handled by the bounce and complaint processors rather than forwarded further.

The mechanism would come in handy where role addresses of several domains should converge into one mailbox. Now dmarc@, postmaster@ and abuse@ are accepted by a pattern rule and go to the bounce processor: what is recognized becomes an accounting record, the rest is discarded — they do not end up in a mailbox.

Example configuration
# declaring the node's names, reception and the forwarding itself
host-name yourdomain.com
relay-address user@example.com

<aliases>
    alias example@yourdomain.com support@example.net,sales@example.net    alias jdoe someone@example.com
</aliases>
The first forwarding line gives two addresses on output. The second is written in short form — it will trigger for jdoe@ in any of the node’s declared names.
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▶

Expecting the stream to be chosen by the new address

§ 13.9

What it costsThe stream is chosen before expansion — by the original recipient. Messages go out through the stream assigned to a domain they no longer have.
How to spot itIn accounting, forwarded messages show a stream that does not match their recipient domain.
How to do it rightTake this into account when distributing across streams: the rule must fit the original address, not the final one.

Counting on patterns in the forwarding declaration

§ 13.9

What it costsMatching by domain or pattern is not supported — only an exact address or a bare local part. A declaration with a pattern simply will not trigger.
How to spot itForwarding does not trigger, though in the configuration it looks declared.
How to do it rightList addresses exactly, or use the short local-part form.
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.
⇄

Related entries

1 relation

Depends on

Six ways to choose a stream and the order among themExpansion happens after the stream is chosen: the stream is chosen by the original recipient, while the message leaves addressed to others. § 13.9

Referenced from

max-message-hops<source>Forwarding creates exactly the loops this limit breaks. § 3.3.7.38

How to check on the node
The declarations are visible in the configuration; the result — from the queues:
grep -n -A5 '^<aliases>\|^alias ' /etc/pmta/config
pmta show queues --maxitems=20
The queues will show the domains of the addresses mail is forwarded to, not those it arrived at. This is the quickest way to make sure expansion worked.
◇

What else to read

3 articles

◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different 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.◇Address lists — named and unnamedA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Receiving inbound mail