SMTP Relay Service Integration

• Table of Contents
• Overview
• Details of integration
  • Handing off messages
  • Bounces
  • Spam complaints
  • List-Unsubscribe headers
• Caveats on SMTP relay service suppression
• Integrating with specific services.

Overview

Some GreenArrow Engine users choose to send email through a SMTP relay service (such as SendGrid, Amazon SES, or Mandrill) instead of sending email directly through their own IP addresses.

Some common reasons for doing this are:

• As an intermediary step as a user is migrating from one of these SMTP relay services to directly deliver through GreenArrow
• Because the user desires to have their email in the shared IP pool of the SMTP relay services (and the user does not want to use or qualify for GreenArrow’s shared IP pool service)
• Because the user does not desire to manage deliverability of their own IP addresses or have GreenArrow manage that deliverability for them

Details of integration

The broad overview of integration is that:

1. Messages must be handed off to the relay service via SMTP
2. Bounces, spam complaints, and unsubscribes must be suppressed on the remote relay server, or delivered back to GreenArrow for processing.

Handing off messages

To hand messages to the SMTP relay service, configure a “Relay Server” in the GreenArrow Engine web-interface with your account information for the SMTP relay service.

Once this Relay Server VirtualMTA is configured, it will be available as an option for you to choose in either the SimpleMH Mail Class config or in GreenArrow Studio’s Delivery Settings.

Bounces

Preferred method

It’s preferable if the SMTP relay service will do the following:

• Deliver or forward a bounce message to the original Return-Path of the email message (the one that GreenArrow added). (This is standards compliant, as the Return-Path of an email message is the email address that bounce messages should be sent to.)

If this is done, then all bounce related processing, suppression, and reporting will work normally in GreenArrow. (Ensure that you have configured Engine and/or Studio correctly.)

Other methods

If the relay services will not do the above, then some other method must be used to ensure that you don’t email to email addresses that are detected as bad through bouncing.

Some options are:

• The SMTP Relay Service may suppress the bad addresses internally. (See caveats below on “SMTP relay service suppression”)
• You could export the bad addresses from the SMTP Relay Services and update your database.
• Receive a web-hook notification from the SMTP Relay Service and update your database.

Spam complaints

Preferred method

It’s preferable if the SMTP relay service will do one of the following when there is a spam complaint:

• Forward the email that generated the spam complaint to a “spam complaint processing address” in GreenArrow Engine. This forwarded email must contain the original X-Mailer-Info header that was included in the original email.
• Forward the ARF formatted spam complaint notification from the ISP to a “spam complaint processing address” in GreenArrow Engine. (ARF format is the standards-compliant method for sharing feedback loop complaints.)
• Send any email containing the X-Mailer-Info header added by GreenArrow to the a “spam complaint processing address” in GreenArrow Engine

If any of these are done, then spam complaint processing, suppression, and reporting will work normally in GreenArrow Engine and/or Studio. (Ensure that you have configured Engine and/or Studio correctly.)

Other methods

If the relay services will not do this, then some other method must be used to ensure that you don’t send more email to addresses have complained about spam in the past. Some options are:

• The SMTP Relay Service may suppress the spam complainers internally. (See caveats below on “SMTP relay service suppression”)
• You could export the spam complainers from the SMTP Relay Services and update your database.
• Receive a web-hook notification from the SMTP Relay Service and update your database.

List-Unsubscribe headers

Preferred method

GreenArrow adds a List-Unsubscribe header with the following attributes:

• Both HTTP and email address (mailto) unsubscribe methods when it’s added by Studio.
• An email address method only by default when generated by SimpleMH. SimpleMH can be configured to also add an HTTP unsubscribe method by using the X-GreenArrow-List-Unsubscribe-HTTP-URL header.

It’s preferable that the SMTP relay service do one of the following:

• Leave the GreenArrow List-Unsubscribe header intact.
• Replace the GreenArrow’s List-Unsubscribe header with its own header, but when an unsubscribe request is received, to pass that unsubscribe request on to GreenArrow by triggering one of the methods in GreenArrow’s List-Unsubscribe header.

If any of these are done, the GreenArrow will work normally.

Other methods

If the relay service is inserting its own List-Unsubscribe header and not passing the unsubscribe data onto GreenArrow, then some other method must be used to stop emailing these unsubscribes. Some options are:

• The SMTP Relay Service may suppress the unsubscribes internally. (See caveats below on “SMTP relay service suppression”)
• You could export the unsubscribes from the SMTP Relay Services and update your database.
• Receive a web-hook notification from the SMTP Relay Service and update your database.

Caveats on SMTP relay service suppression

It’s common that a SMTP relay service will suppress your ability to email to addresses that they have detected should not be emailed again (either through bounce messages, spam complaints, or unsubscribes). This is a useful feature, but it also has the potential to cause problems.

If you’re using suppression in the SMTP relay service, then:

• You must synchronize the list of suppressed addresses back to your system BEFORE you email your list through another service or through a direct IP address. This is because another service or a direct IP is not able to suppress these addresses, and you’ll suddenly start emailing to everyone that bounced, spam complained, or unsubscribed. This is a recipe for a deliverability disaster, as well as being illegal in the United States (under the CAN-SPAM law).

• The number of emails sent shown in GreenArrow will be more than the number of emails sent by the Relay Service after the suppression is applied. This will effect your open and click rates in GreenArrow.

• It will not be possible for a subscriber to re-subscribe to your list.

Integrating with specific services.

As a convenience, we have documents that describe how to integrate with the following services:

• Amazon SES
• Sendgrid