SP_UseCases_ThumbnailThis past week, SparkPost released its long-anticipated enhancement to our API: individual recipient-level Message Events. While it has been possible to get individual recipient-level data via webhooks since we launched back in April, this feature provides users with an additional mechanism to get message events data. This new API endpoint provides our customers a way to pull data – on demand – for use in internal reporting, triggering message generation, or other programmatic processing of event data.

Some highlights:

* You can get all events or specific events, such as bounces, deliveries, or clicks

* You can filter the data by date range, subject line, campaign, or just about any other field

* Message events data is available for 10 days. Of course, rolled up data is available via our metrics endpoints or the UI reports for much longer.

So what kinds of can you do with the message events?

For transactional messages:

Let’s look at a customer service example. A customer calls your support line because they didn’t receive an important notification, such as an alert or a receipt or a password reset. You can build a simple UI that allows your customer service rep to search for an individual recipient to determine if he received the message. The API call would look something like this:

curl -XGET -H ‘Authorization: <API_KEY_HERE>’ https://api.sparkpost.com/api/v1/message-events?recipients=john.doe@yourcompany.com

If the recipient received the message — and maybe even opened it, the customer service rep can provide a time/date to help them find it. Inboxes are pretty full these days — it’s easy to lose messages.

For marketing messages:

Use the data to build a customer profile database — who’s engaged (opened / clicked within 90 days), who isn’t, and use that to drive additional messaging. You could further break it down by campaign — are certain users more responsive to certain campaigns than others? This is the foundation for segmentation analysis. 

Here’s a sample call to get opened or clicked within a specific day in the Central Time Zone (because, why not?)

curl -XGET -H ‘Authorization: <your key> https://api.sparkpost.com/api/v1/message-events?events=open,click&from=2015-09-02T00:00&to=2015-09-02T23:59&timezone=America/Chicago.

Take it even further and tie it to existing data you already have about the recipient, such as purchase history or website data, for a richer profile. 

How will you use message events? Tell us in the comments.

-By Irina Doliov, Cloud Queen
Follow on Twitter: @idoliov

New API Feature_Message EventsWe just released a new feature in our API: Message Events, which allows users to pull down recipient-level data. There has been a lot of demand for such an API, and I’m very proud to say implementing this was not as hard as you may think. Why? Because SparkPost is built using a microservice architecture and we are continually building additional microservices.  All of the event data is written to a message queue, and we create Node.js ETL processes that interface with a specific queue and implement specific business logic.  The advantage of this is we can reuse our event stream data for many different services: Metrics, Message Events, Event Webhooks, and Suppression Lists.

It was also very exciting to use a relatively new feature in Vertica called Flex Tables.  Think of it as MongoDB, but an enterprise quality version.  It did have to be tuned to support such high throughput, but since we had previous knowledge of Vertica for the Metrics API, it was straightforward and attainable in a few days. 

Also, we have built our first API that supports pagination. We are leveraging HATEOS (Hypertext As The Engine Of Application State) to build this feature. The intention is you can build applications that can chain REST calls. In the case of pagination, by default we return the most recent 1000 results in a given page. You can use the query parameter per_page to change this to a maximum of 10,000.  The data that is returned from the API will give you the results as well as total_count and links:

It allows you to programatically page through results by using the rel of first, previous, next, last. As you make subsequent requests the links returned in the response payload will dynamically change:

The primary use case is you can build a Web UI that can support dynamic paging, keeping the hard part of tracking number of pages/results out of your application and simply show/hide elements based on what is returned in the response payload.  At SparkPost we will leverage this in the future by building out our own Web UI.

One internal debate we had was the best query parameters to use: per_page/page and limit/offset.  Sure, limit/offset is the implementation behind the scenes but we wanted to provide a better user experience by translating limit/offset to more human readable/consumable names.

With the addition of Message Events to our API, we’ve added the power of searching for message event data based on recipients, campaigns, and more. Take a look at the documentation and as always, let us know what you think at developers@sparkpost.com

Learn more about microservices, Node.js,  ETL and HATEOAS here:





-Bob Evans, Manager, Application Engineering