SparkPost’s New Events Search Is Here

We’ve just released a new and improved Events Search feature for all SparkPost customers. When you log into SparkPost, you’ll see it highlighted in the navigation menu, under “Reports.”

Events Search’s robust searching capabilities provide ready access to the raw event data associated with the messages you send via SparkPost. In addition to the Events Search capabilities in the SparkPost web app, the functionality also is available programmatically through a new Events API endpoint.

Why You’ll Want Events Search

The data provided by Events Search allows for the debugging of potential deliverability issues your mail streams may encounter, viewing the lifecycle of individual emails, and syncing your SparkPost data to external sources.

In fact, the Events API and Events Search feature have the most flexible filtering capabilities of any SparkPost feature to date, providing the ability to refine queries to events associated with individual emails, regardless of what starting piece of information is used.

Some common scenarios for Events Search include:

Digging into issues with a particular recipient domain. Imagine those times when you’re seeing decreased engagement or increased blocks to a particular domain. Events Search can filter message events to find all messages sent to a specific domain like to see details of what’s going on.

Drilling down on individual messages in an A/B test. If you’ve run a test using SparkPost’s A/B features, you might want to see what’s happened at the individual message level. With Events Search, it’s easy to filter or search events by the A/B test ID.

Searching by subject to examine details for a mailing. Let’s say you’re on the email team working with a number of clients or stakeholders and need to help them troubleshoot deliverability issues with a particular piece of content. Events Search can make that easy—even if the mailings cross several campaign IDs.

This kind of flexibility really helps when you’re working to solve email challenges every day. Penny-Merelle Gray, a product manager on the email deliverability team at Intercom, works with a lot of email. She saw the value of Events Search right away. “We’ve wanted this for ages. It’s so useful when you’re troubleshooting and trying to deep dive in an investigation.”

Events Search Replaces Message Events API

The improved Events Search extends our old Message Events feature to include new filtering and keyword search options. The Events Search API’s filtering capabilities are even more powerful and flexible than those provided by the old Message Events API.

By the way, if you’ve coded against the old Message Events API, we definitely encourage you to move to the new Events API. The increased power and flexibility is well worth it. Our engineering team has created a helpful guide for migrating and getting started with Events Search.

Below is a handy cross-section displaying what is filterable in each API, and as you can see, we’ve added many new ways to search for the exact events you need.


Filtering Capability Message Events Support Events Search Support
Event Types X X
Recipient Addresses X X
Friendly From Addresses X X
Bounce Classes X X
Bounce/Failure/Rejection Reasons* X X
Subaccounts X X
Transmission IDs X X
Message IDs X X
Campaign IDs* X X
Template IDs* X X
Recipient Domains* X
Subject* X
Sending Domains* X
Sending IPs X
IP Pools* X
AB Test IDs* X
AB Test Version X
Search by keyword X


* = supports keyword search in Events Search API and UI

Let’s Get Started: API or UI?

The Events API is a powerful way to search through SparkPost email events from your own code. The API endpoint is /api/v1/events/message. This endpoint supports adding search criteria through query parameters added to the URL. Please refer to the Events API documentation for additional information about the different filters you can add to Events API calls.

For day-to-day interactive use, the Events Search report is a new SparkPost application feature built on top of the Events API that provides a convenient way to perform the same types of queries you would with the Events API, but without having to write a line of code.

The new report lives under the “Reports” section of the SparkPost application. For those familiar with the SparkPost application, this report is very similar to the interface provided by the old Message Events report (and in fact, the Events Search report has replaced the Message Events report). The new report provides all the same searchability as the Events API, under the “More Filters” section. There, you can add multiple filters, and also provide word search filters where applicable.

Want to integrate your systems with the Events API?

As I mentioned earlier, our engineering team created a quick start and migration guide called Getting Started with the Events Search API. It’s a great resource for developers integrating against the new Events API.