How To Configure Custom Postfix Bounce Messages

Version 1.0
Author: Falko Timme <ft [at] falkotimme [dot] com>
Last edited 02/26/2008

Since Postfix version 2.3, Postfix supports custom bounce messages. This guide shows how to configure custom Postfix bounce messages.

I do not issue any guarantee that this will work for you!

1 Postfix Version

First you should find out about your Postfix version to make sure it supports custom bounce messages:

postconf -d | grep mail_version

server2:~# postconf -d | grep mail_version
mail_version = 2.3.8
milter_macro_v = $mail_name $mail_version
server2:~#

If your Postfix is 2.3 or newer, then you're good to go.

2 Set maximal_queue_lifetime And delay_warning_time

From http://www.postfix.org/postconf.5.html:

maximal_queue_lifetime: The maximal time a message is queued before it is sent back as undeliverable.

delay_warning_time: The time after which the sender receives the message headers of mail that is still queued.

The postconf -n command shows the settings that are currently configured in /etc/postfix/main.cf, whereas the postconf -d command shows the default settings that are valid unless something else is set in /etc/postfix/main.cf.

To find out about the current value of maximal_queue_lifetime, you can run

postconf -d | grep maximal_queue_lifetime
postconf -n | grep maximal_queue_lifetime

If postconf -n doesn't display anything, this means the value from postconf -d is currently being used:

server2:~# postconf -d | grep maximal_queue_lifetime
maximal_queue_lifetime = 5d
server2:~# postconf -n | grep maximal_queue_lifetime
server2:~#

The same goes for delay_warning_time:

postconf -d | grep delay_warning_time
postconf -n | grep delay_warning_time

server2:~# postconf -d | grep delay_warning_time
delay_warning_time = 0h
server2:~# postconf -n | grep delay_warning_time
server2:~#

If you want to modify these settings, you can use the postconf -e command. It will write the settings to /etc/postfix/main.cf, e.g. like this:

postconf -e 'maximal_queue_lifetime = 1d'
postconf -e 'delay_warning_time = 0h'

Restart Postfix afterwards:

/etc/init.d/postfix restart

The reason that we care about these two settings is that their values can be used in the custom bounce messages.

3 Create A Custom Bounce Message

From http://www.postfix.org/bounce.5.html:

The template file can specify templates for failed mail, delayed mail, successful delivery or for address verification. These templates are named failure_template, delay_template, success_template and verify_template, respectively. You can but do not have to specify all four templates in a bounce template file.

Each template starts with "template_name = <<EOF" and ends with a line that contains the word "EOF"

We can now create the file /etc/postfix/bounce.cf which contains the templates like this (I'm using all four templates here, but you can leave out the ones you don't need). It is absolutely important that the file ends with an empty line!

vi /etc/postfix/bounce.cf

#
# The failure template is used when mail is returned to the sender;
# either the destination rejected the message, or the destination
# could not be reached before the message expired in the queue.
#

failure_template = <<EOF
Charset: us-ascii
From: MAILER-DAEMON (Mail Delivery System)
Subject: Undelivered Mail Returned to Sender
Postmaster-Subject: Postmaster Copy: Undelivered Mail

This is the mail system at host $myhostname.

I'm sorry to have to inform you that your message could not
be delivered to one or more recipients. It's attached below.

For further assistance, please send mail to <postmaster>

If you do so, please include this problem report. You can
delete your own text from the attached returned message.

                   The mail system
EOF


#
# The delay template is used when mail is delayed. Note a neat trick:
# the default template displays the delay_warning_time value as hours
# by appending the _hours suffix to the parameter name; it displays
# the maximal_queue_lifetime value as days by appending the _days
# suffix.
#
# Other suffixes are: _seconds, _minutes, _weeks. There are no other
# main.cf parameters that have this special behavior.
#
# You need to adjust these suffixes (and the surrounding text) if
# you have very different settings for these time parameters.
#

delay_template = <<EOF
Charset: us-ascii
From: MAILER-DAEMON (Mail Delivery System)
Subject: Delayed Mail (still being retried)
Postmaster-Subject: Postmaster Warning: Delayed Mail

This is the mail system at host $myhostname.

####################################################################
# THIS IS A WARNING ONLY.  YOU DO NOT NEED TO RESEND YOUR MESSAGE. #
####################################################################

