Events

The 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. You can fetch all event types or only specific ones, such as bounces, deliveries, or clicks. You can also filter by date range, campaign, or just about any other field. It provides access to similar event data that can also be delivered via Webhooks.

The maximum URI length is 4096 characters, so please keep your queries below that size when adding filters to an API call.

The SparkPost Events API uses MaxMind software MaxMind License

Data Retention

Data in the Events API is retained for 10 days. Aggregate reporting data is available through metrics or the app for up to 6 months.

Event Types

You can query the following types of events from the Events API.

bounce Event

Remote MTA has permanently rejected a message.

{
  "amp_enabled": true,
  "bounce_class": "1",
  "campaign_id": "Example Campaign Name",
  "click_tracking": true,
  "customer_id": "1",
  "delv_method": "esmtp",
  "device_token": "45c19189783f867973f6e6a5cca60061ffe4fa77c547150563a1192fa9847f8a",
  "error_code": "554",
  "event_id": "92356927693813856",
  "friendly_from": "sender@example.com",
  "initial_pixel": true,
  "injection_time": "2016-04-18T14:25:07.000Z",
  "ip_address": "18.236.253.72",
  "ip_pool": "example-ip-pool",
  "mailbox_provider": "Gsuite",
  "mailbox_provider_region": "Europe - UK",
  "message_id": "000443ee14578172be22",
  "msg_from": "sender@example.com",
  "msg_size": "1337",
  "num_retries": "2",
  "open_tracking": true,
  "rcpt_meta": {
    "customKey": "customValue"
  },
  "rcpt_tags": [
    "male",
    "US"
  ],
  "rcpt_to": "recipient@example.com",
  "rcpt_hash": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
  "raw_rcpt_to": "recipient@example.com",
  "rcpt_type": "cc",
  "raw_reason": "MAIL REFUSED - IP (17.99.99.99) is in black list",
  "reason": "MAIL REFUSED - IP (a.b.c.d) is in black list",
  "recipient_domain": "example.com",
  "recv_method": "esmtp",
  "routing_domain": "example.com",
  "scheduled_time": "1588348800",
  "sending_domain": "example.com",
  "sending_ip": "18.236.253.72",
  "sms_coding": "ASCII",
  "sms_dst": "7876712656",
  "sms_dst_npi": "E164",
  "sms_dst_ton": "International",
  "sms_src": "1234",
  "sms_src_npi": "E164",
  "sms_src_ton": "Unknown",
  "subaccount_id": "101",
  "subject": "Summer deals are here!",
  "template_id": "templ-1234",
  "template_version": "1",
  "timestamp": "2019-06-16T19:02:09.373Z",
  "transactional": "1",
  "transmission_id": "65832150921904138",
  "type": "bounce"
}

Events

amp_enabled

Indicates whether or not amp format was enabled.

bounce_class

Classification code for a given message (see Bounce Classification Codes).

campaign_id

Campaign of which this message was a part.

click_tracking

Indicates whether or not click tracking was enabled.

customer_id

SparkPost-customer identifier through which this message was sent.

delv_method

Protocol by which SparkPost delivered this message.

device_token

Token of the device / application targeted by this PUSH notification message. Applies only when delv_method is gcm or apn.

error_code

Error code by which the remote server described a failed delivery attempt.

event_id

Unique event identifier.

friendly_from

Friendly sender or 'From' header in the original email.

initial_pixel

Indicates whether or not initial open pixel tracking was enabled.

injection_time

Time at which this message was injected into SparkPost.

ip_address

IP address of the host to which SparkPost delivered this message; in engagement events, the IP address of the host where the HTTP request originated.

ip_pool

IP pool through which this message was sent.

mailbox_provider

Mailbox Provider of the recipient.

mailbox_provider_region

Region of the Mailbox Provider.

message_id

SparkPost-cluster-wide unique identifier for this message.

msg_from

Sender address used on this message's SMTP envelope.

msg_size

Message's size in bytes.

num_retries

Number of failed attempts before this message was successfully delivered; when the first attempt succeeds, zero.

open_tracking

Indicates whether or not open tracking was enabled.

rcpt_meta

Metadata describing the message recipient.

rcpt_tags

Tags applied to the message which generated this event.

rcpt_to

Lowercase version of recipient address used on this message's SMTP envelope.

rcpt_hash

Hashed version of recipient address used on this message's SMTP envelope.

raw_rcpt_to

Actual recipient address used on this message's SMTP envelope.

rcpt_type

Indicates that a recipient address appeared in the Cc or Bcc header or the archive JSON array.

raw_reason

Unmodified, exact response returned by the remote server due to a failed delivery attempt.

reason

Canonicalized text of the response returned by the remote server due to a failed delivery attempt.

recipient_domain

Domain part of the recipient address used on this message's SMTP envelope.

recv_method

Protocol by which SparkPost received this message.

routing_domain

Domain receiving this message.

scheduled_time

Time at which the email was scheduled to be sent.

sending_domain

Domain part of the sender or 'From' header in the original email.

sending_ip

IP address through which this message was sent.

sms_coding

Data encoding used in the SMS message.

sms_dst

SMS destination address.

sms_dst_npi

Destination numbering plan identification.

sms_dst_ton

Type of number for the destination address.

sms_src

SMS source address.

sms_src_npi

Source numbering plan identification.

sms_src_ton

Type of number for the source address.

subaccount_id

Unique subaccount identifier.

subject

Subject line from the email header.

template_id

Slug of the template used to construct this message.

template_version

Version of the template used to construct this message.

timestamp

Event date and time, millisecond precision in UTC.

transactional

Indicates if the transmission was marked as transactional.

transmission_id

Transmission which originated this message.

type

Type of event this record describes.

display_name

Human readable label for the event name.

event_description

Human readable description of the event.

Keyword Searching

Some of the filter query parameters in the Events API support keyword searching. Keyword searching allows for filtering results without the precise value and also allows filtering for multiple values, without having to enter in each value individually. Keywords are determined by natural breaks in phrases by spaces, dashes, underscores, and in special cases periods(recipient_domains and sending_domains).

For example, suppose the following campaigns are sent via SparkPost: blackfriday-specials, blackfriday-members, and blackfriday-flash-deals. Without keyword searching, to retrieve results for all three campaigns, ?campaigns=blackfriday-specials,blackfriday-members,blackfriday-flash-deals would need to be added to the Events API request. With keyword searching, the previous example can be condensed into ?campaigns=blackfriday, and the same data is returned as would be by the much longer filter.

Its important to distinguish that searching for a keyword is different than a partial search. In the previous example, searching for ?campaigns=friday will not return any of the same results that ?campaigns=blackfriday would return.

Filters that support keyword searching are:

ab_tests
campaigns
ip_pools
reasons
recipient_domains
sending_domains
subjects
templates
mailbox_providers
mailbox_provider_regions

Pagination

The Events API supports pagination for queries with larger result sets. Pagination is done through the use of the cursor and per_page query parameters. The per_page query parameter tells the Events API the number of events to return in a single request, and supports a maximum value of 10,000.

To start a paging request, add the query parameter ?cursor=initial to your Events API request. This will fetch the first page of results. If cursor is not provided, then the default value of initial is applied. In the response body, there are three main keys: results, total_count and links. results is an array which contains the page of JSON events that matched the request, total_count is an integer that describes the total number of JSON events that matched your request, and links is an object which provides a way to request the next page of events, if there is more than one page.

Once you have the response, you then can use links to retrieve the URL for your next page, which will be prefilled with the appropriate value for the cursor query parameter, as well as any other filters you supplied with the original request.

In the following examples, to retrieve the first page, we use the initial value for the cursor query parameter. the cursor value from the next key in the links object, and use that to make the request for the second page. This process would then be repeated until all results have been paged through, at which point the links object will not have a next key, and no further additional requests are necessary.

If your result set is less than one page of data, then the links object will not have a next key.

Pagination requests count towards the number of requests allowed by rate limiting, the same as non-paginated requests.

Request

GET /api/v1/events/message?per_page=1000&cursor=initial

