July 13, 2020

Understanding Amazon SES Configuration Sets and how Mailintel uses them

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

How Mailintel uses configuration sets

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

Here is the breakdown of the process in 4 steps.

  1. Mailintel creates a SNS Topic. This is named mailintel for easy identification.
  2. A subscription to the topic is created. The subscription points the topic to a webhook that handles messages to the SNS topic.
  3. Mailintel creates the configuration set. This is also named mailintel
  4. Mailintel creates the configuration set 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.

If you get an error when adding your domain, it’s most likely an issue with the access keys. Ensure they have full SNS and SES permissions.

What the access keys are used for?

The SNS and SES permissions are used to created and manage the SNS topic, SNS topic subscription and SES configuration set. Mailintel also allows sending quick mails to users directly from the dashboard. The SES permission is used for this.

Confirming proper setup

Here is how to confirm everything has been properly set up.

  1. Go to SNS on your Amazon console. Click on Topics. You should see mailintel in the list of topics.
  2. Click on the mailintel 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 mailintel in the list of configuration sets.
  4. Click on the mailintel configuration set. It should have the mailintel 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’ve 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.

Update configuration set
  1. You can add additional destination to the configuration set by clicking on the mailintel configuration set and selecting a new option for Add destination
  2. You can add an IP pool by clicking the Sending IP pool tab
  3. 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. Mailintel doesn’t track Send, Rendering Failure and Rendering Success so don’t check those.
  4. 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. We need to tell Amazon to use it anytime we 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: mailintel.

If you use PHP Laravel 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', 'mailintel');  // <-- 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', 'mailintel');  // <-- 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': 'mailintel'  // <-- 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: 'mailintel', // <-- this
  Source:  '"Mailintel" <hello@mailintel.io>'
  }, (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 mailintel.

Follow the conversation: @mailintel · RSS