Controlling Delivery Status Notification Messages

Delivery status notifications or status notifications are email status messages sent by the MTA to the sender and, optionally, the postmaster. Messaging Server allows you to customize notification messages by content and language. You can also create different messages for each type of delivery status (for example, FAILED, BOUNCED, TIMEDOUT, etc.). In addition, you can create status notifications for messages originating from specific channels.

By default, status notifications are stored in the msg_svr_base/config/locale/C directory (specified by the IMTA_LANG setting in the msg_svr_base/config/imta_tailor file). The filenames are as follows:

return_bounced.txt, return_delivered.txt return_header.opt, return_timedout.txt, return_deferred.txt, return_failed.txt, return_prefix.txt, return_delayed.txt, return_forwarded.txt, return_suffix.txt.

Message text for *.txt files should be limited to 78 characters per line. Note that you shouldn’t change these files directly since they’ll be overwritten when the current version of Messaging Server is upgraded. If you wish to modify these files and use them as your only set of notification message template files (return_*.txt), copy the files to a new directory and edit them there. Then, set the IMTA_LANG option in the imta_tailor file to point to the new directory containing those templates. If you wish to have multiple sets of notification files (for example, a set for each language) then you will need to set up a NOTIFICATION_LANGUAGE mapping table.

To Construct and Modify Status Notifications

A single notification message is constructed from a set of three files: return_prefix.txt + return_ActionStatus.txt + return_suffix.txt

To customize or localize notifications, you would create a complete set of return_*.txt files for each locale and/or customization and store it in a separate directory. For example, you could have French notification files stored in one directory, Spanish for another, and notifications for a special unsolicited bulk email channel stored in a third.

Sample files for French, German, and Spanish are included in this release. These files can be modified to suit your specific needs.

For double-byte languages such as Japanese, be sure to construct your text in Japanese, then view the text as if it was ASCII to check for % characters. If there are accidental % characters, then replace them with %%.

The format and structure of status notification message sets is described below.

1. return_prefix.txt provides appropriate header text as well as introductory material for the body. The default for US-english locale is as follows:

   Content-type: text/plain; charset=us-asci Content-language: EN-US This report relates to a message you sent with the following header fields: %H

   Non-US-ASCII status notification messages should change the charset parameter and Content-Language header value appropriately (for example, for French localized files the values would be ISO-8859-1 and fr). %H is a header substitution sequence defined in Table 10–9.

2. return_<ActionStatus>.txt contains status-specific text. ActionStatus refers to a message’s MTA status type. For example, the default text for return_failed.txt is as follows:

   Your message cannot be delivered to the following recipients:%R

   The default text for return_bounced.txt is:

   Your message is being returned. It was forced to return bythe postmaster.

   The recipient list for this message was:%R

3. return_suffix.txt contains concluding text. By default this file is blank.

To Customize and Localize Delivery Status Notification Messages

Delivery Status Notification Messages can be localized such that messages will be returned to different users in different languages. For example, French notifications could be returned to users who have expressed a preference for French.

Localizing or customizing status notification messages consists of two steps:

1. Create a set of localized/customized return_*.txt message files and store each set in a separate directory. This is described in To Construct and Modify Status Notifications

2. Set up a NOTIFICATION_LANGUAGE mapping table.

The NOTIFICATION_LANGUAGE mapping table (located in msg_svr_base/config/mappings) specifies the set of localized or customized notification message files to use depending upon attributes (for example: language, country, domain, or address) of the originating message (the message causing the notification to be sent).

The original sender’s message is parsed to determine status notification type, source channel, preferred language, return address and first recipient. Depending on how the table is constructed, a set of notification files is selected depending on one or more of these attributes.

The format of the NOTIFICATION_LANGUAGE mapping table is as follows. The sample entry line has been wrapped for typographic reasons. The actual entry should appear on one physical line.

NOTIFICATION_LANGUAGE

 dsn-type-list|source-channel|preferred-language|return-address \
|first-recipient $Idirectory-spec

