PPoossttffiixx VVEERRPP HHoowwttoo

-------------------------------------------------------------------------------

PPoossttffiixx VVEERRPP ssuuppppoorrtt

Postfix versions 1.1 and later support variable envelope return path addresses
on request. When VERP style delivery is requested, each recipient of a message
receives a customized copy of the message, with his/her own recipient address
encoded in the envelope sender address.

For example, when VERP style delivery is requested, Postfix delivers mail from
"owner-listname@origin" for a recipient "user@domain", with a sender address
that encodes the recipient as follows:

    owner-listname+user=domain@origin

Thus, undeliverable mail can reveal the undeliverable recipient address without
requiring the list owner to parse bounce messages.

The VERP concept was popularized by the qmail MTA and by the ezmlm mailing list
manager. See http://cr.yp.to/proto/verp.txt for the ideas behind this concept.

Topics covered in this document:

  * Postfix VERP configuration parameters
  * Using VERP with majordomo etc. mailing lists
  * VERP support in the Postfix SMTP server
  * VERP support in the Postfix sendmail command
  * VERP support in the Postfix QMQP server

PPoossttffiixx VVEERRPP ccoonnffiigguurraattiioonn ppaarraammeetteerrss

With Postfix, the whole process is controlled by four configuration parameters.

default_verp_delimiters (default value: +=)
    What VERP delimiter characters Postfix uses when VERP style delivery is
    requested but no explicit delimiters are specified.

verp_delimiter_filter (default: -+=)
    What characters Postfix accepts as VERP delimiter characters on the
    sendmail command line and in SMTP commands. Many characters must not be
    used as VERP delimiter characters, either because they already have a
    special meaning in email addresses (such as the @ or the %), because they
    are used as part of a username or domain name (such as alphanumerics), or
    because they are non-ASCII or control characters. And who knows, some
    characters may tickle bugs in vulnerable software, and we would not want
    that to happen.

smtpd_authorized_verp_clients (default value: none)
    What SMTP clients are allowed to request VERP style delivery. The Postfix
    QMQP server uses its own access control mechanism, and local submission
    (via /usr/sbin/sendmail etc.) is always authorized. To authorize a host,
    list its name, IP address, subnet (net/mask) or parent .domain.

    With Postfix versions 1.1 and 2.0, this parameter is called
    authorized_verp_clients (default: $mynetworks).

disable_verp_bounces (default: no)
    Send one bounce report for multi-recipient VERP mail, instead of one bounce
    report per recipient. The default, one per recipient, is what ezmlm needs.

UUssiinngg VVEERRPP wwiitthh mmaajjoorrddoommoo eettcc.. mmaaiilliinngg lliissttss

In order to make VERP useful with majordomo etc. mailing lists, you would
configure the list manager to submit mail according to one of the following two
forms:

Postfix 2.3 and later:

    % sendmail -XV -f owner-listname other-arguments...

    % sendmail -XV+= -f owner-listname other-arguments...

Postfix 2.2 and earlier (Postfix 2.3 understands the old syntax for backwards
compatibility, but will log a warning that reminds you of the new syntax):

    % sendmail -V -f owner-listname other-arguments...

    % sendmail -V+= -f owner-listname other-arguments...

The first form uses the default main.cf VERP delimiter characters. The second
form allows you to explicitly specify the VERP delimiter characters. The
example shows the recommended values.

This text assumes that you have set up an owner-listname alias that routes
undeliverable mail to a real person:

    /etc/aliases:
        owner-listname: yourname+listname

In order to process bounces we are going to make extensive use of address
extension tricks.

You need to tell Postfix that + is the separator between an address and its
optional address extension, that address extensions are appended to .forward
file names, and that address extensions are to be discarded when doing alias
expansions:

    /etc/postfix/main.cf:
        recipient_delimiter = +
        forward_path = $home/.forward${recipient_delimiter}${extension},
            $home/.forward
        propagate_unmatched_extensions = canonical, virtual

(the last two parameter settings are default settings).

You need to set up a file named .forward+listname with the commands that
process all the mail that is sent to the owner-listname address:

    ~/.forward+listname:
        "|/some/where/command ..."

With this set up, undeliverable mail for user@domain will be returned to the
following address:

    owner-listname+user=domain@your.domain

which is processed by the command in your .forward+listname file. The message
should contain, among others, a To: header with the encapsulated recipient
sender address:

    To: owner-listname+user=domain@your.domain

It is left as an exercise for the reader to parse the To: header line and to
pull out the user=domain part from the recipient address.

VVEERRPP ssuuppppoorrtt iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr

The Postfix SMTP server implements a command XVERP to enable VERP style
delivery. The syntax allows two forms:

    MAIL FROM:<sender@domain> XVERP

    MAIL FROM:<sender@domain> XVERP=+=

The first form uses the default main.cf VERP delimiters, the second form
overrides them explicitly. The values shown are the recommended ones.

You can use the smtpd_command_filter feature to append XVERP to SMTP commands
from legacy software. This requires Postfix 2.7 or later.

    /etc/postfix/main.cf:
        smtpd_command_filter = pcre:/etc/postfix/append_verp.pcre
        smtpd_authorized_verp_clients = $mynetworks

    /etc/postfix/append_verp.pcre:
        /^(MAIL FROM:<listname@example\.com>.*)/ $1 XVERP

VVEERRPP ssuuppppoorrtt iinn tthhee PPoossttffiixx sseennddmmaaiill ccoommmmaanndd

The Postfix sendmail command has a -V flag to request VERP style delivery.
Specify one of the following two forms:

Postfix 2.3 and later:

    % sendmail -XV -f owner-listname ....

    % sendmail -XV+= -f owner-listname ....

Postfix 2.2 and earlier (Postfix 2.3 understands the old syntax for backwards
compatibility, but will log a warning that reminds you of the new syntax):

    % sendmail -V -f owner-listname ....

    % sendmail -V+= -f owner-listname ....

The first form uses the default main.cf VERP delimiters, the second form
overrides them explicitly. The values shown are the recommended ones.

VVEERRPP ssuuppppoorrtt iinn tthhee PPoossttffiixx QQMMQQPP sseerrvveerr

When the Postfix QMQP server receives mail with an envelope sender address of
the form:

    listname-@your.domain-@[]

Postfix generates sender addresses "listname-user=domain@your.domain", using "-
=" as the VERP delimiters because qmail/ezmlm expect this.

More generally, a sender address of "prefix@origin-@[]" requests VERP style
delivery with sender addresses of the form "prefixuser=domain@origin". However,
Postfix allows only VERP delimiters that are specified with the
verp_delimiter_filter parameter. In particular, the "=" delimiter is required
for qmail compatibility (see the qmail addresses(5) manual page for details).