Response

    {
      "results": [
        ...
      ],
      "total_count": 20000,
      "links": {
        "next": "/api/v1/events/message?events=delivery&per_page=1000&cursor=WycyMDE4LTExLTA1VDIyOjQ1OjM5LjAwMFonLCAnc3BjLTM4MTQ1MjY3MjMyNTA2NTEwJ10="
      }
    }

Retrieve First Page

GET/api/v1/events/message{?per_page,cursor}

Parameters

per_page string

cursor string

Request

GET /api/v1/events/message?per_page=1000&cursor=WycyMDE4LTExLTA1VDIyOjQ1OjM5LjAwMFonLCAnc3BjLTM4MTQ1MjY3MjMyNTA2NTEwJ10=

Response

    {
      "results": [
        ...
      ],
      "total_count": 20000,
      "links": {
        "next": "/api/v1/events/message?events=delivery&per_page=1000&cursor=WycyMDE4LTExLTA0VDIyOjQ1OjM5LjAwMFonLCAndWF0LTM4MTQ1MjE3MjUyNTY2NTIwJ10="
      }
    }

Retrieve Subsequent Page

GET/api/v1/events/message{?per_page,cursor}

Parameters

per_page string

cursor string

Search

Request

GET /api/v1/events/message?recipients=recipient@example.com&templates=my-template

Response

{
  "results": [
    {
      "type": "click",
      "campaign_id": "Example Campaign Name",
      "customer_id": "1",
      "delv_method": "esmtp",
      "event_id": "92356927693813856",
      "friendly_from": "sender@example.com",
      "geo_ip": {
        "country": "US",
        "region": "MD",
        "city": "Columbia",
        "latitude": "39.1749",
        "longitude": "-76.8375"
      },
      "injection_time": "2016-04-18T14:25:07.000+00:00",
      "ip_address": "127.0.0.1",
      "ip_pool": "Example-Ip-Pool",
      "message_id": "000443ee14578172be22",
      "msg_from": "sender@example.com",
      "msg_size": "1337",
      "num_retries": "2",
      "queue_time": "12",
      "rcpt_meta": {
        "customKey": "customValue",
        "anotherKey": [
          "value1",
          "value2",
          "value3"
        ]
      },
      "rcpt_tags": [
        "male",
        "US"
      ],
      "rcpt_to": "recipient@example.com",
      "raw_rcpt_to": "recipient@example.com",
      "rcpt_type": "cc",
      "recipient_domain": "example.com",
      "routing_domain": "example.com",
      "sending_domain": "example.com",
      "sending_ip": "127.0.0.1",
      "subaccount_id": "101",
      "subject": "Summer deals are here!",
      "target_link_name": "Example Link Name",
      "target_link_url": "http://example.com",
      "template_id": "my-template",
      "template_version": "1",
      "timestamp": "2016-04-18T14:25:07.000+00:00",
      "transmission_id": "65832150921904138",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
      "mailbox_provider": "Gmail",
      "mailbox_provider_region": "Europe"
    }
  ],
  "total_count": 1,
  "links": {}
}

Search for Message Events

GET/api/v1/events/message{?ab_tests,ab_test_versions,bounce_classes,campaigns,cursor,delimiter,event_ids,events,from,from_addresses,ip_pools,messages,per_page,reasons,recipients,recipient_domains,subjects,sending_domains,sending_ips,subaccounts,templates,to,transmissions}

Parameters

from string, default is 24 hours ago

Datetime in format of YYYY-MM-DDTHH:MM:ssZ, inclusive. Value should be in UTC.

to string, default is 1 minute ago

Datetime in format of YYYY-MM-DDTHH:MM:ssZ, exclusive. Value should be in UTC.

cursor string, default is initial

Results cursor for pagination. Used in conjunction with per_page parameter. See Pagination section for details.

per_page number, default is 1000

Maximum number of results to return per page. Must be between 1 and 10,000.

delimiter string, default is ,

event_ids string

Comma delimited list of event IDs to search.

events string, default is all event types

Comma delimited list of event types to search.

recipients string

