Troubleshooting Bounced Campaign Email Processing

Overview

When a campaign email is sent to an invalid recipient (e.g. an email address that does not exist) a bounced message is returned to the sender; in the case of a SugarCRM campaign the bounced message would be delivered to the bounce handling mailbox chosen during the setup of the campaign. SugarCRM can be setup to process messages from bounce handling mailboxes and log any relevant bounces. Occasionally bounced messages may not be processed as expected. To understand why a message may not be processed it is important to understand the criteria SugarCRM depends on to properly process bounced messages.

Beginning with version 9.1.0, each user's license type (e.g. Sugar Serve) determines what functionality is available as described in the License Types Matrix documentation. Please note that the Campaigns module is not available for Sugar Serve users.

Sugar's Process

The steps for processing a bounced message are fairly simple:

1. SugarCRM will first check if the message is from "MAILER-DAEMON" or "POSTMASTER", if the message is not from either it will be ignored. This allows SugarCRM to ignore messages that are not bounce notifications. When an email server sends a bounced message it must provide a "From Address". A common "From Address" used by email servers for bounce notifications is "MAILER-DAEMON@whatever_domain.com" or "POSTMASTER@whatever_domain.com".
2. SugarCRM then checks the contents of the bounced message for an identifier key. Campaign emails are required to have an unsubscribe link in the body of the message. In SugarCRM this unsubscribe link contains an identifier key that is unique to the recipient and campaign message; this means that SugarCRM can identify the intended recipient and source campaign message from this single key. An unsubscribe link looks as follows: index.php?entryPoint=removeme&identifier={uniquely generated key} The identifier key is the only way SugarCRM can know the intended recipient of a bounced message. If the key is not present in the bounced message, the message will be ignored. This does pose problems when the original message is not included with the bounced message. Unfortunately, at this time, messages cannot be processed if the original message is not included with the bounced message.
3. The final step in the process is to lookup the targeted recipient and source campaign based on the identifier key and update the campaign log. Successfully processed bounced messages will appear on the status page of a campaign.

If you'd like to review the code responsible for processing bounced messages you can do so in the file "modules/Campaigns/ProcessBouncedEmails.php".