1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 5<title> Postfix manual - bounce(5) </title> 6</head> <body> <pre> 7BOUNCE(5) BOUNCE(5) 8 9<b>NAME</b> 10 bounce - Postfix bounce message template format 11 12<b>SYNOPSIS</b> 13 <b><a href="postconf.5.html#bounce_template_file">bounce_template_file</a> = /etc/postfix/bounce.cf</b> 14 15 <b>postconf -b</b> [<i>template</i><b>_</b><i>file</i>] 16 17<b>DESCRIPTION</b> 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 21 requests. 22 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- 27 uration parameter. 28 29 This document describes the general procedure to create a 30 bounce template file, followed by the specific details of 31 bounce template formats. 32 33<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. 37 38 To preview the results of $<i>name</i> expansions in the template 39 text, use the command 40 41 <b>postconf -b</b> <i>temporary</i><b>_</b><i>file</i> 42 43 Errors in the template will be reported to the standard 44 error stream and to the syslog daemon. 45 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. 49 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> 52 something like: 53 54 /etc/postfix/<a href="postconf.5.html">main.cf</a>: 55 <a href="postconf.5.html#bounce_template_file">bounce_template_file</a> = /etc/postfix/bounce.cf 56 57<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. 64 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>). 69 Here is an example: 70 71 # The failure template is used for undeliverable mail. 72 73 failure_template = <<EOF 74 Charset: us-ascii 75 From: MAILER-DAEMON (Mail Delivery System) 76 Subject: Undelivered Mail Returned to Sender 77 Postmaster-Subject: Postmaster Copy: Undelivered Mail 78 79 This is the mail system at host $<a href="postconf.5.html#myhostname">myhostname</a>. 80 81 I'm sorry to have to inform you that your message could not 82 be delivered to one or more recipients. It's attached below. 83 84 For further assistance, please send mail to postmaster. 85 86 If you do so, please include this problem report. You can 87 delete your own text from the attached returned message. 88 89 The mail system 90 EOF 91 92 The usage and specification of bounce templates is subject 93 to the following restrictions: 94 95 <b>o</b> No special meaning is given to the backslash char- 96 acter or to leading whitespace; these are always 97 taken literally. 98 99 <b>o</b> Inside the << context, the "$" character is spe- 100 cial. To produce a "$" character as output, specify 101 "$$". 102 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. 106 107 Examples of all templates can be found in the file 108 <b>bounce.cf.default</b> in the Postfix configuration directory. 109 110<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. 116 117 The following headers are supported: 118 119 <b>Charset:</b> 120 The MIME character set of the template message 121 text. See the "TEMPLATE MESSAGE TEXT FORMAT" 122 description below. 123 124 <b>From:</b> The sender address in the message header of the 125 delivery status notification. 126 127 <b>Subject:</b> 128 The subject in the message header of the delivery 129 status notification that is returned to the sender. 130 131 <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. 136 137 The usage and specification of template message headers is 138 subject to the following restrictions: 139 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>". 144 145 <b>o</b> Template message headers must not span multiple 146 lines. 147 148 <b>o</b> Template message headers do not support $parameter 149 expansions. 150 151 <b>o</b> Template message headers must contain ASCII charac- 152 ters only, and must not contain ASCII null charac- 153 ters. 154 155<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. 162 163 <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>. 168 169 <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. 174 175 The usage and specification of template message text is 176 subject to the following restrictions: 177 178 <b>o</b> The template message text is not sent in Postmaster 179 copies of delivery status notifications. 180 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- 186 plate when it sends a delivery status notification. 187 188<b>SEE ALSO</b> 189 <a href="bounce.8.html">bounce(8)</a>, Postfix delivery status notifications 190 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 191 192<b>LICENSE</b> 193 The Secure Mailer license must be distributed with this 194 software. 195 196<b>HISTORY</b> 197 The Postfix bounce template format was originally devel- 198 oped by Nicolas Riendeau. 199 200<b>AUTHOR(S)</b> 201 Wietse Venema 202 IBM T.J. Watson Research 203 P.O. Box 704 204 Yorktown Heights, NY 10598, USA 205 206 BOUNCE(5) 207</pre> </body> </html> 208