Using SendGrid templates with Node.js

For a while now at Mish Guru we had been using Mandrill to handle transactional emails, things like password resets. But unfortunately as Mandrill has recently decided to change their pricing plans, this was no longer a cost effective option for what we were trying to achieve.

We decided to give SendGrid a try as it seemed to have all the features we wanted like templates, no cost at low volumes and a node wrapper over the API to help get us going.

This all seemed great until I got started and realised that SendGrid has horrible documentation on how to use their Node package, especially when it came to using their template engine.

Screen Shot 2016-05-26 at 2.43.24 PM
This is the entire section on templating in the docs for the node package


After giving the appropriate feedback on the SendGrid docs page



I decided to make this quick guide to share what I’ve learnt about getting templates going with Node. This tutorial will quickly cover how you can setup a template in SendGrid, and start sending your users customised emails.

Setting up a template

After you’ve created your SendGrid account, you’ll need to create a template on their dashboard. Once you’ve created a new template you should be on the template editor which looks like this

Screen Shot 2016-05-26 at 2.50.19 PM

Now you can start formatting and adding elements to your template by turning the drag and drop editor on on the left hand control panel, and then going to the build tab to start adding elements to your template

Required tags

For some reason or another the <%body%> tag is mandatory, even though in this example we aren’t going to use it. It has to be in your template somewhere, and you have to provide some kind of body when you send your email via Node.

Similarly when you’re sending your email from Node, you have to provide a <%subject%> variable, even if you’ve hardcoded the subject of your email into the template.

Variable substitution

There is very little documentation on how variable substitution works on SendGrid’s Node docs, however with a bit of digging through their API docs and trial and error I managed to get variables substituting in the format of %my_substituted_var%.

It seems user given variables don’t work when you have the angle brackets <% ... %> around them, these are reserved for the <%body%> and <%subject%> tags.

So now you can make your template that might look something like this

Screen Shot 2016-05-26 at 3.17.40 PM
Example template in SendGrid. Note the required <%body%> tag.

Note at the bottom of the template I’ve inserted the <%body%> tag, even though the template I’ve created has all of the information that is required for this email. This just seems to be a quirk of SendGrid and you’ll get an error if you don’t include it.

Button URLs

In an email like the one in our password reset example, you’ll most likely want to have the URL of the button set to a custom URL which is unique for each email. You can do this by clicking on the button, then set the button URL to a template variable in the button properties section on the left hand side of the template editor.

Screen Shot 2016-05-26 at 3.22.01 PM
This is the entire section on templating in the docs for the node package

Sending an email from Node

After your template is looking good, head over to the API keys section on the SendGrid site and create a new API key that has permission to send mail and read templates. You’ll also need to get the ID of the template you want to use, which is available from the template page on the SendGrid dashboard.

Then after a quick npm install sendgrid --save in your project you can start sending emails right away! Heres an example of how you would fire off the template we created earlier in this example


Note a few things here.

  1. The body of the email must be set using the html parameter in the email constructor. It failed when I gave it as an empty string. For this example I set it to an empty paragraph tag which was at the bottom of the template so it renders out as nothing
  2. The subject must also be given, even if you’ve hard coded it into the template, otherwise you’ll get an error.
  3. When setting the substitutions you have to add the % delimiters or it won’t work
  4. The syntax for specifying your template is a bit strange. You have to set it as a filter and enable it. If you copy paste how it’s done here it should work.


SendGrid provide a way to send templated emails like you would in Mandrill, but getting everything going is nowhere near as straight forward as it should be.

Happy coding!