Mailgun, Node.js, and Google Sheets: Tracking Email Deliverability

The ability and reliability of communications is an extremely vital part of running any type of subscription business. For many, if not all, SaaS (software as a service) businesses, the primary channel of communication with customers is email. So, ensuring that customers actually receive these communications is a top priority; whether the content of the communication is a newsletter, announcement, password reset or billing information.

At Jungle Disk, we use Mailgun to send these “transactional” email communications and to track the deliverability of the email we send. Mailgun is a superb email service, but has limitations on the length of time that logs and event information is available, 30 days to be exact. So, in order to track our deliverability over time, we make use of Mailgun’s API to record historical data about the emails we send. This allows us to have a longer term view on the performance of our communications over the statistics that Mailgun already provides.

Tracking Email Events with Mailgun

There are several specific email events that we track:
* Delivered - This event is logged when an email is successfully accepted by the recipient’s mail server.
* Failed - This event is logged when an email cannot be delivered to the intended recipient, this can be a temporary or permanent failure.
* Unsubscribes - This event is logged when a recipient clicks the unsubscribe link in an email.
* Complaints - This event is logged when a recipient uses their email client or email provider to report an email as spam.

Using Node.js and Google Sheets to Track Deliverability Over Time

So, to get a deeper look at the deliverability of our email communications, I wrote up a fairly simple script that queries the Mailgun API for all email events for the billing-related emails that we send to customers and writes out the results to a Google Sheet. This script is run every morning.

This guide assumes some knowledge of Javascript, Node.js, and NPM. We’ll walk through the script piece by piece and I’ll expand on the purpose and functionality of each section.

In this block, we’re including external libraries to expand the functionality of our script. The top section is included to authenticate with Google and utilize the Google Sheets API, which allows us to programmatically write our data to a Google Sheet. Lastly, we include Mailgun’s official API client for Node.js and Underscore, an extremely useful library that extends the Javascript language and makes it much easier to work with objects and arrays.

Next, we define some additional constants for the script, and set up a query object that will be used to narrow the results we get from Mailgun. Our example is pretty basic, but could become quite granular if needed.

// This is only called if the OAuth tokens are expired or non-existent
function getAndStoreTokens(oauthclient) {
var authUrl = oauth2Client.generateAuthUrl({access_type: 'offline', scope: 'https://www.googleapis.com/auth/spreadsheets'});
// print URL to the screen
console.log(authUrl);

Below is the bulk of the work this script will do. We’re passing the raw data returned from Mailgun to this function in order to break out metrics/stats for the whole 30-day period and for the current date. Finally, we pass these off to another function that will write the data to a Google sheet.