To detect bounced e-mail, ATG provides the atg.service.email.pop.POP3Service class. This service implements a standard POP3 e-mail client. It periodically checks for incoming mail on a specified POP3 server, and it determines which messages are bounced-back messages. For each bounced message, it generates an event of class atg.service.email.pop.MailBounceEvent, which contains information about the bounced message.
The Personalization module includes an atg.userprofiling.email.EmailManager class which handles these events. An EmailManager component registers itself with the POP3Service as a listener. When the POP3Service generates a mail bounce event, the EmailManager looks at the e-mail address of the bounced message, finds all profiles that use that address, and marks those profiles as being ineligible for receiving e-mail by setting the emailStatus property to invalid.
Once a user’s profile is marked as ineligible to receive e-mail, future mailings will skip this user. This cuts down on the number of bounced messages and provides a mechanism for flagging users with invalid e-mail addresses. For example, when a user logs into a site, you could check if the user’s e-mail address is marked as invalid, and if it is, prompt the user to enter a new address. When the new address is submitted, your application should then set the emailStatus property to valid to include this user in future mailings.
Note also that the InboundEmail event in the Scenarios module is fired whenever the POP3Service receives an e-mail, and it contains various properties that you can use to create scenarios triggered by the arrival of bounced e-mails. For example, you could set up a scenario that notifies your customer service department when a bounced e-mail is received. For more information, refer to InboundEmail Event.
Enabling Bounced E-mail Detection
To enable bounced e-mail detection, you must configure the /atg/dynamo/service/POP3Service component to retrieve mail from a POP3 e-mail server. The following table summarizes the key properties of this component:
Property | Function |
|---|---|
| User name for the e-mail account. Default: |
| Password for the e-mail account. Default: |
| Name of the POP server, for example |
| Interval at which the component checks the POP server for new e-mail. Default: |
| The name of the service that the component uses to schedule the task of checking for new e-mail. Default: |
| Directory for the POP client to store e-mail attachments. Default: |
| Indicates whether to delete bounced-back e-mail messages from the server after retrieving them. Default: |
| Indicates whether to delete e-mail messages (other than bounced-back messages) from the server after retrieving them. Default: |
| An array of Default:
|
In addition to the POP3Service component, you must also have an EmailManager component running. To ensure that both of these services start up when your ATG application starts, add them to the initialServices property of an atg.nucleus.InitialService component, such as the /atg/dynamo/service/Initial component.
Note that there must be only one instance of each of these services on a site. In other words, if an application has a single database but multiple servers running ATG products, only one of the ATG servers should run these services.
You must also configure and enable the specific emailExaminer components that you want the POP3Service to use to identify bounced e-mail messages. See the next section, Detecting Bounced E-mail Messages from Different MTAs.
Detecting Bounced E-mail Messages from Different MTAs
The format of each bounced message that the POP3Service receives can vary depending on the type of MTA (Mail Transfer Agent) that sent it. The POP3Service handles these different formats by means of one or more implementations of the atg.service.email.examiner.EmailExaminer interface. Several classes that implement this interface are supplied by default with the Personalization module:
atg.service.email.examiner.SendmailEmailExaminer. See SendmailExaminer Component for more information.atg.service.email.examiner.EximEmailExaminer. See EximExaminer Component.atg.service.email.examiner.RegExEmailExaminer. You can use this class to detect bounced messages from other MTAs by configuring regular expressions. (The examiner looks for configurable string expressions inside the text of the bounced message to determine the various properties of the e-mail.) Two default implementations are provided for interpreting bounced Microsoft Exchange Server messages:/atg/dynamo/service/MSExchange5Examinerand/atg/dynamo/service/MSExchange6Examiner.
You specify the examiner component or components you want to use to check bounced e-mail messages in the emailExaminers property of the POP3Service component.
SendmailExaminer Component
The /atg/dynamo/service/SendmailExaminer component is an implementation of the atg.service.email.examiner.SendmailEmailExaminer class that you can use to detect bounced e-mail messages returned by sendmail MTA systems.
The component determines whether a message is bounced by looking for specific String expressions within the message text. For example, the following text would allow this component to determine that the message is bounced:
<<< 550 5.1.1 <noone@example.com>... User unknown
The SendmailExaminer component looks for the String <<< n, where n is any of the reply codes specified in the component’s monitoredBounceReplyCodes property (550, in this example). If the String exists, the message is considered bounced.
In addition, it checks for any reply codes that are specified in the monitoredBounceReplyCodes property (see below).
An RFC 1893 enhanced status code appears after the bounce indicator String. In this example, the value is 5.1.1. This implementation assumes a space character after the reply code followed by a status code that is 5 characters long. The bounced e-mail address (here, noone@example.com) appears between the < and > characters after the bounced indicator. The error message appears after the first ... that is found after the bounce indicator. In this example, the error message is User unknown. Note that the text of the error message is a mail server-specific interpretation of the status code, and therefore the error message varies from one mail server to another.
The SendmailExaminer component is not enabled by default. It contains the following key properties:
Property | Description |
|---|---|
| The MTA format to which this examiner corresponds. Default: |
| An array of Strings that represent RFC 821 reply codes from bounced e-mail messages. When an examiner checks an e-mail message to see if it is bounced, it looks for specific text and a reply code. If the If the |
EximExaminer Component
The /atg/dynamo/service/EximExaminer component is an implementation of the atg.service.email.examiner.EximEmailExaminer class that you can use to detect bounced e-mail messages returned by exim MTA systems.
The component determines whether a message is bounced by looking for the following header in the message:
X-failed-recipients
In addition, it checks for any reply codes that are specified in the monitoredBounceReplyCodes property (see below).
This component is not enabled by default. It contains the following key properties:
Property | Description |
|---|---|
| The MTA format to which this examiner corresponds. Default: |
| An array of Strings that represent RFC 821 reply codes from bounced e-mail messages. When an examiner checks an e-mail message to see if it is bounced, it looks for specific text and a reply code. If the If the |
Identifying Soft-Bounced Messages
A “soft bounce” can be defined as a transient delivery failure, one where a message is bounced for reasons that are usually temporary, for example the user’s mailbox is full or a server is too busy to handle the request. In such cases you may want to resend the mailing at a later time or otherwise identify the bounced e-mail recipient as only temporarily unavailable. The softBounceReplyCodes and softBounceEnhancedStatusCodes properties in the EmailExaminer implementations described above can be used to track soft bounce messages, which are identified by their RFC 821 and 1893 error codes.
Retrieving Tracking Data from a Bounced E-mail
You can send tracking data with a mailing for subsequent retrieval from a bounced message. To add tracking data to a mailing, add name/value pairs to the trackingData Map property in the TemplateEmailInfoImpl object. Alternatively, call the appropriate methods in the atg.service.email.TrackableEmailSender interface, which is implemented by the atg.service.email.SMTPEmailSender class (/atg/dynamo/service/SMTPEmail or /atg/dynamo/service/EmailListenerQueue components). As described earlier, when the POP3Service receives a bounced e-mail, it sends out bounce events to any configured listeners. The trackingData Map property in the bounce events contains any tracking data that could be retrieved from the bounced message.