Your message could not be delivered for more than $delay_warning_time_hours hour(s).
It will be retried until it is $maximal_queue_lifetime_days day(s) old.

For further assistance, please send mail to <postmaster>

If you do so, please include this problem report. You can
delete your own text from the attached returned message.

                   The mail system
EOF


#
# The success template is used when mail is delivered to mailbox,
# when an alias or list is expanded, or when mail is delivered to a
# system that does not announce DSN support. It is an error to specify
# a Postmaster-Subject: here.
#

success_template = <<EOF
Charset: us-ascii
From: MAILER-DAEMON (Mail Delivery System)
Subject: Successful Mail Delivery Report

This is the mail system at host $myhostname.

Your message was successfully delivered to the destination(s)
listed below. If the message was delivered to mailbox you will
receive no further notifications. Otherwise you may still receive
notifications of mail delivery errors from other systems.

                   The mail system
EOF


#
# The verify template is used for address verification (sendmail -bv
# address...). or for verbose mail delivery (sendmail -v address...).
# It is an error to specify a Postmaster-Subject: here.
#

verify_template = <<EOF
Charset: us-ascii
From: MAILER-DAEMON (Mail Delivery System)
Subject: Mail Delivery Status Report

This is the mail system at host $myhostname.

Enclosed is the mail delivery report that you requested.

                   The mail system
EOF

You can customize the messages to your likings. In the messages, you can use all main.cf variables (e.g. $myhostname). If you take a look at the delay_template, you'll see that I use the additional variables $delay_warning_time_hours and $maximal_queue_lifetime_days. You could as well use $delay_warning_time_seconds, $delay_warning_time_minutes, $delay_warning_time_days, $delay_warning_time_weekes resp. $maximal_queue_lifetime_seconds, $maximal_queue_lifetime_minutes, $maximal_queue_lifetime_hours, $maximal_queue_lifetime_weeks, but keep in mind what http://www.postfix.org/bounce.5.html explains about these variables:

delay_warning_time_suffix: Expands into the value of the delay_warning_time parameter, expressed in the time unit specified by suffix, which is one of seconds, minutes, hours, days, or weeks.

maximal_queue_lifetime_suffix: Expands into the value of the maximal_queue_lifetime parameter, expressed in the time unit specified by suffix. See above under delay_warning_time for possible suffix values.

So if you use the variable $delay_warning_time_minutes instead of $delay_warning_time_hours in your template, you should follow it by the word "minutes" instead of "hours".

Next we configure Postfix to use the custom templates:

postconf -e 'bounce_template_file = /etc/postfix/bounce.cf'

To check what the templates look like when all variables are replaced with their real values, and to make sure that there are no errors in your templates (e.g. like a missing newline at the end of /etc/postfix/bounce.cf), run:

postconf -b /etc/postfix/bounce.cf

server2:~# postconf -b /etc/postfix/bounce.cf
expanded_failure_text = <<EOF
This is the mail system at host server2.example.com.

I'm sorry to have to inform you that your message could not
be delivered to one or more recipients. It's attached below.

For further assistance, please send mail to <postmaster>

If you do so, please include this problem report. You can
delete your own text from the attached returned message.

                   The mail system
EOF

expanded_delay_text = <<EOF
This is the mail system at host server2.example.com.

####################################################################
# THIS IS A WARNING ONLY.  YOU DO NOT NEED TO RESEND YOUR MESSAGE. #
####################################################################

Your message could not be delivered for more than 0 hour(s).
It will be retried until it is 1 day(s) old.

For further assistance, please send mail to <postmaster>

If you do so, please include this problem report. You can
delete your own text from the attached returned message.

                   The mail system
EOF

expanded_success_text = <<EOF
This is the mail system at host server2.example.com.

Your message was successfully delivered to the destination(s)
listed below. If the message was delivered to mailbox you will
receive no further notifications. Otherwise you may still receive
notifications of mail delivery errors from other systems.

                   The mail system
EOF

expanded_verify_text = <<EOF
This is the mail system at host server2.example.com.

Enclosed is the mail delivery report that you requested.

                   The mail system
EOF
server2:~#

If no errors are shown, we can restart Postfix so that it can use the custom templates:

/etc/init.d/postfix restart

4 Links

• Postfix bounce man page: http://www.postfix.org/bounce.5.html
• Postfix configuration parameters: http://www.postfix.org/postconf.5.html