• dsn-type-list is a comma-separated list of delivery status notification types. If multiple types are specified, they must be separated by commas and without spaces (a space will terminate the pattern of the mapping table entry). The types are as follows:

  • failed - Generic permanent failure messages (for example, no such user). Uses the return_failed.txt file.

  • bounced - Notification message used in conjunction with manual “bounces.” Done by the postmaster. Uses the return_bounced.txt file.

  • timedout - The MTA has been unable to deliver the message within the time allowed for delivery. The message is now being returned. Uses the return_timedout.txt file.

  • delayed - The MTA has been unable to deliver the message, but will continue to try to deliver it. Uses the return_delayed.txt file.

  • deferred - Non-delivery notification similar to “delayed” but without an indication of how much longer the MTA will continue to try to deliver. Uses the return_deferred.txt file.

  • forwarded - A delivery receipt was requested for this message, however, this message has now been forwarded to a system that does not support such receipts. Uses the return_forwarded.txt file.

• source-channel is the channel generating the notification message, that is, the channel at which the message is currently queued. For example, ims-ms for the message store’s delivery queue, tcp_local for outbound SMTP queues, etc.

• preferred-language is the language expressed in the message being processed (the message for which the notification is being generated). The sources for this information are first the accept_language field. If that doesn’t exist the Preferred-language: header field and X-Accept-Language: header field are used. For a list of standard language code values, refer to the file msg_svr_base/config/languages.txt

  This field, if not empty, will be whatever the originator of the message specified for the Preferred-language: or X-Accept-language: header line. As such, you may find nonsense characters in this field.

• return-address is the envelope From: address of the originating message. This is the envelope address to which the notification message will be sent and hence a possible indicator of what language to use.

• first-recipient is the envelope To: address (the first one, if the message is failing to more than one recipient) to which the original message was addressed. For example, in the notification “your message to dan@siroe.com could not be delivered”—in this case dan@siroe.com is the envelope To: address being reported on.

• directory-spec is the directory containing the return_*.txt files to use if the mapping table probe matches. Note that a $I must precede the directory specification.

  For instance, a site that stores French notification files (return_*.txt) in a directory /lc_messages/table/notify_french/ and Spanish notification files in return_*.txt files in a directory /lc_messages/table/notify_spanish/ might use a table as shown below. Note that each entry must start with one or more spaces, and that there can be no blank lines between entries.

NOTIFICATION_LANGUAGE
 
! Preferred-language: header value specified
!
    *|*|fr|*|*     $I/lc_messages/table/notify_french/
    *|*|es|*|*     $IIMTA_TABLE/notify_spanish/
    *|*|en|*|*     $I/imta/lang/
!
! If no Preferred-language value, then select notification based on the
! country code in the domain name. EX: PF=French Polynesia; BO=Bolivia
!
    *|*|*|*.fr|*   $I/imta/table/notify_french/
    *|*|*|*.fx|*   $I/imta/table/notify_french/
    *|*|*|*.pf|*   $I/imta/table/notify_french/
    *|*|*|*.tf|*   $I/imta/table/notify_french/
    *|*|*|*.ar|*   $I/imta/table/notify_spanish/
    *|*|*|*.bo|*   $I/imta/table/notify_spanish/
    *|*|*|*.cl|*   $I/imta/table/notify_spanish/
    *|*|*|*.co|*   $I/imta/table/notify_spanish/
    *|*|*|*.cr|*   $I/imta/table/notify_spanish/
    *|*|*|*.cu|*   $I/imta/table/notify_spanish/
    *|*|*|*.ec|*   $I/imta/table/notify_spanish/
    *|*|*|*.es|*   $I/imta/table/notify_spanish/
    *|*|*|*.gp|*   $I/imta/table/notify_spanish/
    *|*|*|*.gt|*   $I/imta/table/notify_spanish/
    *|*|*|*.gy|*   $I/imta/table/notify_spanish/
    *|*|*|*.mx|*   $I/imta/table/notify_spanish/
    *|*|*|*.ni|*   $I/imta/table/notify_spanish/
    *|*|*|*.pa|*   $I/imta/table/notify_spanish/
    *|*|*|*.ve|*   $I/imta/table/notify_spanish/
                  

A default mappings.locale file is provided with the installation and will be included in the mappings file to enable notification language mapping. To disable notification language mapping, comment out the include line as follows:

! <IMTA_TABLE:mappings.locale

(Read the comments in the file and modify to suit your needs.)

Internationalization of Generated Notices

