Understanding Amazon SES Configuration Sets and how Engage uses them

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
• What the requested access keys are used for
• Confirming proper setup
• Updating the configuration set
• Telling Amazon SES to use the configuration set

With Engage, you can use any of our supported Email Service Providers (ESP). We currently support Mailgun, Amazon SES, Sparkpost, and Sendgrid.

Get Started For Free

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 an 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 credential 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 automation. 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, and 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.

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(['[email protected]' => 'John Doe'])
  ->setTo(['[email protected]', '[email protected]' => '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 👻" <[email protected]>',
  to: "[email protected], [email protected]",
  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: ['[email protected]']
  },
  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" <[email protected]>'
  }, (err, data) => {
  console.log(data, err);
  // ~
})

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

Engage lets you see real-time failures, complaints, delivery, and engagement of transactional emails you send through Amazon SES.

Sign up for free.