Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Mail Systems
Eclipse Documentation

How To Guides
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Problem Solutions
Privacy Policy




Postfix Documentation
Previous Page Home Next Page

Address rewriting when mail is delivered

The Postfix queue manager sorts mail according to its destination and gives it to Postfix delivery agents such as local(8), smtp(8), or lmtp(8). Just like the cleanup(8) server, the Postfix queue manager delegates the more complex address manipulations to the trivial-rewrite(8) server.

Address manipulations at this stage are:

Each Postfix delivery agent tries to deliver the mail to its destination, while encapsulating the sender, recipients, and message content according to the rules of the SMTP, LMTP, etc. protocol. When mail cannot be delivered, it is either returned to the sender or moved to the deferred queue and tried again later.

Address manipulations when mail is delivered via the smtp(8) delivery agent:

Address manipulations when mail is delivered via the local(8) delivery agent:

The remainder of this document presents each address manipulation step in more detail, with specific examples or with pointers to documentation with examples.

Resolve address to destination

The Postfix qmgr(8) queue manager selects new mail from the incoming queue or old mail from the deferred queue, and asks the trivial-rewrite(8) address rewriting and resolving daemon where it should be delivered.

As of version 2.0, Postfix distinguishes four major address classes. Each class has its own list of domain names, and each class has its own default delivery method, as shown in the table below. See the ADDRESS_CLASS_README document for the fine details. Postfix versions before 2.0 only distinguish between local delivery and everything else.

Destination domain list Default delivery method Availability
$ mydestination, $ inet_interfaces, $ proxy_interfaces $ local_transport Postfix 1.0
$ virtual_mailbox_domains $ virtual_transport Postfix 2.0
$ relay_domains $ relay_transport Postfix 2.0
none $ default_transport Postfix 1.0

Mail transport switch

Once the trivial-rewrite(8) daemon has determined a default delivery method it searches the optional transport(5) table for information that overrides the message destination and/or delivery method. Typical use of the transport(5) table is to send mail to a system that is not connected to the Internet, or to use a special SMTP client configuration for destinations that have special requirements. See, for example, the STANDARD_CONFIGURATION_README and UUCP_README documents, and the examples in the transport(5) manual page.

Transport table lookups are disabled by default. To enable, edit the transport_maps parameter in the file and specify one or more lookup tables, separated by whitespace or commas.


transport_maps = hash:/etc/postfix/transport

Relocated users table

Next, the trivial-rewrite(8) address rewriting and resolving daemon runs each recipient through the relocated(5) database. This table provides information on how to reach users that no longer have an account, or what to do with mail for entire domains that no longer exist. When mail is sent to an address that is listed in this table, the message is returned to the sender with an informative message.

The relocated(5) database is searched after transport(5) table lookups, in anticipation of transport(5) tables that can replace one recipient address by a different one.

Lookups of relocated users are disabled by default. To enable, edit the relocated_maps parameter in the file and specify one or more lookup tables, separated by whitespace or commas.


relocated_maps = hash:/etc/postfix/relocated

    [email protected]      [email protected]

As of Postfix version 2, mail for a relocated user will be rejected by the SMTP server with the reason "user has moved to [email protected]". Older Postfix versions will receive the mail first, and then return it to the sender as undeliverable, with the same reason.

Generic mapping for outgoing SMTP mail

Some hosts have no valid Internet domain name, and instead use a name such as localdomain.local. This can be a problem when you want to send mail over the Internet, because many mail servers reject mail addresses with invalid domain names.

With the smtp_generic_maps parameter you can specify generic(5) lookup tables that replace local mail addresses by valid Internet addresses when mail leaves the machine via SMTP. The generic(5) mapping replaces envelope and header addresses, and is non-recursive. It does not happen when you send mail between addresses on the local machine.

This feature is available in Postfix version 2.2 and later.


smtp_generic_maps = hash:/etc/postfix/generic

    [email protected]		[email protected]
    [email protected]		[email protected]
    @localdomain.local			[email protected]

When mail is sent to a remote host via SMTP, this replaces [email protected] by his ISP mail address, replaces [email protected] by her ISP mail address, and replaces other local addresses by his ISP account, with an address extension of +local (this example assumes that the ISP supports "+" style address extensions).

Local alias database

When mail is to be delivered locally, the local(8) delivery agent runs each local recipient name through the aliases(5) database. The mapping does not affect addresses in message headers. Local aliases are typically used to implement distribution lists, or to direct mail for standard aliases such as postmaster to real people. The table can also be used to map "Firstname.Lastname" addresses to login names.

Alias lookups are enabled by default. The default configuration depends on the operating system environment, but it is typically one of the following:

alias_maps = hash:/etc/aliases
alias_maps = dbm:/etc/aliases, nis:mail.aliases

The pathname of the alias database file is controlled with the alias_database configuration parameter. The value is system dependent. Usually it is one of the following:

alias_database = hash:/etc/aliases (4.4BSD, LINUX)
alias_database = dbm:/etc/aliases (4.3BSD, SYSV<4)
alias_database = dbm:/etc/mail/aliases (SYSV4)

An aliases(5) file can specify that mail should be delivered to a local file, or to a command that receives the message in the standard input stream. For security reasons, deliveries to command and file destinations are performed with the rights of the alias database owner. A default userid, default_privs, is used for deliveries to commands or files in "root"-owned aliases.

Local per-user .forward files

With delivery via the local(8) deliver agent, users can control their own mail delivery by specifying destinations in a file called .forward in their home directories. The syntax of these files is the same as with the local aliases(5) file, except that the left-hand side of the alias (lookup key and colon) are not present.

Local catch-all address

When the local(8) delivery agent finds that a message recipient does not exist, the message is normally returned to the sender ("user unknown"). Sometimes it is desirable to forward mail for non-existing recipients to another machine. For this purpose you can specify an alternative destination with the luser_relay configuration parameter.

Alternatively, mail for non-existent recipients can be delegated to an entirely different message transport, as specified with the fallback_transport configuration parameter. For details, see the local(8) delivery agent documentation.

Note: if you use the luser_relay feature in order to receive mail for non-UNIX accounts, then you must specify:

local_recipient_maps =

(i.e. empty) in the file, otherwise the Postfix SMTP server will reject mail for non-UNIX accounts with "User unknown in local recipient table". See the LOCAL_RECIPIENT_README file for more information on this.

luser_relay can specify one address. It is subjected to "$name" expansions. Examples:

[email protected]

The bare username, without address extension, is prepended to "". For example, mail for "username+foo" is sent to "[email protected]".

[email protected]

The entire original recipient localpart, including address extension, is prepended to "". For example, mail for "username+foo" is sent to "[email protected]".


The bare username, without address extension, is appended to "sysadmin". For example, mail for "username+foo" is sent to "sysadmin+username".


The entire original recipient localpart, including address extension, is appended to "sysadmin". For example, mail for "username+foo" is sent to "sysadmin+username+foo".

Postfix Documentation
Previous Page Home Next Page