Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.24

alias

Global

Forward mail from one address to others
in the configuration this is a linealiasinside the block Global
A line with two places to be written

The format is the source address, then the destination address. The section on forwarding itself (§ 13.9) clarifies: there can be several destination addresses, separated by commas.

The short form is a local part only. Then forwarding fires for that local part in any of the node’s local names. There is no matching by domain or by pattern.

Two places to write it, and the manual disagrees. Chapter 3 (§ 3.3.1.24) describes the line at the node level and shows it at the root of the file. Chapter 13 (§ 13.9) in all three examples places the same lines inside an <aliases> block — a block that is in neither the chapter 15 index nor the chapter 3 description of blocks.

Which form works on your engine version can only be checked by applying the configuration.

The main trap is the place in the chain. Expansion happens after the sending stream is chosen and before the message is queued into it. So the stream is chosen by the original recipient, while the message goes to someone else. A rule that distributes mail across streams will not learn about the new address.

The other half is the manual’s own disagreement about whether to write the line at the root of the file or inside a block. It is easy to get wrong: a line written in the wrong place will most likely just not work, and there will be no error.

What the Hub does. It does not write it: it declares no forwarding. Incoming service mail — complaints, bounces, role addresses — is accepted by pattern rules and parsed by processors rather than forwarded on as email.
Recommended values

What to set. The value is a “from, to” pair; what you choose is the form of the entry:

Value When
a full address and one recipient the usual case: one mailbox instead of another
a full address and several separated by commas the message must go to several at once
a bare local part the same mailbox in all of the node’s names

The third form is the broadest and the least noticeable: it silently covers all local names, including those added later.

The pair syntax comes from § 3.3.1.24; several comma-separated addresses, the short form and the lack of pattern matching — from § 13.9. The disagreement about where to write it (file root versus block) is our finding.
Example configuration
# two addresses on output and the short form in the second line
<aliases>
    alias example@yourdomain.com support@example.net,sales@example.net    alias jdoe someone@example.com
</aliases>
This is how the lines are shown in chapter 13. Chapter 3 describes the same directive at the node level, without an enclosing block — which form works is checked by applying the configuration.
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▶

Expecting the stream to be chosen by the destination address

§ 13.9

What it costsExpansion happens after the stream is chosen. Messages go out through the stream assigned to the original recipient — that is, to a domain that is no longer in the message.
How to spot itIn accounting, the stream of forwarded messages does not match their recipient domain.
How to do it rightBuild the stream distribution from the original address, not the final one.

Writing the line in the wrong place

§ 3.3.1.24

What it costsChapter 3 shows it at the root of the file, chapter 13 — inside an <aliases> block that is not in the index. Written in the wrong place, the line will most likely just not work, and there will be no error.
How to spot itForwarding is declared, but messages go to the original address.
How to do it rightCheck both forms by applying the configuration and keep the one that worked on your engine version.

Using the short form without thinking about all of the node's names

§ 13.9

What it costsA bare local part fires in all of the node’s local names, including those added later. A new domain on the node silently gets the same forwarding.
How to spot itMail for a new domain goes to someone else’s mailbox, although nothing was declared for it.
How to do it rightWrite full addresses wherever forwarding must not extend to future domains.
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
alias SOURCE TARGET
Values
a source address or local part, then one or more comma-separated addresses
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
A node-level directive: it applies to the whole instance and has no inheritance. Forwarding cannot be limited to a source or stream — it fires by recipient address, whoever submitted the message.
⇄

Related directives

1 relation

Works together with

Who is allowed to submit mail and for whom to accept itFor a message to reach expansion, the node first has to agree to accept it — that is decided by the acceptance rules. inference

How to check on the node
The declarations are visible in the configuration; whether expansion worked — from the queues:
grep -n -A5 '^<aliases>\|^alias ' /etc/pmta/config
pmta show queues --maxitems=20
The queues will show the domains of the destination addresses, not the original ones. If they are not there, the line did not work — and the first thing to check is where it was written.
◇

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
Neighboring settings of the block Global:auto-mx-rollupsmtp-proxy-source-hosthost-namepostmasterdomain-keyAll 108 directives of the block →