Understanding Amazon SES Configuration Sets and how Engage uses them

Opeyemi Obembe -

Configuration Sets are settings for emails you send using Amazon Simple Email Service (SES). They are broadly used for tracking email events and sending emails with dedicated IPs.

Outline:

How Engage uses configuration sets

Configuration Sets are how Engage is able to track your Amazon SES transactional emails and provide analytics and reporting. When you add an SES domain to Engage, the application automatically creates a configuration set for you. To do this, we request your IAM credentials with SNS and SES access.

Here is the breakdown of the process in 4 steps.

  1. Engage creates a SNS Topic. This is named engage_so for easy identification.
  2. A subscription to the topic is created. The subscription points the topic to a webhook that can process messages to the SNS topic.
  3. Engage creates the configuration set. This is also named engage_so.
  4. Engage creates the configuration set's event destination. This involves 2 things: selecting the events to track and pointing the configuration set to the SNS topic created earlier. The events tracked are reject, bounce, complaint, delivery, open and click.

What the requested access keys are used for

When you add an SES domain to Engage, we request an IAM credentials with full SNS and SES access. The SNS and SES permissions are used to create and manage the SNS topic, SNS topic subscription and SES configuration set. Engage also lets you send email broadcasts and create email automations. The SES permission is used for this.

Confirming proper setup

If for any reason you want to confirm your setup or peep under the hood, here is how:

  1. Go to SNS on your Amazon console. Click on Topics. You should see engage_so in the list of topics.
  2. Click on the engage_so topic. It should have an HTTPS subscription pointing to a URL similar to this https://us-central1-suet-170506.cloudfunctions.net/ses-webhook. The status should be confirmed.
  3. Go to SES on your Amazon console. Click on Configuration Sets. You should see engage_so in the list of configuration sets.
  4. Click on the engage_so configuration set. It should have the engage_so SNS topic as its destination and should have the event types Bounce, Click, Complaint, Delivery, Open, Reject.

Updating the configuration set

Do not do this unless you know what you are doing.

Now that we have established you understand what you are doing, you may need to update the configuration set for custom purposes; especially because you can only use one configuration set at a time when sending emails.

Edit Configuration Set

You can add additional destinations to the configuration set by clicking on the engage_so configuration set and selecting a new option for Add destination.

Other things you can do:

  1. You can add an IP pool by clicking the Sending IP pool tab
  2. You can update the tracked events, for example to disable open or click tracking. To do this, click on the edit (pencil icon) option on the configuration set page and uncheck the events you want to stop tracking. Engage doesn’t track Send, Rendering Failure and Rendering Success so don’t check those.
  3. You can also use a custom subdomain for your open and click tracking. This option is available on the same edit configuration set page above.

Telling Amazon SES to use the configuration set

Using the configuration set is not automatic. You need to tell Amazon to use it anytime you send an email. Depending on how you are sending your email and what library you use, you just need to add the SMTP header: X-SES-CONFIGURATION-SET: engage_so.

If you use Laravel PHP for example, here is a short post on how to do this: eoghanobrien.com/posts/laravel-smtp-ses-configuration-set.

If you use PHPMailer, it should be something like this

// ...
$mail = new PHPMailer(true);
try {
    $mail->isSMTP();
    // ...
    $mail->addCustomHeader('X-SES-CONFIGURATION-SET', 'engage_so');  // <-- this
    // ...
    $mail->Send();
} catch (Exception $e) {
    echo "Email not sent. {$mail->ErrorInfo}";
}

If you use SwiftMailer:

// ...
$mailer = new Swift_Mailer($transport);

$message = new Swift_Message('Wonderful Subject');
$headers = $message->getHeaders();
$headers->addTextHeader('X-SES-CONFIGURATION-SET', 'engage_so');  // <-- this
$message->setFrom(['john@doe.com' => 'John Doe'])
  ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
  ->setBody('Here is the message itself')
  ;

$result = $mailer->send($message);

In NodeMailer:

const transporter = nodemailer.createTransport(transportObject);

await transporter.sendMail({
  from: '"Fred Foo 👻" <foo@example.com>',
  to: "bar@example.com, baz@example.com",
  subject: "Hello ✔",
  text: "Hello world?",
  html: "<b>Hello world?</b>",
  headers: {
      'X-SES-CONFIGURATION-SET': 'engage_so'  // <-- this
  },
});

AWS NodeJs library

const ses = new AWS.SES({
  accessKeyId: process.env.ID,
  secretAccessKey: process.env.KEY,
  region: process.env.REGION
});
ses.sendEmail({
  Destination: {
    ToAddresses: ['yo@hey.com']
  },
  Message: {
    Body: {
    Html: {
      Charset: "UTF-8",
      Data: '<p>Yo. This is a test :)</p>'
    },
    Text: { Data: 'Yo. This is test :)' }
    },
    Subject: { Data: 'Hey' }
  },
  ConfigurationSetName: 'engage_so', // <-- this
  Source:  '"Heello" <hello@awesome.co>'
  }, (err, data) => {
  console.log(data, err);
  // ~
})

If you are sending your email via the sendRawEmail or SendEmail API, there is a ConfigurationSetName parameter you should set to engage_so.

Engage lets you see in realtime failures, complaints, delivery and engagement of transactional emails you send through Amazon SES. Sign up for free.