postfix-master/bounce.5.html

   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>
   7 BOUNCE(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> &lt;&lt;<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>  &lt;&lt;<b>'EOF'</b>).
  69        Here is an example:
  70
  71            # The failure template is used for undeliverable mail.
  72
  73            failure_template = &lt;&lt;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 &lt;&lt; context, the "$"  character  is  spe-
 100               cial. To produce a "$" character as output, specify
 101               "$$".
 102
 103        <b>o</b>      Outside the &lt;&lt; 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>