15
15
<b>postconf -b</b> [<i>template</i><b>_</b><i>file</i>]
18
The Postfix <a href="bounce.8.html"><b>bounce</b>(8)</a> server produces delivery status
19
notification (DSN) messages for undeliverable mail,
20
delayed mail, successful delivery or address verification
23
By default, these notifications are generated from built-
24
in templates with message headers and message text. Sites
25
can override the built-in information by specifying a
26
bounce template file with the <b><a href="postconf.5.html#bounce_template_file">bounce_template_file</a></b> config-
29
This document describes the general procedure to create a
30
bounce template file, followed by the specific details of
31
bounce template formats.
18
The Postfix <a href="bounce.8.html"><b>bounce</b>(8)</a> server produces delivery status notification
19
(DSN) messages for undeliverable mail, delayed mail, successful deliv-
20
ery or address verification requests.
22
By default, these notifications are generated from built-in templates
23
with message headers and message text. Sites can override the built-in
24
information by specifying a bounce template file with the <b><a href="postconf.5.html#bounce_template_file">bounce_tem</a>-</b>
25
<b><a href="postconf.5.html#bounce_template_file">plate_file</a></b> configuration parameter.
27
This document describes the general procedure to create a bounce tem-
28
plate file, followed by the specific details of bounce template for-
33
31
<b>GENERAL PROCEDURE</b>
34
To create a customized bounce template file, create a tem-
35
porary copy of the file <b>/etc/postfix/bounce.cf.default</b> and
36
edit the temporary file.
32
To create a customized bounce template file, create a temporary copy of
33
the file <b>/etc/postfix/bounce.cf.default</b> and edit the temporary file.
38
To preview the results of $<i>name</i> expansions in the template
35
To preview the results of $<i>name</i> expansions in the template text, use
41
38
<b>postconf -b</b> <i>temporary</i><b>_</b><i>file</i>
43
Errors in the template will be reported to the standard
44
error stream and to the syslog daemon.
46
While previewing the text, be sure to pay particular
47
attention to the expansion of time value parameters that
48
appear in the delayed mail notification text.
50
Once the result is satisfactory, copy the template to the
51
Postfix configuration directory and specify in <a href="postconf.5.html">main.cf</a>
40
Errors in the template will be reported to the standard error stream
41
and to the syslog daemon.
43
While previewing the text, be sure to pay particular attention to the
44
expansion of time value parameters that appear in the delayed mail
47
Once the result is satisfactory, copy the template to the Postfix con-
48
figuration directory and specify in <a href="postconf.5.html">main.cf</a> something like:
54
50
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
55
51
<a href="postconf.5.html#bounce_template_file">bounce_template_file</a> = /etc/postfix/bounce.cf
57
53
<b>TEMPLATE FILE FORMAT</b>
58
The template file can specify templates for failed mail,
59
delayed mail, successful delivery or for address verifica-
60
tion. These templates are named <b>failure_template</b>,
61
<b>delay_template</b>, <b>success_template</b> and <b>verify_template</b>,
62
respectively. You can but do not have to specify all four
63
templates in a bounce template file.
54
The template file can specify templates for failed mail, delayed mail,
55
successful delivery or for address verification. These templates are
56
named <b>failure_template</b>, <b>delay_template</b>, <b>success_template</b> and <b>ver-</b>
57
<b>ify_template</b>, respectively. You can but do not have to specify all
58
four templates in a bounce template file.
65
Each template starts with "<i>template</i><b>_</b><i>name</i> <b>=</b> <<<b>EOF</b>" and ends
66
with a line that contains the word "<b>EOF</b>" only. You can
67
change the word EOF, but you can't enclose it in quotes as
68
with the shell or with Perl (<i>template</i><b>_</b><i>name</i> <b>=</b> <<<b>'EOF'</b>).
60
Each template starts with "<i>template</i><b>_</b><i>name</i> <b>=</b> <<<b>EOF</b>" and ends with a line
61
that contains the word "<b>EOF</b>" only. You can change the word EOF, but you
62
can't enclose it in quotes as with the shell or with Perl (<i>tem-</i>
63
<i>plate</i><b>_</b><i>name</i> <b>=</b> <<<b>'EOF'</b>). Here is an example:
71
65
# The failure template is used for undeliverable mail.
92
The usage and specification of bounce templates is subject
93
to the following restrictions:
95
<b>o</b> No special meaning is given to the backslash char-
96
acter or to leading whitespace; these are always
99
<b>o</b> Inside the << context, the "$" character is spe-
100
cial. To produce a "$" character as output, specify
103
<b>o</b> Outside the << context, lines beginning with "#"
104
are ignored, as are empty lines, and lines consist-
105
ing of whitespace only.
107
Examples of all templates can be found in the file
108
<b>bounce.cf.default</b> in the Postfix configuration directory.
86
The usage and specification of bounce templates is subject to the fol-
89
<b>o</b> No special meaning is given to the backslash character or to
90
leading whitespace; these are always taken literally.
92
<b>o</b> Inside the << context, the "$" character is special. To produce
93
a "$" character as output, specify "$$".
95
<b>o</b> Outside the << context, lines beginning with "#" are ignored, as
96
are empty lines, and lines consisting of whitespace only.
98
Examples of all templates can be found in the file <b>bounce.cf.default</b> in
99
the Postfix configuration directory.
110
101
<b>TEMPLATE HEADER FORMAT</b>
111
The first portion of a bounce template consists of
112
optional template headers. Some become message headers in
113
the delivery status notification; some control the format-
114
ting of that notification. Headers not specified in a tem-
115
plate will be left at their default value.
102
The first portion of a bounce template consists of optional template
103
headers. Some become message headers in the delivery status notifica-
104
tion; some control the formatting of that notification. Headers not
105
specified in a template will be left at their default value.
117
107
The following headers are supported:
120
The MIME character set of the template message
121
text. See the "TEMPLATE MESSAGE TEXT FORMAT"
110
The MIME character set of the template message text. See the
111
"TEMPLATE MESSAGE TEXT FORMAT" description below.
124
<b>From:</b> The sender address in the message header of the
125
delivery status notification.
113
<b>From:</b> The sender address in the message header of the delivery status
128
The subject in the message header of the delivery
129
status notification that is returned to the sender.
117
The subject in the message header of the delivery status notifi-
118
cation that is returned to the sender.
131
120
<b>Postmaster-Subject:</b>
132
The subject that will be used in Postmaster copies
133
of undeliverable or delayed mail notifications.
134
These copies are sent under control of the
135
<a href="postconf.5.html#notify_classes">notify_classes</a> configuration parameter.
137
The usage and specification of template message headers is
138
subject to the following restrictions:
140
<b>o</b> Template message header names can be specified in
141
upper case, lower case or mixed case. Postfix
142
always produces bounce message header labels of the
143
form "<b>From:</b>" and "<b>Subject:</b>".
145
<b>o</b> Template message headers must not span multiple
148
<b>o</b> Template message headers do not support $parameter
151
<b>o</b> Template message headers must contain ASCII charac-
152
ters only, and must not contain ASCII null charac-
121
The subject that will be used in Postmaster copies of undeliver-
122
able or delayed mail notifications. These copies are sent under
123
control of the <a href="postconf.5.html#notify_classes">notify_classes</a> configuration parameter.
125
The usage and specification of template message headers is subject to
126
the following restrictions:
128
<b>o</b> Template message header names can be specified in upper case,
129
lower case or mixed case. Postfix always produces bounce message
130
header labels of the form "<b>From:</b>" and "<b>Subject:</b>".
132
<b>o</b> Template message headers must not span multiple lines.
134
<b>o</b> Template message headers do not support $parameter expansions.
136
<b>o</b> Template message headers must contain ASCII characters only, and
137
must not contain ASCII null characters.
155
139
<b>TEMPLATE MESSAGE TEXT FORMAT</b>
156
The second portion of a bounce template consists of mes-
157
sage text. As the above example shows, template message
158
text may contain <a href="postconf.5.html">main.cf</a> $parameters. Besides the parame-
159
ters that are defined in <a href="postconf.5.html">main.cf</a>, the following parameters
160
are treated specially depending on the suffix that is
161
appended to their name.
140
The second portion of a bounce template consists of message text. As
141
the above example shows, template message text may contain <a href="postconf.5.html">main.cf</a>
142
$parameters. Besides the parameters that are defined in <a href="postconf.5.html">main.cf</a>, the
143
following parameters are treated specially depending on the suffix that
144
is appended to their name.
163
146
<b>delay_warning_time_</b><i>suffix</i>
164
Expands into the value of the <b><a href="postconf.5.html#delay_warning_time">delay_warning_time</a></b>
165
parameter, expressed in the time unit specified by
166
<i>suffix</i>, which is one of <b>seconds</b>, <b>minutes</b>, <b>hours,</b>
167
<b>days</b>, or <b>weeks</b>.
147
Expands into the value of the <b><a href="postconf.5.html#delay_warning_time">delay_warning_time</a></b> parameter,
148
expressed in the time unit specified by <i>suffix</i>, which is one of
149
<b>seconds</b>, <b>minutes</b>, <b>hours, days</b>, or <b>weeks</b>.
169
151
<b>maximal_queue_lifetime_</b><i>suffix</i>
170
Expands into the value of the <b><a href="postconf.5.html#maximal_queue_lifetime">maximal_queue_life</a>-</b>
171
<b><a href="postconf.5.html#maximal_queue_lifetime">time</a></b> parameter, expressed in the time unit speci-
172
fied by <i>suffix</i>. See above under <b><a href="postconf.5.html#delay_warning_time">delay_warning_time</a></b>
173
for possible <i>suffix</i> values.
175
The usage and specification of template message text is
176
subject to the following restrictions:
178
<b>o</b> The template message text is not sent in Postmaster
179
copies of delivery status notifications.
181
<b>o</b> If the template message text contains non-ASCII
182
characters, Postfix requires that the <b>Charset:</b> tem-
183
plate header is updated. Specify an appropriate
184
superset of US-ASCII. A superset is needed because
185
Postfix appends ASCII text after the message tem-
152
Expands into the value of the <b><a href="postconf.5.html#maximal_queue_lifetime">maximal_queue_lifetime</a></b> parameter,
153
expressed in the time unit specified by <i>suffix</i>. See above under
154
<b><a href="postconf.5.html#delay_warning_time">delay_warning_time</a></b> for possible <i>suffix</i> values.
156
The usage and specification of template message text is subject to the
157
following restrictions:
159
<b>o</b> The template message text is not sent in Postmaster copies of
160
delivery status notifications.
162
<b>o</b> If the template message text contains non-ASCII characters,
163
Postfix requires that the <b>Charset:</b> template header is updated.
164
Specify an appropriate superset of US-ASCII. A superset is
165
needed because Postfix appends ASCII text after the message tem-
186
166
plate when it sends a delivery status notification.
added
removed
html/bounce.5.html
