Twilio SendGrid and MuleSoft Integration

Author: Dipesh Mestry

Agenda of this blog is to cover the below points:

1. What is Twilio SendGrid ?

2. How to design a simple Email template in Twilio SendGrid.

3. Twilio SendGrid Email API.

4. How to send Email from MuleSoft using a previously designed template in SendGrid?

1. What is Twilio SendGrid ?

SendGrid is a cloud-based SMTP provider that allows you to send email without having to maintain email servers. SendGrid manages all of the technical details, from scaling the infrastructure to ISP outreach and reputation monitoring to whitelist services and real time analytics.

Twilio, the leading cloud communications platform, acquired SendGrid on 30th Jan 2019.

After this acquisition, now Twilio can provide the following benefits to their customers:

    a.  Access to the single, best-in-class platform to manage all important communication channels: voice, messaging, video and now, email.

    b. The ability to deliver consistent and personalized messaging based on the customer’s preferred form of communication.

2. How to design a simple Email template in Twilio SendGrid?

2.1  Visit https://sendgrid.com/ and sign up for a free account.

2.2  Once the registration is successfully completed, login to SendGrid account and you will be presented with the dashboard below. From the menu which is on the left hand side, click on EMAIL API → Dynamic Templates. This is the place where you can design dynamic templates for your email.

2.3 After this, you will be able to see the screen below where you can design the new dynamic templates by clicking on the “Create a Dynamic Template” option.

Also, if the templates are already present, then you can browse through existing templates and do the modifications.

2.4  Once you click on the option to create a new dynamic template, it will ask for the name of the template. Give the name as “Sample-Email-Template” and hit the create button. 

Post that now you can see your newly created template in the template section. Expand it and see its properties.

• Template ID– Each template has a unique template id using which you can refer to the template.
• Version– Every template has one or more versions that you can add into it and only one version can be active at a time using that emails will be sent when you refer to the template using its template id.

Now click on “Add Version” to add a new template version and create the body of the email template. From the screen, select the option of “Blank Template” then it will prompt you to the below screen. 

2.5 After this, you can see the “Design Section” which has below components:

• Settings section- This is a place where you can define “Version Name ” and “Subject” to your email template. For my example, “Version Name ” is “1.0”  and “Subject” is “Sample Test Email Template”.
• Area on the right hand side is the place where you can design your email body using different modules from the “Build” section. 

2.6  Drag and drop the “Text” Module from “Build” Section to the design email body and paste below text in it.

Hi {{ReceiverName}},

This is a sample email to demonstrate SendGrid Capabilities.

Thanks,
{{SenderName}}

Above text is your email body content which will be sent to the recipient once you refer “Sample-Email-Template” to send an email. Above email body has some text enclosed within “{{}}”. Whatever we enclose in text within “{{}}”, it becomes placeholder text and it can be leveraged as dynamic content i.e. value of these placeholders can be populated dynamically while sending email via SendGrid Email API which we will see in further sections. 

2.6  Using the “Preview” section, you can see the Desktop and Mobile preview of the email.

2.7  Click on the “Save” button to save the template.

2.8  Furthermore, we will explore how to refer to this newly created template using SendGrid Email API. 

3. Twilio SendGrid Email API

Twilio SendGrid provides below APIs to integrate its services with your application and send Email:

• Web API- The fastest, most flexible way to send email using languages like Node.js, Ruby, C#, and more.

• SMTP Relay- The easiest way to send email. It only requires modifying your application’s SMTP configuration.

3.1  For the demo, let’s look into Web API. Documentation for the same can be found at https://app.sendgrid.com/guide/integrate/langs.

3.2 To use SendGrid Rest API in the application, below 2 steps are mandatory.

• SendGrid account should have at least one authenticated sender using which we will be sending the mails from SendGrid account.
• API Key must be generated for the sender with restricted access. This API Key should be used while invoking REST API to send the mail from your application. 

3.2.1 In order to authenticate the send, Go to SendGrid Account and from menu go to “Settings” → “Sender Authentication” and select the option of “Verify a Single Sender” from “Single Sender Verification” section. It will ask you the details of “Sender Email address”. Please provide the sender as your email address and verify the same.

