external/ibm-public/postfix/dist/man/man5/bounce.5

   1 .\"     $NetBSD$
   2 .\"
   3 .TH BOUNCE 5
   4 .ad
   5 .fi
   6 .SH NAME
   7 bounce
   8 \-
   9 Postfix bounce message template format
  10 .SH "SYNOPSIS"
  11 .na
  12 .nf
  13 \fBbounce_template_file = /etc/postfix/bounce.cf\fR
  14
  15 \fBpostconf -b\fR [\fItemplate_file\fR]
  16 .SH DESCRIPTION
  17 .ad
  18 .fi
  19 The Postfix \fBbounce\fR(8) server produces delivery status
  20 notification (DSN) messages for undeliverable mail, delayed
  21 mail, successful delivery or address verification requests.
  22
  23 By default, these notifications are generated from built-in
  24 templates with message headers and message text. Sites can
  25 override the built-in information by specifying a bounce
  26 template file with the \fBbounce_template_file\fR configuration
  27 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 .SH "GENERAL PROCEDURE"
  33 .na
  34 .nf
  35 .ad
  36 .fi
  37 To create a customized bounce template file, create a
  38 temporary
  39 copy of the file \fB/etc/postfix/bounce.cf.default\fR and
  40 edit the temporary file.
  41
  42 To preview the results of $\fIname\fR expansions in the
  43 template text, use the command
  44
  45 .nf
  46     \fBpostconf -b\fR \fItemporary_file\fR
  47 .fi
  48
  49 Errors in the template will be reported to the standard
  50 error stream and to the syslog daemon.
  51
  52 While previewing the text, be sure to pay particular attention
  53 to the expansion of time value parameters that appear in
  54 the delayed mail notification text.
  55
  56 Once the result is satisfactory, copy the template to the
  57 Postfix configuration directory and specify in main.cf
  58 something like:
  59
  60 .nf
  61 /etc/postfix/main.cf:
  62     bounce_template_file = /etc/postfix/bounce.cf
  63 .fi
  64 .SH "TEMPLATE FILE FORMAT"
  65 .na
  66 .nf
  67 .ad
  68 .fi
  69 The template file can specify templates for failed mail,
  70 delayed mail, successful delivery or for address verification.
  71 These templates are named \fBfailure_template\fR,
  72 \fBdelay_template\fR, \fBsuccess_template\fR and
  73 \fBverify_template\fR, respectively.  You can but do not
  74 have to specify all four templates in a bounce template
  75 file.
  76
  77 Each template starts with "\fItemplate_name\fB = <<EOF\fR"
  78 and ends with a line that contains the word "\fBEOF\fR"
  79 only. You can change the word EOF, but you can't enclose
  80 it in quotes as with the shell or with Perl (\fItemplate_name\fB
  81 = <<'EOF'\fR). Here is an example:
  82
  83 .nf
  84     # The failure template is used for undeliverable mail.
  85
  86     failure_template = <<EOF
  87     Charset: us-ascii
  88     From: MAILER-DAEMON (Mail Delivery System)
  89     Subject: Undelivered Mail Returned to Sender
  90     Postmaster-Subject: Postmaster Copy: Undelivered Mail
  91
  92     This is the mail system at host $myhostname.
  93
  94     I'm sorry to have to inform you that your message could not
  95     be delivered to one or more recipients. It's attached below.
  96
  97     For further assistance, please send mail to postmaster.
  98
  99     If you do so, please include this problem report. You can
 100     delete your own text from the attached returned message.
 101
 102                        The mail system
 103     EOF
 104 .fi
 105 .PP
 106 The usage and specification of bounce templates is
 107 subject to the following restrictions:
 108 .IP \(bu
 109 No special meaning is given to the backslash character or
 110 to leading whitespace; these are always taken literally.
 111 .IP \(bu
 112 Inside the << context, the "$" character is special. To
 113 produce a "$" character as output, specify "$$".
 114 .IP \(bu
 115 Outside the << context, lines beginning with "#" are ignored,
 116 as are empty lines, and lines consisting of whitespace only.
 117 .PP
 118 Examples of all templates can be found in the file
 119 \fBbounce.cf.default\fR in the Postfix configuration
 120 directory.
 121 .SH "TEMPLATE HEADER FORMAT"
 122 .na
 123 .nf
 124 .ad
 125 .fi
 126 The first portion of a bounce template consists of optional
 127 template headers.  Some become message headers in the
 128 delivery status notification; some control the formatting
 129 of that notification. Headers not specified in a template
 130 will be left at their default value.
 131
 132 The following headers are supported:
 133 .IP \fBCharset:\fR
 134 The MIME character set of the template message text.  See
 135 the "TEMPLATE MESSAGE TEXT FORMAT" description below.
 136 .IP \fBFrom:\fR
 137 The sender address in the message header of the delivery
 138 status notification.
 139 .IP \fBSubject:\fR
 140 The subject in the message header of the delivery status
 141 notification that is returned to the sender.
 142 .IP \fBPostmaster-Subject:\fR
 143 The subject that will be used in Postmaster copies of
 144 undeliverable or delayed mail notifications. These copies
 145 are sent under control of the notify_classes configuration
 146 parameter.
 147 .PP
 148 The usage and specification of template message headers is
 149 subject to the following restrictions:
 150 .IP \(bu
 151 Template message header names can be specified in upper
 152 case, lower case or mixed case. Postfix always produces
 153 bounce message header labels of the form "\fBFrom:\fR" and
 154 "\fBSubject:\fR".
 155 .IP \(bu
 156 Template message headers must not span multiple lines.
 157 .IP \(bu
 158 Template message headers do not support $parameter expansions.
 159 .IP \(bu
 160 Template message headers must contain ASCII characters only,
 161 and must not contain ASCII null characters.
 162 .SH "TEMPLATE MESSAGE TEXT FORMAT"
 163 .na
 164 .nf
 165 .ad
 166 .fi
 167 The second portion of a bounce template consists of message
 168 text. As the above example shows, template message text may
 169 contain main.cf $parameters. Besides the parameters that are
 170 defined in main.cf, the following parameters are treated
 171 specially depending on the suffix that is appended to their
 172 name.
 173 .IP \fBdelay_warning_time_\fIsuffix\fR
 174 Expands into the value of the \fBdelay_warning_time\fR
 175 parameter, expressed in the time unit specified by
 176 \fIsuffix\fR, which is one of \fBseconds\fR, \fBminutes\fR,
 177 \fBhours\fB, \fBdays\fR, or \fBweeks\fR.
 178 .IP \fBmaximal_queue_lifetime_\fIsuffix\fR
 179 Expands into the value of the \fBmaximal_queue_lifetime\fR
 180 parameter, expressed in the time unit specified by
 181 \fIsuffix\fR.  See above under \fBdelay_warning_time\fR for
 182 possible \fIsuffix\fR values.
 183 .PP
 184 The usage and specification of template message text is
 185 subject to the following restrictions:
 186 .IP \(bu
 187 The template message text is not sent in Postmaster copies
 188 of delivery status notifications.
 189 .IP \(bu
 190 If the template message text contains non-ASCII characters,
 191 Postfix requires that the \fBCharset:\fR template header
 192 is updated.  Specify an appropriate superset of US-ASCII.
 193 A superset is needed because Postfix appends ASCII text
 194 after the message template when it sends a delivery status
 195 notification.
 196 .SH "SEE ALSO"
 197 .na
 198 .nf
 199 bounce(8), Postfix delivery status notifications
 200 postconf(5), configuration parameters
 201 .SH "LICENSE"
 202 .na
 203 .nf
 204 .ad
 205 .fi
 206 The Secure Mailer license must be distributed with this software.
 207 .SH "HISTORY"
 208 .na
 209 .nf
 210 .ad
 211 .fi
 212 The Postfix bounce template format was originally developed by
 213 Nicolas Riendeau.
 214 .SH "AUTHOR(S)"
 215 .na
 216 .nf
 217 Wietse Venema
 218 IBM T.J. Watson Research
 219 P.O. Box 704
 220 Yorktown Heights, NY 10598, USA