SendGrid Mailer

This week I’m going to pick up where I left off with my project. Before I dive into Docker to generate the seed data I wanted to test out an emailer provider, something like MailChimp. Most websites today have an emailing service through which they can send out mass messages for advertising, notifications, confirmations, etc. So in this post, I’m going to go over my experience with working with the SendGrid API. Let’s get started.

API configuration/API keys

So, as always — the first step is going to be the API configuration. I decided to use SendGrid over other mailer providers for similar reasons I chose to use the Stripe API for payment gateway (Okay, maybe not similar — more like the exact same reason-they have free trial accounts). Let me start by saying I didn’t exactly find this to be the easiest configuration and am eager to experiment with other options. When I first began to make use of external APIs the process was always grueling and took forever! (*one time it took me an entire day to integrate the National Parks Services API 😂 )

However, I have now gone through the process of API integration for this project enough times that it’s no longer emotionally taxing and that sense of eternal loneliness and despair has all but dissipated.

The first step is to create an account, which is fast and easy. Once you have successfully created an account you must verify a Sender.

For this project, I chose Single Sender Verification. It was the quickest to set up and I can always Authenticate my domain at a later time. When you click “Verify a Single Sender”, a modal will appear with a form. I used a testing email address of my own (*SendGrid discourages the use of Gmail accounts, but they do indeed work). After you complete and submit the form you will receive an email from SendGrid at the specified address. Once you go through the verification process you have successfully verified a Sender.

The next step will be to integrate using the Web API. You will be directed to a page to select your language, I am using Node.js and selected accordingly.

At this point, I installed the npm module for the web API by running the following command:

npm install --save sendgrid @sendgrid/mail

Environment Variables

SendGrid provides their own process for testing the integration-which I used as a reference, but since I have already configured my environment variables I made a small adjustment in setting up the API key.

In my config directory, I added the API key generated by SendGrid to both dev.js and prod.js. The final step was adding this key to my Heroku environment variables and that was it.

So in my process, I did NOT follow steps 3–5 but have added them here for clarity.

Route Handlers

Looking through the source code for SendGrid was extremely helpful. I made use of a few helper functions provided by SendGrid. The functions I used from SendGrid were helper functions to properly format the request and for click tracking so that SendGrid knows to update my account’s statistics. I created my own Mailer class that will handle a lot of the formatting my application requires as well as create the Mail object that SendGrid requires.

While SendGrid offers a lot of the functionality above, it won’t be useful for my application on the backend. So by creating my own classes I am able to execute both requests with the same data.

Models

The models were the most challenging part of this process. Deciding which properties and methods to use from SendGrid, and which to customize took a lot of digging through the source code.

My first step was to create my custom Mailer class which extends the SendGrid’s Mail class. In order to maintain control over my application, I decided to create my own classes for emails as well as recipients (if this is not desirable — SendGrid does have many functions that provide similar services.

source code for SendGrid’s addContent()

helper functions for custom Mailer class.

SendGrid’s addPersonalization() — this is responsible for managing unique data to specific email addresses when sending a single email to multiple addresses

SendGrid’s addTo() — this is used to add each recipient’s email address to their own Personalization object.

SendGrid’s setTrackingSettings() — this tracks user interaction. These statistics are available to the client on the SendGrid dashboard.

The final API request made to SendGrid’s API.

The final API request has a couple of steps. Defining the variable request set to an ‘emptyRequest’ object (generated by SendGrid) by passing along the method, path, and body — toJSON() is another function provided by SendGrid, the source code for this is pretty long but can be found here. The API method will return a response — which I set to a local variable ‘response’.

API Testing

To test my Frankenstein request I realized that I can’t user a RESTclient to do so because of the authentication required. So I decided to use axios attached to the window object. By creating a survey object in the console, and calling axios.post() to my ‘/api/surveys’ path and passing in my temporary survey object. I checked my Gmail account eagerly and was relieved to see that it worked!

There is a lot more to be done in order to manage and store the necessary data in my database but getting this far was a lot of work and I am happy to share my experience.

I would say the takeaway lesson here is to not fear source code! Documentation is fantastic, but sometimes it may be more helpful to look at the actual code.

My successful test email #schittscreek