To detect bounced e-mail, the Oracle Commerce Platform uses the atg.service.email.pop.StoreService
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 StoreService
as a listener. When the StoreService
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 StoreService
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, which is an instance of class atg.service.email.pop.StoreService
, to retrieve mail from a POP3 e-mail server. The following table summarizes the key properties of this component:
Property | Function |
---|---|
| The protocol to use for retrieving messages, either Default: |
| User name for the e-mail account. |
| Password for the e-mail account. |
| 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 Oracle Commerce Platform 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 Oracle Commerce Platform products, only one of the Oracle Commerce Platform 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 can vary depending on the type of MTA (Mail Transfer Agent) that sent it. The StoreService
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/MSExchange5Examiner
and/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.
By default, most soft bounce reply codes being with the number 4. However, there are some soft bounce reply codes that begin with the number 5. For example the code 552 is used to produce an error indicating that the mail action was not completed because of exceeded storage allocation. You can identify additional codes by adding them in a comma separated list to the configuredSoftBounceCodes
property in the /atg/service/email/EmailSoftBounceCodes
properties file. For example:
configuredSoftBounceCodes=552, 598
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 StoreService
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.