Two option files can be used for both the delivery status and message disposition notification. These are intended to make internationalization of generated notices more flexible. They are as follows:

IMTA_LANG:return_option.dat (DSN)IMTA_LANG:disposition_option.dat (MDN)

The options available for these files are described in Table 10–10.

Additional Status Notification Message Features

The essential procedures for setting up status notification messages is describe in the previous sections. The following sections describe additional functionality.

To Block Content Return on Large Messages

Typically, when a message is bounced or blocked, the content of the message is returned to sender and to the local domain postmaster in the notification message. This can be a strain on resources if a number of very large messages are returned in their entirety. To block the return of content for messages over a certain size, set the CONTENT_RETURN_BLOCK_LIMIT option in the MTA options file.

To Remove non-US-ASCII Characters from Included Headers in the Status Notification Messages

The raw format for Internet message headers does not permit non-US-ASCII characters. If non-US-ASCII characters are used in a message header they are encoded using “MIME header encoding” described in RFC 2047. Thus, a Chinese “Subject” line in an email message will actually look like this:

Subject: =?big5?Q?=A4j=AB=AC=A8=B1=AD=B1=B0=D3=F5=A5X=AF=B2?=

and it is the responsibility of email clients to remove the encoding when displaying headers.

Because the %H template copies headers into the body of the notification message, the encoded header text will normally appear. However, Messaging Server will remove the encoding if the character set in the subject (in this case “big5”) matches the character set in the Content-Type header character set parameter in return_prefix.txt. If it doesn’t match, the Messaging Server will leave the encoding intact.

To Set Notification Message Delivery Intervals

Keywords: notices, nonurgentnotices, normalnotices, urgentnotices

Undeliverable messages are held in a given channel queue for specified amount of time before being returned to sender. In addition, a series of status/warning messages can be returned to the sender while Messaging Server attempts delivery. The amount of time and intervals between messages can be specified with the notices, nonurgentnotices, normalnotices, or urgentnotices keywords. Examples:

notices 1 2 3

Transient failure status notification messages are sent after 1 and 2 days for all messages. If the message is still not delivered after 3 days, it is returned to its originator.

urgentnotices 2,4,6,8

Transient failure notifications are sent after 2, 4, and 6 days for messages of urgent priority. If the message is still not delivered after 8 days, it is returned to its originator.

Note that the RETURN_UNITS option in the MTA Options file allows you to specify the units in either hours (1) or days (0). The default is days (0). If you set RETURN_UNITS=1, then you will need to schedule the return job to run hourly as well to get hourly notices. When the return job runs every hour it will also roll over the mail.log* files every hour. To prevent the hourly rollover of the mail.log file, set the IMTA_RETURN_SPLIT_PERIOD tailor file option in the imta.tailor file to 24. Return job scheduling is controlled by the local.schedule.return_job configutil parameter.

If no notices keyword is specified, the default is to use the notices setting for the local, l, channel. If no setting has been made for the local channel, then the default is to use notices 3, 6, 9, 12.

To Include Altered Addresses in Status Notification Messages

Keywords: includefinal, suppressfinal, useintermediate

When the MTA generates a notification message (bounce message, delivery receipt message, and so on), there may be both an “original” form of a recipient address and an altered “final” form of that recipient address available to the MTA. The MTA always includes the original form (assuming it is present) in the notification message, because that is the form that the recipient of the notification message (the sender of the original message, which the notification message concerns) is most likely to recognize.

The includefinal and suppressfinal channel keywords control whether the MTA also includes the final form of the address. Suppressing the inclusion of the final form of the address may be of interest to sites that are “hiding” their internal mailbox names from external view. Such sites may prefer that only the original, “external” form of address be included in status notification messages. includefinal is the default and includes the final form of the recipient address. suppressfinal causes the MTA to suppress the final address form, if an original address form is present, from status notification messages.

The useintermediate keyword uses an intermediate form of the address produced after list expansion, but prior to user mailbox name generation. If this information isn’t available, the final form is used.

To Send, Block and Specify Status Notification Messages to the Postmaster

By default, a copy of failure and warning status notification messages are sent to the postmaster unless error returns and warnings are completely suppressed with a blank Errors-to: header line or a blank envelope From: address. Further granularity of notification message delivery to the postmaster can be controlled by a number of channel keywords described in the sections below and in Table 10–11.

