How To Use Mixpanel To Track SendGrid Email Delivery

Patricio Robles
Feb. 20 2014, 10:51AM EST

Email is one of the oldest mediums of communication on the Internet, and, for many companies, it's still one of the most important. Delivering email and tracking email campaigns reliably is crucial to success for countless businesses today.

In this tutorial, we'll look at how APIs from SendGrid and Mixpanel can be used together to track email delivery events on a very granular level without building a complex analytics application or even writing much code at all.

SendGrid is a popular cloud-based email delivery platform. Using SendGrid's SMTP and HTTP APIs, companies can send email to their customers and subscribers while alleviating some of the challenges frequently encountered with email delivery.

Mixpanel is a next-generation analytics platform. Using Mixpanel's API, it is possible to track any number of arbitrary events and associate them with them the people who generated them, allowing for the creation of powerful custom analytics programs.

Combining SendGrid and Mixpanel

SendGrid's platform provides some analytics data, but it's not an analytics platform in and of itself. For organizations that want detailed analytics on a per-email recipient basis, SendGrid offers an Events Webhook API that delivers raw data about email delivery events to a customer-created and hosted script.

However, taking raw data and turning it into meaningful insight can be a daunting task that requires significant development. Fortunately, organizations don't have to reinvent the wheel. They can simply send the data delivered by SendGrid's Events Webhook API to a Mixpanel account using Mixpanel's API. This provides the ability to track and visualize email delivery events on a per-email recipient basis with minimal effort.

Getting started

To start, you will need:

  • SendGrid and Mixpanel accounts
  • A hosting account that, at a minimum, supports PHP 5.0 or greater and has the PHP curl module installed

In the root web directory of the hosting account, create an empty PHP file, events.php, and upload the directory containing the Mixpanel PHP library, which can be downloaded from Github.

The script

Into the empty events.php file, paste the following PHP code:

<?php

// Include the Mixpanel PHP library
require "mixpanel-php/Mixpanel.php";

// Instanstiate the Mixpanel class
$mp = new Mixpanel("YOUR_MIXPANEL_PROJECT_TOKEN");

// Grab the data that has been posted by Sendgrid
$data = trim(file_get_contents('php://input'));

// Make sure we have data
if (!empty($data)) {

  // Decode the JSON data
  if ($events = json_decode($data)) {

     // Loop through all of the events that have been posted
     foreach ($events as $event) {

        // Make sure the event is one we want to track
        if ($event->event == "processed" || $event->event == "delivered" || $event->event == "open" || $event->event == "click" || $event->event == "unsubscribe") {

           // Create a new Mixpanel profile for the recipient if necessary, using an MD5 hash of the user's email address as their ID
           $mp->people->set(md5($event->email), array(
              '$email' => $event->email
           ));

           // Identify the user so that events we track are associated with them
           $mp->identify(md5($event->email));

           // Finally, track the event
           $mp->track($event->event, $parameters);
        }
     }
  }
}

?>

This code parses the email delivery events posted to the script by SendGrid, ensures that the events are the ones the organization wants to track, and sends the events to Mixpanel. All email delivery events are associated with the recipient of the email so that they can be tracked down to the recipient level.

Be sure to replace YOUR_MIXPANEL_PROJECT_TOKEN with your actual token, which can be obtained through your Mixpanel account.

Once in place, you can configure SendGrid to post event data to your script by supplying SendGrid with the URL to your script. To test that everything is working, you can have SendGrid send test data to your script. Once SendGrid has sent the test data, your Mixpanel account should begin to populate.

Extending the script

While there is plenty of insight to be gleaned from tracking events and associating them with each individual recipient, some events the SendGrid notifies users about come with additional data that provide more context. This context is often very useful. Open Events, for example, include the recipient's user agent and IP address, and Click Events include the URL of the link that was clicked. In addition, if users associate one or more categories or custom parameters with the email, SendGrid will include those in the event notification.

To capture this data, the script can be extended:

<?php
// Include the Mixpanel PHP library
require "mixpanel-php/Mixpanel.php";

// Instanstiate the Mixpanel class
$mp = new Mixpanel("YOUR_MIXPANEL_PROJECT_TOKEN");

// Grab the data that has been posted by Sendgrid
$data = trim(file_get_contents('php://input'));

// Make sure we have data
if (!empty($data)) {

  // Decode the JSON data
  if ($events = json_decode($data)) {

    // Loop through all of the events that have been posted
    foreach ($events as $event) {

     // Make sure the event is one we want to track
     if ($event->event == "processed" || $event->event == "delivered" || $event->event == "open" || $event->event == "click" || $event->event == "unsubscribe") {
       $parameters = array();

       // Track parameters for different types of events
       switch ($event->event) {
         case "click":

            // Record the URL of the link that was clicked on
            $parameters["url"] = $event->url;
         default:
           //  Record the categories or category of the email, if present
           if (isset($event->category) && is_array($event->category)) {
             for ($i = 0, $size = count($event->category); $i < $size; ++$i) {
               $parameters["category_$i"] = $event->category[$i];
             }
           } elseif (isset($event->category)) {
             $parameters["category"] = $event->category;
           }
           //  Record the user agent, if present
           if (isset($event->useragent)) {
             $parameters["useragent"] = $event->useragent;
           }             

           // Create a new Mixpanel profile for the recipient if necessary, using an MD5 hash of the user's email address as their ID
           $mp->people->set(md5($event->email), array(
            '$email' => $event->email
           ));             

           // Identify the user so that events we track are associated with them
           $mp->identify(md5($event->email));             

           // Finally, track the event
           $mp->track($event->event, $parameters);
         }
       }
     }
  }
}  

?>

In this revision to the code, we added logic specific to Click Events that captures the URL of the link that was clicked. And for all events, we are now capturing any category or categories that were associated with the email, as well as the recipient's user agent, if present.

Visualizing the data

With the script in place and SendGrid configured to post event notifications to it, we now have everything in place to generate powerful email analytics. Importantly, email delivery events can be visualized in aggregate, allowing organizations to view trends.

We can also look at the properties associated with specific events, such as which URLs were associated with the links in the emails that recipients clicked on.

Finally, we can drill down to specific recipients. This allows organizations to keep tabs on their most important customers or to gain insight into the typical life cycle of subscribers.

Ideas for further development

There is even more potential when teaming SendGrid and Mixpanel. For example, if your company has a CRM database that contains customer demographic data such as gender, location and age, this data can be added to the customer's Mixpanel profile using the Mixpanel API, making it possible to generate reports based on customer segments.

In addition, as noted, Sendgrid's SMTP and HTTP APIs allow custom parameters to be associated with the emails that are sent, and these custom parameters are included in the SendGrid notifications posted to our script. Custom parameters can be used to identify emails, such as by campaign, providing the ability to track the performance of specific groups of emails by subscribers and subscriber segments.

Are you using SendGrid or Mixpanel? How might using them together benefit your organization? Let us know in the comments section.

Patricio Robles Follow me on Google+

Comments