Message Events

Run in Postman
Import the SparkPost API as a Postman collection

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. 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 the same event data that gets delivered to you through webhooks.

Data retention

Message event data is retained for 10 days and is generally available within 1 minute. Aggregate reporting data is available through metrics or the app for up to 6 months.

Note: The maximum URI length is 4096 characters so please keep your message events queries below that size.

Event Types

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


bounce Event

Remote MTA has permanently rejected a message.

{
  "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": "127.0.0.1",
  "ip_pool": "Example-Ip-Pool",
  "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",
  "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",
  "recv_method": "esmtp",
  "routing_domain": "example.com",
  "sending_ip": "127.0.0.1",
  "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": "2016-04-18T14:25:07.000+00:00",
  "transactional": "1",
  "transmission_id": "65832150921904138",
  "type": "bounce"
}

Events

 

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.

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.

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.

recv_method

Protocol by which SparkPost received this message.

routing_domain

Domain receiving this message.

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 with +00:00 style timezone information.

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.


The SparkPost Message Events API uses MaxMind software MaxMind License


Request

GET /api/v1/message-events?recipients=recipient@example.com&template_ids=templ-1234&per_page=1

Response

{
  "results": [
    {
      "type": "click",
      "campaign_id": "Example Campaign Name",
      "customer_id": "1",
      "delv_method": "esmtp",
      "event_id": "92356927693813856",
      "friendly_from": "sender@example.com",
      "injection_time": "2016-04-18T14:25:07.000Z",
      "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"
      },
      "rcpt_tags": [
        "male",
        "US"
      ],
      "rcpt_to": "recipient@example.com",
      "raw_rcpt_to": "recipient@example.com",
      "rcpt_type": "cc",
      "routing_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": "templ-1234",
      "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",
      "geo_ip": {
        "country": "US",
        "region": "MD",
        "city": "Columbia",
        "latitude": 39.1749,
        "longitude": -76.8375
      }
    }
  ]
}

Search for Message Events

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

Parameters

recipients list

Delimited list of recipients to search.

friendly_froms list

Delimited list of friendly from emails to search.

events list

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

bounce_classes number

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

reason string

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

subaccounts list

Delimited list of subaccount IDs to search.

transmission_ids list

Delimited list of transmission IDs to search.

campaign_ids string

Delimited list of campaign IDs to search.

template_ids list

Delimited list of template IDs to search.

ab_test_ids list

Delimited list of A/B test IDs to search.

message_ids list

Delimited list of message IDs to search.

timezone string, default is UTC

Standard timezone identification string.

to datetime

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

from datetime

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

page number, default is 1

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

per_page number, default is 1000

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

Returns a list of message events that matched the filtered search. The response is sorted by descending timestamp.

Documentation

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

Request

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

Response

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

Events Documentation

GET/api/v1/message-events/events/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/message-events/events/samples?events=bounce

Response

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

Events Samples

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

Parameters

events string

Event types for which to get a sample payload. Defaults to all event types. Use the Webhooks Documentation endpoint to list the available event types.

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