Email Event Data with Keen

The SendGrid Event Webhook lets you stream all email events directly to Keen for nearly real-time analysis and long term storage.

It only takes a couple of minutes to start streaming email event data from SendGrid to Keen, and once you do, you’ll get tools to create flexible email analytics and stunning email marketing dashboards.

Prerequisites

Before continuing with this guide, you should first create SendGrid and Keen accounts if you do not have them already.

Get a destination URL from Keen

  1. Once you're logged into Keen, add a new project in the Keen application user interface (UI) by clicking New Project in the left sidebar.
  2. A new page will load where you can name your project. Add a name and click Add Project.
  3. Click Access in the left sidebar to load a page with your project's information.
  4. Copy the Project ID and Write Key values from this page.
  5. Once you have your Project ID and Write Key, you can construct a URL where SendGrid will deliver event data. That URL follows the pattern:

https://api.keen.io/3.0/projects/<YOUR_KEEN_PROJECT_ID>/email/sendgrid/1.0?api_key=<YOUR_KEEN_WRITE_KEY>

  1. Navigate to the SendGrid application to configure an Event Webhook.

Add or edit an Event Webhook

Whether starting with a new webhook or editing an existing one, you will set a Post URL, which is where you'll add your Keen URL.

Test your integration

SendGrid application

Once your webhook's Post URL is set by following the linked directions above, you will be able to click Test Your Integration in the SendGrid webhook dialog to send a test payload to Keen. The sample email data from SendGrid is an example and not data related to your actual email send.

Keen application

Once you send a test payload from SendGrid, navigate to the Keen application to see the sample data.

  1. In the Keen application, navigate to the Keen project you created earlier.
  2. Click Streams in the left sidebar menu.
  3. In the box labeled Event Streams, you will see events such as email_bounce and email_click. You can click on any of these events to display the event data in JSON format. See the "Data Models" section of this page for more information about how event data is represented in Keen.
  4. After you've confirmed the data was sent, enable the Event Webhook in the SendGrid application and your email data will be sent to Keen.

Data Models

Each email event type that is selected will be recorded as a separate Event Collection in your Keen project. We recommend sending all event types from SendGrid to Keen to access the full functionality of Keen’s reporting.

The email events that are recorded in Keen are:

  • email_bounce
  • email_click
  • email_deferred
  • email_delivered
  • email_dropped
  • email_group_resubscribe
  • email_group_unsubscribe
  • email_open
  • email_processed
  • email_spamreport
  • email_unsubscribe

As SendGrid email data streams to Keen, it will be enhanced using Keen's Data Enrichment capabilities. Keen’s data enrichment turn IP addresses into geographic locations and break out timestamps, URLs, and user agent strings into more easy-to-use data such as device_type, day_of_the_week, and URL path.

Use the property message_id or singlesend_name contained in each event to track a particular email across all of these possible actions. Similarly, you can follow a particular user's behavior via the email property.

Work with Keen and SendGrid event data

With Keen, you will have access to all of your raw data for as long as you need it. An archive of all of your email data is created, which means you will have access to your historical data and can query for past user behavior.

Just like SendGrid, Keen is 100 percent powered by APIs. This means you can embed rich analytics anywhere you can write code.

The following resources provide more information about working with your data once it's in the Keen platform. See the "Additional Resources" section of this page for more SendGrid and Keen documentation.

Additional Resources

Rate this page:

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif