dist/html/VERP_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "https://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix VERP Howto</title>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix VERP Howto</h1>

<hr>

<h2>Postfix VERP support</h2>

<p> 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.  </p>

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

<blockquote>
<pre>
owner-listname+user=domain@origin
</pre>
</blockquote>

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

<p> The VERP concept was popularized by the qmail MTA and by the ezmlm
mailing list manager.  See <a href="https://cr.yp.to/proto/verp.txt">https://cr.yp.to/proto/verp.txt</a> for the
ideas behind this concept. </p>

<p> Topics covered in this document: </p>

<ul>

<li> <a href="#config"> Postfix VERP configuration parameters </a>

<li> <a href="#majordomo"> Using VERP with majordomo etc. mailing lists </a>

<li> <a href="#smtp"> VERP support in the Postfix SMTP server</a>

<li> <a href="#sendmail"> VERP support in the Postfix sendmail command </a>

<li> <a href="#qmqp"> VERP support in the Postfix QMQP server </a>

</ul>

<h2> <a name="config"> Postfix VERP configuration parameters </a> </h2>

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

<dl>

<dt> <a href="postconf.5.html#default_verp_delimiters">default_verp_delimiters</a> (default value:  +=)

    <dd> <p> What VERP delimiter characters Postfix uses when VERP
    style delivery is requested but no explicit delimiters are
    specified. </p>

<dt> <a href="postconf.5.html#verp_delimiter_filter">verp_delimiter_filter</a> (default: -+=)

    <dd> <p> 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.  </p> </dd>

<dt> <a href="postconf.5.html#smtpd_authorized_verp_clients">smtpd_authorized_verp_clients</a> (default value: none)

    <dd> <p> 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. </p>

    <p> With Postfix versions 1.1 and 2.0, this parameter is called
    <a href="postconf.5.html#authorized_verp_clients">authorized_verp_clients</a> (default: $<a href="postconf.5.html#mynetworks">mynetworks</a>). </p> </dd>

<dt> <a href="postconf.5.html#disable_verp_bounces">disable_verp_bounces</a> (default: no)

    <dd> <p> 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. </p> </dd>

</dl>

<h2> <a name="majordomo"> Using VERP with majordomo etc. mailing lists </a> </h2>

<p> 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: </p>

<p> Postfix 2.3 and later: </p>

<blockquote>
<pre>
% sendmail -XV -f owner-listname other-arguments...

% sendmail -XV+= -f owner-listname other-arguments...
</pre>
</blockquote>

<p> 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): </p>

<blockquote>
<pre>
% sendmail -V -f owner-listname other-arguments...

% sendmail -V+= -f owner-listname other-arguments...
</pre>
</blockquote>

<p> The first form uses the default <a href="postconf.5.html">main.cf</a> VERP delimiter characters.
The second form allows you to explicitly specify the VERP delimiter
characters. The example shows the recommended values. </p>

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

<blockquote>
<pre>
/etc/aliases:
    owner-listname: yourname+listname
</pre>
</blockquote>

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

<p> 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: </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> = +
    <a href="postconf.5.html#forward_path">forward_path</a> = $home/.forward${<a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a>}${extension},
        $home/.forward
    <a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a> = canonical, virtual
</pre>
</blockquote>

<p> (the last two parameter settings are default settings). </p>

<p> 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: </p>

<blockquote>
<pre>
~/.forward+listname:
    "|/some/where/command ..."
</pre>
</blockquote>

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

<blockquote>
<pre>
owner-listname+user=domain (a] your.domain
</pre>
</blockquote>

<p> 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: </p>

<blockquote>
<pre>
To: owner-listname+user=domain (a] your.domain
</pre>
</blockquote>

<p> 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.
</p>

<h2> <a name="smtp"> VERP support in the Postfix SMTP server </a> </h2>

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

<blockquote>
<pre>
MAIL FROM:&lt;sender@domain&gt; XVERP

MAIL FROM:&lt;sender@domain&gt; XVERP=+=
</pre>
</blockquote>

<p> The first form uses the default <a href="postconf.5.html">main.cf</a> VERP delimiters, the
second form overrides them explicitly. The values shown are the
recommended ones. </p>

<p> You can use the <a href="postconf.5.html#smtpd_command_filter">smtpd_command_filter</a> feature to append XVERP
to SMTP commands from legacy software. This requires Postfix 2.7
or later. </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#smtpd_command_filter">smtpd_command_filter</a> = <a href="pcre_table.5.html">pcre</a>:/etc/postfix/append_verp.pcre
    <a href="postconf.5.html#smtpd_authorized_verp_clients">smtpd_authorized_verp_clients</a> = $<a href="postconf.5.html#mynetworks">mynetworks</a>

/etc/postfix/append_verp.<a href="pcre_table.5.html">pcre</a>:
    /^(MAIL FROM:&lt;listname@example\.com&gt;.*)/ $1 XVERP
</pre>
</blockquote>

<h2> <a name="sendmail"> VERP support in the Postfix sendmail command </a> </h2>

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

<p> Postfix 2.3 and later:</p>
<blockquote>
<pre>
% sendmail -XV -f owner-listname ....

% sendmail -XV+= -f owner-listname ....
</pre>
</blockquote>

<p> 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): </p>

<blockquote>
<pre>
% sendmail -V -f owner-listname ....

% sendmail -V+= -f owner-listname ....
</pre>
</blockquote>

<p> The first form uses the default <a href="postconf.5.html">main.cf</a> VERP delimiters, the
second form overrides them explicitly. The values shown are the
recommended ones. </p>

<h2> <a name="qmqp"> VERP support in the Postfix QMQP server </a> </h2>

<p> When the Postfix QMQP server receives mail with an envelope
sender address of the form: </p>

<blockquote>
<pre>
listname- (a] your.domain-@[]
</pre>
</blockquote>

<p> Postfix generates sender addresses
"<tt>listname-user=domain (a] your.domain</tt>", using "-=" as the VERP
delimiters because qmail/ezmlm expect this.  </p>

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

</body>

</html>