SendGrid is an all-in-one digital marketing platform to enable B2B and B2C businesses, e-commerce sellers, and agencies to build customer relationships through end-to-end digital marketing campaigns and transactional messaging.
The SendGrid transactional email platform has an API that supports dynamic HTML content to deliver custom messages to clients or end-users as can be seen in their documentation here. In this tutorial, you will integrate your Ubidots account’s events via webhooks to forward a custom email alert to your clients.
Requirements
1. Create an email template with dynamic content
Log in to your SendGrids account, go to the upper left menu bar, click on “Email API”, select “Dynamic Templates”, and then click on “Create Dynamic Template”.
Give a name to your template and then click on “Create”, and click on “Add version” to start editing the content of your template. Here we will choose a “Blank Template”, select “Design Editor” for visual, drag and drop editing with access to modify HTML.
2. Edit the template to include your custom content
The editor menu is divided in two main parts, “Settings” and “Building”.
In "Settings" assign a custom name to this version of your template, you can also set up a “Subject” and a “Preheader”, which is content that follows the subject on the email that will be sent to your clients. “Build” will allow you to add visual components to your template from a drag-and-drop palette that includes modules such as images, code, buttons, etc.
Here, we will add—in order from top to bottom—an image followed by a code module which will have inside an HTML table to display your event’s data dynamically by making use of the handlebars syntax, also known as "Mustache". For more information on how this syntax works, check SendGrid's documentation here.
In a nutshell, the handle or mustache values will be indicated on the API request, the key would be their name and the value would be the event's data—in this case, your Ubidots device name, variable name, the value that triggered the alert, and the timestamp of the event.
Here's the structure of our template:
Image component: There you can upload an image from your computer. Keep in mind that the image uploaded can be modified, in case you need to resize your image you can modify its width property as follows.
Code component: Copy and paste the following HTML code:
<style>
h2{
font-family: arial, sans-serif
}
table {
font-family: arial, sans-serif;
border-collapse: collapse;
width: 100%;
}
td, th {
border: 1px solid #dddddd;
text-align: left;
padding: 8px;
}
</style>
<h2>Sensor Data</h2>
<table>
<tr>
<th>Device Name</th>
<th>Variable</th>
<th>Last Value</th>
<th>Timestamp</th>
</tr>
<tr>
<td>{{devicename}}</td>
<td>{{variable}}</td>
<td>{{value}}</td>
<td>{{date}}</td>
</tr>
</table>
The template will look as follows:
3. Integrate an event via webhooks to the SendGrid’s API
Here we will focus on the configuration needed to send a POST request to the transactional email API endpoint in order to send an email to a client. To do this, you'll need your SendGrid account's API Key and the template ID of the template already created. If you need to learn how to create a webhook in detail, refer to this tutorial.
To create a new API key or modify your existing one, go to the left panel in your SendGrid account, select “Settings”, and click on “API Keys”.
The template ID can be obtained by going to “Templates” as follows:
In your Ubidots event’s action section you must select the HTTP POST method, the SendGrid’s URL, and the headers as follows:
HTTP method: POST
URL: https://api.sendgrid.com/v3/mail/send
Headers:
Content-Type | application/json |
Authorization | Bearer <<Your sendgrids API Key>> |
Body:
{
"from":{
"email":"support@youriotcompany.com"
},
"personalizations":[
{
"to":[
{
"email":"yourcustomers@email.com"
}
],
"dynamic_template_data":{
"subject":"<variable> alert!",
"devicename":"<deviceName>",
"variable":"<variable>",
"value":"<value>",
"date":"<timestamp>"
}
}
],
"template_id":"<your template's id>"
}
Heres how the configuration looks while setting up the webhook on the events module:
The following video will help you understand how to enter the event’s dynamic content in the body, as the value for the keys that we already set in our template.
4. Test your event and verify the results
In this example, I had a Humidity sensor connected to an ESP32 board and I set the event based on this condition.
Once the event was triggered your client will receive an email like this one: