Amazon SES Integration

This page lists special considerations when using Amazon SES as a relay server with GreenArrow. These steps are specific to Amazon SES and should be executed in addition to the steps required to setup an SMTP relay server

For more information on other steps necessary to integrate external relay services see Integrating with SMTP Relay Services

Amazon SES Email Verification

Amazon only relays messages that are sent from email addresses that have been verified.

Amazon SES requires the following email addresses to be verified:

• The From address
• The Sender address - this is only necessary if you plan to use a Sender header
• The Return Path - also known as bounce address, SMTP FROM address and envelope sender

This documentation from Amazon has all of the steps necessary to verify the specific From and Sender email addresses.

Verifying the Return Path

Amazon SES does not recognize the VERP method GreenArrow uses to encode the variable part of the bounce address. This means that, to Amazon, every message that GreenArrow sends has a unique bounce address that needs to be verified.

Because of this, we recommend verifying GreenArrow’s Return Path address by verifying the whole domain you’re using in the Return Path address.

This documentation from Amazon has all of the steps necessary to verify a domain.

NOTE: If domain verification is not possible then there is a more complicated alternative method to verify the Return Path address (including GreenArrow’s VERP portion) using Amazon’s wildcard feature. This method is described in the last section of this document.

Set Up Amazon SES Notifications

Since Amazon SES is the MTA handling the final delivery of your emails, all bounces and spam complaints will be directed back to them. By default, this leaves GreenArrow without any knowledge of a bounce or spam complaint ever happening.

If you would like GreenArrow to receive a copy of any bounce or spam complaints, you will need to set up Amazon SES Notification Through Email.

Testing Amazon SES bounces and spam complaints

We recommend thorough testing of bounces and spam complaints after setting up Amazon SES as a relay.

To test the relay end to end, use the email addresses that Amazon publishes in the following article: http://docs.aws.amazon.com/ses/latest/DeveloperGuide/mailbox-simulator.html

Testing from GreenArrow Studio

1. Create a test mailing list
2. Add the email addresses listed in the Mailbox Simulator article
3. Create and send a campaign to the mailing list
4. Check the statistics for the campaign, you should see bounces and spam complaints

Testing from GreenArrow Engine

1. Send a message to the email addresses listed in the Mailbox Simulator article from your injection application
2. Check the statistics for the send, you should see bounces and spam complaints

Alternative Return Path verification method

GreenArrow encodes information about the subscriber and campaign in the Return Path, using Variable Envelope Return Path (VERP). To separate the base from the sub-address (the variable portion) in the localpart, GreenArrow uses a - character. Amazon recognizes + as the separator between the base address and sub-address.

By creating a bounce mailbox in Engine that ends with a + character, GreenArrow will set the Return Path to an address that has a + between the static and variable portions of the address, which will be a valid VERP address on Amazon. Then it’s just a matter of following the instructions to verify a single email address, with the bounce mailbox email address without the + sign.

Here are the steps:

1. Create the bounce mailbox with the + at the end of the localpart (e.g.[email protected])
2. Create an email forwarder with the localpart but without the + character that forwards to a mailbox that you can access - this is where Amazon will send the verification email (e.g. [email protected]).
3. Follow Amazon’s instructions to verify the email address without the + ([email protected])
4. Update the bounce address configuration for messages injected into Engine (see details below)
5. Remove the forwarder after verifying the email address
6. Thoroughly test bounces and spam complaints as explained in the section above.

Updating Engine’s bounce address configuration

SimpleMH’s bounce address needs to be updated in any place where it is set or overridden:

1. Update the $RETURN_PATH_OVERRIDE variable in SimpleMH’s configuration file
2. Update any mail classes that use the Override Default Bounce Address option (if needed)
3. Update injection code that sets the X-GreenArrow-BounceMailboxOverride header

These must be updated with the new bounce address, that includes the + character.

Example

• Setting up the new bounce address and the temporary email forwarder:

• Updating the $RETURN_PATH_OVERRIDE in /var/hvmail/control/simplemh-config:

  $RETURN_PATH_OVERRIDE = 'return+-%%VERP%%@acme.net';
  

• Updating the X-GreenArrow-BounceMailboxOverride header (if needed) - the same update should be applied to all mail classes that override the bounce address:

  X-GreenArrow-BounceMailboxOverride: [email protected]
  

In the example, the bounce address is [email protected] (2) and the forwarder [email protected] (1) was created to forward Amazon’s verification emails to [email protected]. The forwarder can be removed after verifying the bounce address.