Message Events

The Message Events API allows searching for recent events, and supports various types of result filtering. Available events include message status - injection, delivery, bounce - as well as recipient engagement - clicks and opens. Message Events is an on-demand (pull) interface to the same underlying event data that gets delivered in a near-real-time (push) fashion via Webhooks.

You can get all event types or only specific ones, such as bounces, deliveries, or clicks. You can filter by date range, campaign, or just about any other field. Event data is retained for 10 days and is generally available within 1 minute. Of course, aggregate reporting data is available via our metrics endpoint or the UI reports for much longer.

Data retention

Message Events API data is retained for 10 days.

Using Postman

If you use Postman you can click the following button to import the SparkPost API as a collection:

Run in Postman

Copyrights

The SparkPost message events API uses MaxMind software MaxMind License

Events Documentation

Documentation

GET/api/v1/message-events/events/documentation

List descriptions of the event fields that could be included in a response from the Message Events search endpoint. Fields will vary by event type.

Examples

Request

GET /api/v1/message-events/events/documentation


Events Samples

Samples

GET/api/v1/message-events/events/samples{?events}
URI Parameters
events

Event types for which to get a sample payload, use the Webhooks Events endpoint to list the available event types, defaults to all event types.

Example: bounce

List an example of the event data that will be included in a response from the Message Events search endpoint.

Examples

Request

GET /api/v1/message-events/events/samples?events=bounce


Message Events

Search for Message Events

GET/api/v1/message-events{?bounce_classes,campaign_ids,delimiter,events,friendly_froms,from,message_ids,page,per_page,reason,recipients,subaccounts,template_ids,timezone,to,transmission_ids}
URI Parameters
bounce_classes

delimited list of bounce classification codes to search. (See Bounce Classification Codes.)

Example: 1
campaign_ids

delimited list of campaign ID’s to search (i.e. the campaign id used during creation of a transmission).

Notes: Not available for sms_status type.

Example: Example Campaign Name
delimiter

Specifies the delimiter for query parameter lists

Default: ,

Example: ,
events

delimited list of event types to search. Defaults to all event types.

Example: delivery,injection,bounce,delay,policy_rejection,out_of_band,open,click,generation_failure,generation_rejection,spam_complaint,list_unsubscribe,link_unsubscribe
friendly_froms

delimited list of friendly from emails to search.

Notes: Not available for sms_status type.

Example: sender@mail.example.com
from

Datetime in format of YYYY-MM-DDTHH:MM.

Default: 24 hours ago

Example: 2014-07-20T08:00
message_ids

delimited list of message ID’s to search.

Example: 0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e
page

The results page number to return. Used with per_page for paging through results.

Default: 1

Example: 1
per_page

Number of results to return per page. Must be between 1 and 10,000 (inclusive).

Default: 1000

Example: 1000
reason

Bounce/failure/rejection reason that will be matched using a wildcard (e.g., %reason%).

Example: bounce
recipients

delimited list of recipients to search.

Example: recipient@example.com
subaccounts

delimited list of subaccount ID’s to search.

Example: 101
template_ids

delimited list of template ID’s to search.

Example: templ-1234
timezone

Standard timezone identification string.

Default: UTC

Example: America/New_York
to

Datetime in format of YYYY-MM-DDTHH:MM.

Default: now

Example: 2014-07-20T09:00
transmission_ids

delimited list of transmission ID’s to search (i.e. id generated during creation of a transmission).

Example: 65832150921904138

Perform a filtered search for message event data. The response is sorted by descending timestamp.

Hint! Use the delv_method key to differentiate between Email, Push, and SMS type events.

Examples

Request

GET /api/v1/message-events?bounce_classes=1&campaign_ids=Example Campaign Name&delimiter=,&events=delivery,injection,bounce,delay,policy_rejection,out_of_band,open,click,generation_failure,generation_rejection,spam_complaint,list_unsubscribe,link_unsubscribe&friendly_froms=sender@mail.example.com&from=2014-07-20T08:00&message_ids=0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e&page=1&per_page=1000&reason=bounce&recipients=recipient@example.com&subaccounts=101&template_ids=templ-1234&timezone=America/New_York&to=2014-07-20T09:00&transmission_ids=65832150921904138