3.2.2  Once the sender is authenticated, you can generate the API key for the sender by clicking on the “Create API Key” option available under “Settings” → “API Keys”.

3.2.3  It will prompt the below screen to give “API Key Name” and “API Key Permissions”. Give any name to the key for example “mule-app-key” and from “Api Key Permissions” select “Restricted Access” option and give ”Full Access” for “Mail Send” option as shown in the screen below. 

Hit the “Create & View” button. It will show the API key. Kindly make sure that you save it somewhere because it will show you the API key only once due to security reasons.

From the above step, we are making sure that our API key has access to only send an email using SendGrid Email API.

We will be using this API key to send an email from our Mule application using SendGrid Email API.

3.3  Twilio SendGrid Email REST API Overview –  Before we invoke the REST API from Mule application. Let’s see the API endpoint details and sample request –

Pre-requisite to invoke the REST API:

1. Valid email address of a sender which is already authenticated with SendGrid Account.
2. API Key for the sender.
3. Template ID of an Email Template defined in your SendGrid Account.

Endpoint Details are as follows:

Sample Request JSON:

{
  "template_id": "<<Template ID of your Dynamic Template>>",
  "from": {
    "email": "<<Sender’s Email ID>>"
  },
  "personalizations": [
    {
      "to": [
        {
          "email": "<<Receiver’s Email ID>>"
        }
      ],
      "dynamic_template_data": {
        "SenderName": "Bruce Wayne",
        "ReceiverName": "Dipesh Mestry"
      }
    }
  ]
}

4. Invoke SendGrid API from Mule Application

4.1  Once we have all the prerequisites in place, we can create a sample Mule application.

Which will take “SenderName” and “ReceiverName” as input and invoke the SendGrid API for “Sample-Email-Template” using its template_id. 

App flow is as follows:

1. Http listener- Simple http listener which accepts application/json as input and listening on port “8081” and path as “/mail”.

2. Log input- To log the input payload.

3. Transform message- This will pick the “senderName” and “receiverName” from input payload and transform it to json request required to send to SendGrid Email API.

%dw 2.0
output application/json
---
{
  template_id: "<<Template ID of Dynamic Email Template>>",
  from: {
    email:  <<Sender’s Email ID>>
  },
  personalizations: [
    {
      "to": [
        {
          email: <<Receiver’s Email ID>> 
        }
      ],
      dynamic_template_data: {
        SenderName: payload.senderName,
        ReceiverName: payload.receiverName
      }
    }
  ]
}

Replace the <<Sender’s Email ID>> and <<Receiver’s Email ID>> with your sender and receiver details. Also <<Template ID of Dynamic Email Template>> with template id of your email template defined in section 2.6.

4. Invoke Sendgrid Email API- http request palette to configure the REST API of SendGrid as follows –

Http Request Global Element Configuration-

Palette Configuration- 

Also, add “Authorization” header in the request with value as “Bearer <<your api key>>”.

5. Transform Message- This is to send a sample successful response to the API call to the sample Mule application. 

%dw 2.0
output application/json
---
{
	message : "Email Sent Successfully"
}

4.2  Deploy the Mule application using Anypoint Studio and invoke the API exposed by the app using any REST client like “POSTMAN”. This sample app is listening on url “http://localhost:8081/mail”. Once you hit the app url and all the correct configuration is in place then you should get a sample success response from the app and Email should be sent to the receiver’s email id configured in your Mule app. 

In this demo, I have used my personal email address as sender and my apisero email id receiver. So email should be sent to my spider email address as per email template that we defined earlier in this blog (Section 2.6) since we are using its template id.

Conclusion

Twilio SendGrid is a powerful cloud application which allows you to manage and send emails on your behalf. Here your application is not responsible for managing the email templates and its configuration, it will be taken care by Twilio SendGrid. Application can just invoke its API to send the email as per your configuration in SendGrid. 
Please refer to https://sendgrid.com/docs/ to get in depth information about the SendGrid and its APIs.