Amazon Web Services (AWS) has a ton of features for almost anything a developer wants to do. AWS has one for sending emails called Simple Email Service SES. AWS SES can be used to send a text-based and template-based email.

In this post, I want to talk about one particular caveat by sending a template-based email using AWS SES. It is what Amazon says "Rendering-Failure", which happens when variables in the template don't match with provided template data. Let's see what that statement means.

Let's say we have the following template (Template name: WelcomeEmail) that we want to use.

<div>
  <h1>Welcome {full_name}!</h1>
  <p>{message}</p>
</div>

If we were to provide data for this template, it would look something like this.

const templateData = {full_name: "Nabin Adhikari", message: "Australia is burning"}

We can use the following Javascript code from lambda to send this email and hopefully you'd receive it.

await this.ses.sendTemplatedEmail({
  Destination: { ToAddresses: ["you@example.com"], },
  Source: "me@example.com",
  Template: "WelcomeEmail",
  TemplateData: JSON.stringify(templateData)
}).promise();

For more information on how to send templated-based email using AWS SES, please read this - https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-personalized-email-api.html.

The Problem

Now is the time to talk about the caveat SES has. See how template and template data have the same number variables and exactly the same variables in the example above? That is why you would probably receive the email. However, what do you think will happen if you miss any variables or added new variables unknown to the template? You might have already guessed. Yes, the email might not be sent. Now you say, yes we can catch the error and will process it later. But here is the caveat, SES would say it succeed. It is frustrating to ensure all of these data match with the template when you have many email templates and SES API saying success.

Yes Nabin, that sucks, what can be done about this? Well, in the link I have attached for SES email above, it also talks about the solution. If you don't want to feel abandoned after you have done everything the article says and still no success, please continue with this post.

The Solution

The inconsistencies between template variables and template data is called "Rendering-Failure" by AWS, which can be notified through AWS Simple Notification Service (SNS). Let's go through this to get notified if any of "Rendering-Failure" occurs while sending the template-based email.

The first thing we need for this is an SNS topic and subscribe to it. Let's create a topic first. Go to Amazon SNS dashboard and to Topics from the left side menu. Click a button to create a new topic and give it a meaningful name. I will name it ses-failure. Next, we need to subscribe to it. For this, go to the Subscriptions tab in newly created topic details and click on the button labeled "Create Subscription" to starting creating a subscription. You need to choose a protocol that is suitable for you, email is fine for me. If you also choose email, enter your email address as Endpoint and hit the "Create Subscription" button. You have to confirm the subscription by clicking on a link sent to your email address. Now, we should have a topic and a subscription as in the image below.

Next, we need to create a configuration set in AWS SES. First, go to the SES dashboard and click Configuration Sets from the left side menu. You should see a big button to create a new configuration set. Click on it and give it a meaningful name and click the Create Configuration Set button. I'll name it rendering-failure-cs.

Next, you need to edit that configuration to add a destination. You should see a Select a Destination Type dropdown, click on it and choose SNS. This would open a dialogue with form as below.

You need to leave Enabled enabled, give a meaningful name, check Rendering Failure from Event types options, choose the SNS topic name you created earlier (mine was ses-failure), and submit. You should see it as below.

This is all we need to do as per AWS documentation. However, there is one final step to do for all of these steps to work.

The Final Step

The final step is to add the created configuration set name while sending an email. My configuration set name is rendering-failure-cs, you should remember yours. Do not confuse this name with Added SNS Event destination name, because I did. Add ConfigurationSetName: "rendering-failure-cs" parameter while sending email as shown in screenshot below.

Now if you miss any variable data or added extra unintentionally, you'd receive an email with missing or extra variable or the reason behind rendering failure.

Finally

AWS has great resources and tons of services, but every now and then I got stuck in between because of incomplete documentation if not missing documentation. I had spent quite a bit of time to make this thing working and I wanted to share with you so that you don't have to. Thank you for reading this far. I would really appreciate if you provide any feedback or suggestions.

Cover Image from Unsplash. https://unsplash.com/photos/gClIPKFrRjE