Returned Failed Messages

Keywords: sendpost, nosendpost, copysendpost, errsendpost

A channel program may be unable to deliver a message because of long-term service failures or invalid addresses. When this occurs, the MTA channel program returns the message to the sender with an accompanying explanation of why the message was not delivered. Optionally, a copy of all failed messages is sent to the local postmaster. This is useful for monitoring message failures, but it can result in an excessive amount of traffic with which the postmaster must deal. (See Table 10–11.)

Warning Messages

Keywords:warnpost, nowarnpost, copywarnpost, errwarnpost

In addition to returning messages, the MTA can send detailed warnings for undelivered messages. This is generally due to time-outs based on the setting of the notices channel keyword, although in some cases channel programs may produce warning messages after failed delivery attempts. The warning messages contain a description of what’s wrong and how long delivery attempts continue. In most cases they also contain the headers and the first few lines of the message in question.

Optionally, a copy of all warning messages can be sent to the local postmaster. This can be somewhat useful for monitoring the state of the various queues, although it does result in lots of traffic for the postmaster to deal with. The keywords warnpost, copywarnpost, errwarnpost, and nowarnpost are used to control the sending of warning messages to the postmaster. (See Table 10–11.)

Blank Envelope Return Addresses

Keywords: returnenvelope

The returnenvelope keyword takes a single integer value, which is interpreted as a set of bit flags. Bit 0 (value = 1) controls whether or not return notifications generated by the MTA are written with a blank envelope address or with the address of the local postmaster. Setting the bit forces the use of the local postmaster address; clearing the bit forces the use of a blank address.

The use of a blank address is mandated by RFC 1123. However, some systems do not properly handle blank envelope From: addresses and may require the use of this option.

Bit 1 (value = 2) controls whether or not the MTA replaces all blank envelope addresses with the address of the local postmaster. This is used to accommodate noncompliant systems that do not conform to RFC 821, RFC 822, or RFC 1123.

Bit 2 (value = 4) prohibits syntactically invalid return addresses.

Bit 3 (value = 8) same as mailfromdnsverify keyword.

Postmaster Returned Message Content

Keywords:postheadonly, postheadbody

When a channel program or the periodic message return job returns messages to both the postmaster and the original sender, the postmaster copy can either be the entire message or just the headers. Restricting the postmaster copy to just the headers adds an additional level of privacy to user mail. However, this by itself does not guarantee message security; postmasters and system managers are typically in a position where the contents of messages can be read using root system privileges, if they so choose. (See Table 10–11.)

Setting Per Channel Postmaster Addresses

Keywords: aliaspostmaster, returnaddress, noreturnaddress, returnpersonal, noreturnpersonal

By default, the Postmaster’s return address that is used when the MTA constructs bounce or status notification messages is postmaster@local-host, where local-host is the official local host name (the name on the local channel), and the Postmaster personal name is “MTA e-Mail Interconnect.” Care should be taken in the selection of the Postmaster address—an illegal selection may cause rapid message looping and a great number of error messages.

The RETURN_ADDRESS and RETURN_PERSONAL options can be used to set an MTA system default for the Postmaster address and personal name. Or, if per channel controls are desired, the returnaddress and returnpersonal channel keywords may be used. returnaddress and returnpersonal each take a required argument specifying the Postmaster address and Postmaster personal name, respectively. noreturnaddress and noreturnpersonal are the defaults and signify that the default values should be used. The defaults are established via the RETURN_ADDRESS and RETURN_PERSONAL options or the normal default values if such options are not set.

If the aliaspostmaster keyword is placed on a channel, then any messages addressed to the user name postmaster (lowercase, uppercase, or mixed case) at the official channel name is redirected to postmaster@local-host, where local-host is the official local host name (the name on the local channel). Note that Internet standards require that any domain in the DNS that accepts mail have a valid postmaster account that receives mail. So this keyword can be useful when it is desired to centralize postmaster responsibilities, rather than setting separate postmaster accounts for separate domains. That is, whereas returnaddress controls what return postmaster address is used when the MTA generates a notification message from the postmaster, aliaspostmaster affects what the MTA does with messages addressed to the postmaster.