Debugging AWS SES templates

Debugging AWS SES templates

I consider working with email templates a frustrating task and especially if you can’t debug the issues during implementation. In this post, I’ll share how I deal with implementing email templates based on the Amazon SES service.

The workflow

workflow Email template generartion flow

The first part is to prepare an MJML template, if you don’t know about this framework, I highly recommend reading about it from the official site. It helps a lot when it comes to the template boilerplate. At this stage, the template should include the Handlebars tags for the custom variables.

The second part is about generating an HTML content from the MJML template, which can be easily done with the live editor.

Finally, the last part where the HTML content is stringified to be uploaded to AWS email templates. If you feel lazy here is an online tool for that.

what is the issue?

The main issue that I face during development is the Rendering Failure:

When you use an email template, Amazon SES validates that the template data you send includes the variables that are required in the template. If the template data contains non-compliant variables or is missing variables, then Amazon SES can’t deliver the email. This is called a Rendering Failure.

from AWS docs

If you follow the link from the quote, you will see that the first suggested solution is to set up Rendering Failure event notifications. In a perfect world, that is the optimal solution to debug the missing or the issues with some custom variables. But in reality, we face the following issues:

  • No access to that specific AWS environment
  • Missing permissions to manage some services like SNS
  • Long waiting time to get someone from the infrastructure to handle the setup
  • You need to deliver the changes ASAP! 🔥

So how do I handle this?

The template is based on Handlebards syntax and I use this online editor as it fits all my needs tryhandlebarsjs. If you check the workflow, I use the HTML content from the second step in the section marked as “Handlebars Template” and the data in the “Context” box. We don’t need the Register Helper section, as AWS doesn’t support that (it can make life easier in some cases). Hitting the compile button will usually do the trick, I can manage to see if there is a syntax issue or a variable is not visible from the output. Another helpful tip, if you know that some fields can be missing as they are optional in your models, you can use the conditional output in the template, using a syntax like this:

  {{#if myVar}} {{myVar}} {{/if}}

That if condition is simple but it will save you a lot of headaches in the long term when it comes to dealing with this kind of templates.

I hope that you find this helpful when debugging AWS SES templates.