Handling Bounce Emails on XMS

XMS Mail Server has an optional filter called the Bounce Filter - it can recognize over 2,700 bounce message formats, using the b*Bounce library of regular expressions, and when it matches one a bounce handler is invoked to log the bounce details.

When you add the BounceFilter to the SMTPService configuration node, messages destined to an address found in the bounce list (specified in the bouncelistname attribute) will be parsed and handled by the handler defined in the handler child-tag. The handler must implement the xms.bounce.BounceHandler interface. The DatabaseBounceHandler is one implementation we provide. The BounceFilter can contain multiple handlers. You may want to use the stock DatabaseBounceHandler to log bounces to the database and create your own custom handlers for list management or other tasks.

The primary advantage to doing bounce processing on the mail server is that actions can be taken while the message is being processed by the server, such as redirecting challenge response bounces to separate addresses for each bounce address when the bounce address is found in the challenge response map specified in the challengeResponseMap attribute. It will also be possible in a future update to pause an entire campaign for certain types of bounces received on the campaign.

Bounce processing can consume considerable resources. If you expect to handle a large number of bounces, you'll want to weigh the advantages against the performance costs. Connections may be denied during periods where a large number of bounce messges are being handled, depending on a number of factors, including the format of the bounce messages. Common formats will be matched quickly, while uncommon formats may require hundreds or thousands of regular expressions to be evaluated. Future implementations will include monitors to help you measure the load factor and a load balanced version that would enable the target of the message to be changed to another XMS server. If your sending out a large number of emails you may want to setup a dedicated XMS server for handling bounces.

VERP is supported by BounceFilter. VERP (Variable Envelope Return Path) insures that the original recipient information is available in a delivery status notification (bounce) message by encoding the original recipient in the envelope sender. The VERP address is formatted verpPrefix[recipientUsername]=[recipientDomain]@senderDomain. When a message is found to contain a VERP address the VERP address is used to determine the original recipient instead of the address found in the message body, since the message may have been forwarded and would not contain the correct original recipient. Some bounce formats don't include any of the original message or headers. To effectively implement VERP, your client application will need to set the envelope sender with the VERP address. It's very common to have a member of a list abandon an address while forgetting or not bothering to unsubscribe to lists containing the address and since you may be penalized by some ISPs for breaching a bounce threshold, it's nice to be able to handle the list removal automatically for certain bounce types. Since multiple BounceHandlers can be added to the BounceFilter, handling tasks such as this and nearly anything imagineable is greatly simplified.

Configuring the Bounce Filters, and Handlers

The first thing you need to do is create a list of addresses that the bounce filter will process. Name the list bounceAddressList and register it with the StringList Service (click link for example). The list will contain addresses like [email protected] or [email protected].

To process bounces with XMS you need to add a BounceFilter to your SMTP server service (xms.transport.smtp.SMTPService). This is done by adding a filter tag inside the service tag with the class xms.transport.smtp.SMTPService.

Since we will be using the Database Bounce Handler you need to create a database, a table, and a datasource to log all your bounce messages. In this example the table is called bounces and the columns are named: bounceAddress, recipientAddress, subject, message, xheader, bouncetype, bounceindex, statusmessage, and bounceTime

Once you created the database, and table, create a datasource listing in your configuration file using the datasource service. Click here for an example.

<service class="xms.transport.smtp.SMTPService" 
 name="smtpserver" target="spool" port="25" address="*" hostname="mail.yourcompany.com">
    
    <filter class="xms.bounce.BounceFilter" 
      bouncelistname="bounceAddressList"
      action="accept"
      xheader="X-CID"> 
   		<handler class="xms.bounce.DatabaseBounceHandler"
		  datasourcename="bounceDataSource"
		  table="bounces"
		  returnPathColumn="bounceAddress"
		  bouncedemailcolumn="recipientAddress"
		  subjectcolumn="subject"
		  messagecolumn="message"
		  xheadercolumn="xheader"
		  bouncetypecolumn="bouncetype"
		  definitionIndexColumn="bounceindex"
		  statusColumn="statusmessage"
		  timeColumn="bounceTime" />
		   
		<!-- other handlers here -->
		
   </filter>
    
    <!-- other SMTP filters here -->
  
</service>