Comma delimited list of recipients to search.

recipient_domains string

Comma delimited list of recipient domains to search. Supports keyword searching by domain segment.

from_addresses string

Comma delimited list of friendly from addresses to search.

sending_domains string

Comma delimited list of sending domains to search. Supports keyword searching by domain segment.

subjects string

Comma delimited list of subject lines from the email header to search. Supports keyword searching.

bounce_classes number

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

reasons string

Comma delimited list of Bounce/failure/rejection reason to search. Supports keyword searching

campaigns string

Comma delimited list of campaign IDs to search. Supports keyword searching.

templates string

Comma delimited list of template IDs to search. Supports keyword searching.

sending_ips string

Comma delimited list of sending IP addresses to search.

ip_pools string

Comma delimited list of IP pool IDs to search. Supports keyword searching.

subaccounts string

Comma delimited list of subaccount IDs to search.

messages string

Comma delimited list of message IDs to search.

transmissions string

Comma delimited list of transmission IDs to search.

mailbox_providers string

Comma delimited list of mailbox providers to search. Supports keyword searching.

mailbox_provider_regions string

Comma delimited list of mailbox provider regions to search. Supports keyword searching.

ab_tests string

Comma delimited list of A/B test IDs to search. Supports keyword searching.

ab_test_versions number

Comma delimited list of version numbers of A/B tests to search. If provided, ab_tests parameter becomes required.

Returns a list of message events that matched the filtered search.

Request

GET /api/v1/events/ingest?error_typessubaccounts

Response

{
  "results": [
    {
      "retryable": false,
      "number_succeeded": 440,
      "event_id": "1d1941e9-4987-1a6c-b124-2a4328585721",
      "number_failed": 460,
      "batch_id": "fbd59e4c-1629-4736-803d-201ff9fa8dd6",
      "expiration_timestamp": "2019-06-16T19:02:09.373Z",
      "error_type": "validation",
      "href": "https://api.sparkpost.com/ingest/number_failed/fbd59e4c-1629-4736-803d-201ff9fa8dd6",
      "type": "error",
      "customer_id": 8675308,
      "subaccount_id": 38,
      "number_duplicates": 20,
      "timestamp": "2019-06-06T19:02:09.373Z"
    }
  ],
  "total_count": 1,
  "links": {}
}

Search for Ingest Events

GET/api/v1/events/ingest{?batch_ids,cursor,delimiter,error_types,events,event_ids,from,retryable,subaccounts,to}

Parameters

from string, default is 24 hours ago

Datetime in format of YYYY-MM-DDTHH:MM:ssZ, inclusive.

to string, default is 1 minute ago

Datetime in format of YYYY-MM-DDTHH:MM:ssZ, exclusive.

cursor string, default is initial

Results cursor for pagination. Used in conjunction with per_page parameter. See Pagination section for details.

per_page number, default is 1000

Maximum number of results to return per page. Must be between 1 and 10,000.

delimiter string, default is ,

events string, default is success,error

Comma delimited list of event types to search.

event_ids string

Comma delimited list of event IDs to search.

batch_ids string

Comma delimited list of batch IDs to search.

retryable boolean

Filter ingest events by whether or not they are retryable.

subaccounts string

Comma delimited list of subaccount IDs to search.

Returns a list of ingest events that matched the filtered search.

Documentation

These endpoints are used to generate the samples and descriptions for the Event Types section.

Request

GET /api/v1/events/message/documentation

Response

{
  "results": [
    {
      "type": {
        "description": "Type of event this record describes",
        "sampleValue": "bounce"
      },
      ...
    },
    ...
  ]
}

Events Documentation

GET/api/v1/events/message/documentation

Returns a list of descriptions of the event fields that could be included in a response from the message events search. Fields will vary by event type.

Request

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

Response

{
  "results": [
    {
      "type": "bounce",
      ...
    }
  ]
}

Events Samples

GET/api/v1/events/message/samples{?events}

Parameters

events string

Event types for which to get a sample payload. Defaults to all event types. See Events Types for the list of available event types.

Returns an example message event for each event type listed in the events parameter.