Metrics

SparkPost logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance. This reporting data is available in the app (EU) or through the Metrics API. The Metrics API provides a variety of endpoints enabling you to retrieve a summary of the data, data grouped by a specific qualifier, or data by event type. Within each endpoint, you can also apply various filters to drill down to the data for your specific reporting needs.

Data retention

Metrics API data is retained for 6 months.

Terminology

Definitions for terms found in Metrics API

Term	Definition
`count_targeted`	Messages successfully injected into SparkPost as well as rejected by it
`count_injected`	Messages injected to or received by SparkPost
`count_sent`	Messages that SparkPost attempted to deliver, which includes both Deliveries and Bounces
`count_accepted`	Messages an ISP or other remote domain accepted (less Out-of-Band Bounces)
`count_delivered`	Messages delivered
`count_delivered_first`	Messages delivered on the first attempt
`count_delivered_subsequent`	Messages delivered that required more than one delivery attempt
`count_rendered`	Total renderings of a message
`count_nonprefetched_rendered`	Total non-prefetched renderings of a message
`count_initial_rendered`	Total initial renderings of a message
`count_nonprefetched_initial_rendered`	Total initial non-prefetched renderings of a message
`count_unique_rendered`	Total number of messages that were rendered at least once
`count_nonprefetched_unique_rendered`	Total number of non-prefetched messages that were rendered at least once
`count_unique_initial_rendered`	Total number of messages that were initally rendered at least once
`count_nonprefetched_unique_initial_rendered`	Total number of non-prefetched messages that were initally rendered at least once
`count_unique_confirmed_opened`	Total number of messages that were rendered or had at least one link selected
`count_nonprefetched_unique_confirmed_opened`	Total number of non-prefetched messages that were rendered or had at least one link selected
`count_clicked`	Total number of times that links were selected across all messages
`count_unique_clicked`	Total number of messages which had at least one link selected one or more times
`count_bounce`	Total number of bounced messages, which includes both In-Band and Out-of-Band bounces
`count_hard_bounce`	Total number of Bounced messages due to hard bounce classification reasons
`count_soft_bounce`	Total number of Bounced messages due to soft bounce classification reasons
`count_block_bounce`	Total number of Bounced messages due to an IP block
`count_admin_bounce`	Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected
`count_undetermined_bounce`	Total number of Bounced messages due to undetermined bounce reasons
`count_rejected`	Messages rejected due to policy or that failed to generate
`count_policy_rejection`	Messages rejected by SparkPost due to policy
`count_generation_failed`	Message generation failed for an intended recipient
`count_generation_rejection`	Messages rejected by SparkPost due to policy
`count_inband_bounce`	Messages that bounced on delivery attempt during the SMTP session
`count_outofband_bounce`	Messages that the ISP bounced subsequent to a successful delivery
`count_delayed`	Total number of delays due to any temporary failure
`count_delayed_first`	Messages delayed on the first delivery attempt
`total_msg_volume`	Total size of delivered messages, in bytes (including attachments)
`count_spam_complaint`	Number of spam complaints received from an ISP
`total_delivery_time_first`	Total time taken to deliver messages on first attempt (milliseconds)
`total_delivery_time_subsequent`	Total time taken to delivery messages on subsequent attempts (milliseconds)
`count_unsubscribe`	Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature
`count_inbox_panel`	Deliverability Add-On Panel messages delivered to the inbox.
`count_spam_panel`	Deliverability Add-On Panel messages delivered to the spam folder.
`count_inbox_seed`	Deliverability Add-On All Seed messages delivered to the inbox.
`count_spam_seed`	Deliverability Add-On All Seed messages delivered to the spam folder.
`count_inbox_seed_private`	Deliverability Add-On Private Seed messages delivered to the inbox.
`count_spam_seed_private`	Deliverability Add-On Private Seed messages delivered to the spam folder.
`count_inbox_seed_virtual`	Deliverability Add-On Virtual Seed messages delivered to the inbox.
`count_spam_seed_virtual`	Deliverability Add-On Virtual Seed messages delivered to the spam folder.
`count_moved_to_inbox`	Deliverability Add-On Panel messages delivered to the spam folder then moved to the inbox.
`count_moved_to_spam`	Deliverability Add-On Panel messages delivered to the inbox then moved to the spam folder.

Note: The metrics count_inbox_panel,count_spam_panel, count_inbox_seed, count_spam_seed,count_inbox_seed_private,count_spam_seed_private, count_inbox_seed_virtual,count_spam_seed_virtual,count_moved_to_inbox, and count_moved_to_spam are only available to the SparkPost Deliverability Add-On customers.

For a given request, average first attempt delivery latency can be calculated as total_delivery_time_first / count_delivered. A similar calculation holds for total_delivery_time_subsequent.

Precision Parameter

When the precision parameter is specified for aggregate metric requests, the bounds of the time window (from, to) are rounded to the nearest time matching the precision. For example, requesting data between 4:22 to 6:37 would return results within the following time windows:

Precision	Rounded time window	Max time window
`1min`	`04:22:00` - `06:36:59`	`24 hours`
`5min`	`04:20:00` - `06:39:59`	`24 hours`
`15min`	`04:15:00` - `06:44:59`	`48 hours`
`hour`	`04:00:00` - `06:59:59`	`31 days`
`day`	`00:00:00` - `23:59:59`	`No max`

Time-series Metrics

When the precision parameter is specified for the time-series request, it reflects the period of time the data is grouped by. The same max time window ranges apply for time-series requests as do aggregate requests. Precisions 12hr, week, and month may also be used for time-series requests.

Filters

Metric data can be filtered by using query parameters in the query component of the request URI. Each Metrics endpoint specifies certain filters that can be set as query parameters. The exact filters and query parameters available to each route are listed in the respective route's "parameters" section below. The filters can be specified using either a simple or advanced query syntax.

Simple Filters

Simple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them. For example metrics can be limited to sending domains equal to "sparkpost.com" or "example.org" with the following query string: ?sending_domains=sparkpost.com,example.org

Advanced Filters

The Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the query_filters query parameter.

The value of the query_filters query parameter must be structured as a URL-encoded JSON object. The Metrics API uses JSON Schema to define and validate advanced filters. Advanced Filter requests that do not adhere to the schema will result in a 400 error response. Specific schema violations will be attached to the validationErrors property of the error response. The exact schema can be retrieved through the /deliverability/query-filters-schema endpoint. See Advanced Query JSON Schema.

Please note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the query_filters parameter is used. e.g. in ?domains=mailing.com&query_filters={}, the domains query parameter will be ignored. Other query parameters like from, to, metrics, limit, etc., will be processed as expected.

Groupings Structure

The JSON object consists of a root level "groupings" array containing compare objects. Multiple compare groups are evaluated such that the relationship between them is an AND operation.

Example:

{
  "groupings": [
    {
       ... compare group 
    },
    {
       ... compare group 
    }
  ]
}

Compare Group

The compare objects have a single logical comparison operator (OR or AND) that will be used to compare all of the filter conditions in the group.

Example:

{
      "AND":{
        "domains":{
          "eq":[
            "gmail.com",
            "yahoo.com",
            "hotmail.com"
          ],
          "like":[
            "mail"
          ]
        },
        "sending_domains":{
          "notEq": [ 
            "sparkpost.com" 
          ],
          "notLike": [
            ".io"
          ]
        }
      }
    }

Each filter group is comprised of the filter keys and comparator keywords. Filter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.

Filter Keys:

           domains
           sending_ips
           ip_pools
           campaigns
           subject_campaigns
           templates
           sending_domains
           mailbox_providers
           subaccounts
           mailbox_provider_regions

Comparator Keywords:

           eq       - array of exact values to match
           like     - array of substrings to match on; values must be at least 3 characters long
           notEq    - array of exact values to NOT match
           notLike  - array of substrings to NOT match on; values must be at least 3 characters long

Put it all together:

JSON query object:

{
  "groupings":[
    {
      "AND":{
        "domains":{
          "eq":[
            "gmail.com",
            "yahoo.com",
            "hotmail.com"
          ],
          "like":[
            "mail"
          ]
        },
        "sending_domains":{
          "notEq":[
            "sparkpost.com"
          ]
        }
      }
    },
    {
      "OR":{
        "templates":{
          "eq":[
            "default"
          ]
        },
        "campaigns":{
          "like":[
            "333",
            "344",
            "355"
          ]
        }
      }
    },
    {
      "OR":{
        "campaigns":{
          "notLike":[
            "Friday"
          ],
          "notEq":[
            "stuff",
            "things"
          ]
        }
      }
    }
  ]
}

Compressed (whitespace and line end characters removed) and URL encoded:

?query_filters=%7B%22groupings%22%3A%5B%7B%22AND%22%3A%7B%22domains%22%3A%7B%22eq%22%3A%5B%22gmail.com%22%2C%22yahoo.com%22%2C%22hotmail.com%22%5D%2C%22like%22%3A%5B%22mail%22%5D%7D%2C%22sending_domains%22%3A%7B%22notEq%22%3A%5B%22sparkpost.com%22%5D%7D%7D%7D%2C%7B%22OR%22%3A%7B%22templates%22%3A%7B%22eq%22%3A%5B%22default%22%5D%7D%2C%22campaigns%22%3A%7B%22like%22%3A%5B%22333%22%2C%22344%22%2C%22355%22%5D%7D%7D%7D%2C%7B%22OR%22%3A%7B%22campaigns%22%3A%7B%22notLike%22%3A%5B%22Friday%22%5D%2C%22notEq%22%3A%5B%22stuff%22%2C%22things%22%5D%7D%7D%7D%5D%7D

Request

GET /api/v1/metrics/deliverability/query-filters-schema

Response

  {
      "results": {
          "$schema": "http://json-schema.org/draft-07/schema",
          "$id": "root",
          "type": "object",
          "title": "The root schema",
          "description": "The root schema comprises the entire JSON document.",
          "default": {},
          "required": [
              "groupings"
          ],
          "properties": {
              ...
          },
          "additionalProperties": false,
          "$defs": {
              "groupings": {
                  ...
              },
              "filters": {
                  ...
              },
              "logicalOperators": {
                  ...
              }
          }
      }
  }

Advanced Query JSON Schema

GET/api/v1/metrics/deliverability/query-filters-schema

Retrieves the JSON schema for validating the query_filters JSON value.

Request

GET /api/v1/metrics/

Response

  {
      "results": {},
      "links": [
          {
             "href": "/api/v1/metrics/",
             "rel": "",
             "method": "GET"
          },
          {
            "href": "/api/v1/metrics/campaigns",
            "rel": "campaigns",
            "method": "GET"
          },
          {
            "href": "/api/v1/metrics/deliverability",
            "rel": "deliverability",
            "method": "GET"
          },
          {
            "href": "/api/v1/metrics/domains",
            "rel": "domains",
            "method": "GET"
          },
          {
            "href": "/api/v1/metrics/ip-pools",
            "rel": "ip-pools",
            "method": "GET"
          },
          {
            href: '/api/v1/metrics/mailbox-provider-regions',
            rel: 'mailbox-provider-regions',
            method: 'GET'
          },
          {
            href: '/api/v1/metrics/mailbox-providers',
            rel: 'mailbox-providers',
            method: 'GET'
          },
          {
            "href": "/api/v1/metrics/sending-ips",
            "rel": "sending-ips",
            "method": "GET"
          },
          {
            "href": "/api/v1/metrics/subject-campaigns",
            "rel": "subject-campaigns",
            "method": "GET"
          }
      ]
  }

Discoverability Links

GET/api/v1/metrics/

The Metrics API is designed for discoverability of child links. Calling the API root displays a list of URIs that exists within the Metrics API.

Aggregations

The aggregations endpoints allow you to get high-level summaries of your data grouped by specific quantifiers such as sending domain or template. You can also get specific types of data, such as rejection reason, to better understand your sending.

Use the subaccount field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.

Request

GET /api/v1/metrics/deliverability?from=2018-07-11T08:00&metrics=count_targeted

Response

{
  "results": [
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ],
  "links": [
    {
      "href": "/api/v1/metrics/deliverability",
      "rel": "deliverability",
      "method": "GET"
    }
  ]
}

Metrics Summary

GET/api/v1/metrics/deliverability{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies an alternate delimiter for all included query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Precision of the time window (from, to) bounds. All values valid up to a 24 hour window, except for hour which is also valid up a 31 day window. The day precision will return data in UTC regardless of the specified timezone. See: Precision Parameter.

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

Possible Values: count_injected, count_bounce, count_rejected, count_delivered, count_delivered_first, count_delivered_subsequent, total_delivery_time_first, total_delivery_time_subsequent, total_msg_volume, count_policy_rejection, count_generation_rejection, count_generation_failed, count_inband_bounce, count_outofband_bounce, count_soft_bounce, count_hard_bounce, count_block_bounce, count_admin_bounce, count_undetermined_bounce, count_delayed, count_delayed_first, count_rendered, count_nonprefetched_rendered, count_unique_rendered, count_nonprefetched_unique_rendered, count_unique_confirmed_opened, count_nonprefetched_unique_confirmed_opened, count_clicked, count_unique_clicked, count_targeted, count_sent, count_accepted, count_spam_complaint, count_inbox_panel, count_spam_panel, count_inbox_seed, count_spam_seed, count_inbox_seed_private, count_spam_seed_private, count_inbox_seed_virtual, count_spam_seed_virtual, count_moved_to_inbox, count_moved_to_spam

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

Provides high-level summary of aggregate metrics and lists the child endpoints that contain aggregate data, which can be used as "group by" qualifiers.

Request

GET /api/v1/metrics/deliverability/domain?from=2018-07-11T08:00&metrics=count_targeted&order_by=count_injected&limit=5

Response

{
  "results": [
    {
      "domain": "aol.com",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "domain": "foo.net",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Metrics by Recipient Domain

GET/api/v1/metrics/deliverability/domain{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,order_by,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by domain over the time window specified.

Request

GET /api/v1/metrics/deliverability/sending-ip?from=2018-07-11T08:00&metrics=count_targeted&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "sending_ip": "sending-ip-0",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "sending_ip": "sending-ip-1",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Metrics by Sending IP

GET/api/v1/metrics/deliverability/sending-ip{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by sending IP over the time window specified.

Request

GET /api/v1/metrics/deliverability/ip-pool?from=2018-07-11T08:00&metrics=count_targeted&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "ip_pool": "ip-pool-0",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "ip_pool": "ip-pool-1",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Metrics by IP Pool

GET/api/v1/metrics/deliverability/ip-pool{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by IP pool over the time window specified.

Request

GET /api/v1/metrics/deliverability/sending-domain?from=2018-07-11T08:00&metrics=count_targeted&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "sending_domain": "foo.example.com"
    },
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "sending_domain": "bar.example.com"
    },
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "sending_domain": "bat.example.com"
    },
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "sending_domain": "baz.example.com"
    }
  ]
}

Metrics by Sending Domain

GET/api/v1/metrics/deliverability/sending-domain{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by sending domain over the time window specified.

Request

GET /api/v1/metrics/deliverability/subaccount?from=2018-07-11T08:00&metrics=count_targeted&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "subaccount_id": 0
    },
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "subaccount_id": 123
    },
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "subaccount_id": 125
    },
    {
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344,
      "subaccount_id": 127
    }
  ]
}

Metrics by Subaccount

GET/api/v1/metrics/deliverability/subaccount{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by subaccount over the time window specified. Please note that primary account events will be returned grouped by the subaccount_id field containing the value 0.

Request

GET /api/v1/metrics/deliverability/campaign?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "campaign_id": "campaign-0",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "campaign_id": "campaign-1",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Metrics by Campaign

GET/api/v1/metrics/deliverability/campaign{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Sample string required

Provides aggregate metrics grouped by campaign over the time window specified.

Request

GET /api/v1/metrics/deliverability/template?from=2018-07-11T08:00&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "template_id": "template-0",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "template_id": "template-1",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Metrics by Template

GET/api/v1/metrics/deliverability/template{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by template over the time window specified.

Request

GET /api/v1/metrics/deliverability/subject-campaign?from=2018-07-11T08:00&limit=5&order_by=count_inbox_panel

Response

{
  "results": [
    {
      "count_inbox_panel": 564,
      "count_spam_panel": 49,
      "count_inbox_seed": 0,
      "count_spam_seed": 0,
      "count_inbox_seed_private": 0,
      "count_spam_seed_private": 0,
      "count_inbox_seed_virtual": 0,
      "count_spam_seed_virtual": 0,
      "count_moved_to_inbox": 2,
      "count_moved_to_spam": 1,
      "subject_campaign": "[REDACTED] say yes to this deal"
    },
    {
      "count_inbox_panel": 527,
      "count_spam_panel": 19,
      "count_inbox_seed": 0,
      "count_spam_seed": 0,
      "count_inbox_seed_private": 0,
      "count_spam_seed_private": 0,
      "count_inbox_seed_virtual": 0,
      "count_spam_seed_virtual": 0,
      "count_moved_to_inbox": 0,
      "count_moved_to_spam": 2,
      "subject_campaign": "Re: [REDACTED] (Action Requested)"
    }
  ]
}

Metrics by Subject Campaign

GET/api/v1/metrics/deliverability/subject-campaign{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering. Supports deliverability add-on metrics only.

Possible Values: count_inbox_panel, count_spam_panel, count_inbox_seed, count_spam_seed, count_inbox_seed_private, count_spam_seed_private, count_inbox_seed_virtual, count_spam_seed_virtual, count_moved_to_inbox, count_moved_to_spam

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Note: Only available to SparkPost Deliverability Add-On customers

Provides aggregate metrics grouped by deliverability add-on subject campaign over the time window specified.

Request

GET /api/v1/metrics/deliverability/watched-domain?from=2018-07-11T08:00&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "watched_domain": "aol.com",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "watched_domain": "gmail.com",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Metrics by Watched Domain

GET/api/v1/metrics/deliverability/watched-domain{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by watched domain over the time window specified. The difference between domain and watched domain is that watched domains are comprised of the top 99% domains in the world.

Request

GET /api/v1/metrics/deliverability/mailbox-provider?from=2021-03-02T08:00&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "count_injected": 109849,
      "count_targeted": 110923,
      "count_rejected": 1074,
      "count_sent": 107610,
      "mailbox_provider": "Verizon Media Group"
    },
    {
      "count_injected": 102555,
      "count_targeted": 103519,
      "count_rejected": 964,
      "count_sent": 100301,
      "mailbox_provider": "Gmail"
    },
    {
      "count_injected": 53595,
      "count_targeted": 54102,
      "count_rejected": 507,
      "count_sent": 52385,
      "mailbox_provider": "Hotmail / Outlook"
    },
    {
      "count_injected": 16808,
      "count_targeted": 16962,
      "count_rejected": 154,
      "count_sent": 16468,
      "mailbox_provider": "Free.fr"
    },
    {
      "count_injected": 7511,
      "count_targeted": 7576,
      "count_rejected": 65,
      "count_sent": 7534,
      "mailbox_provider": "Educational Institution"
    }
  ]
}

Metrics by Mailbox Provider

GET/api/v1/metrics/deliverability/mailbox-provider{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by mailbox provider over the time window specified.

Request

GET /api/v1/metrics/deliverability/mailbox-provider-region?from=2021-03-02T08:00&limit=5&order_by=count_injected

Response

{
  "results": [
    {
      "count_injected": 109849,
      "count_targeted": 110923,
      "count_rejected": 1074,
      "count_sent": 107610,
      "mailbox_provider_region": "Global"
    },
    {
      "count_injected": 102555,
      "count_targeted": 103519,
      "count_rejected": 964,
      "count_sent": 100301,
      "mailbox_provider_region": "Africa - South Africa"
    },
    {
      "count_injected": 53595,
      "count_targeted": 54102,
      "count_rejected": 507,
      "count_sent": 52385,
      "mailbox_provider_region": "South America - Brazil"
    },
    {
      "count_injected": 16808,
      "count_targeted": 16962,
      "count_rejected": 154,
      "count_sent": 16468,
      "mailbox_provider_region": "APAC - Taiwan"
    },
    {
      "count_injected": 7511,
      "count_targeted": 7576,
      "count_rejected": 65,
      "count_sent": 7534,
      "mailbox_provider_region": "Europe - Sweden"
    }
  ]
}

Metrics by Mailbox Provider Region

GET/api/v1/metrics/deliverability/mailbox-provider-region{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone,limit,order_by}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum, default is 1min

Possible Values: 1min, 5min, 15min, hour, day

metrics list required

Delimited list of metrics for filtering.

timezone string, default is UTC

Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

order_by string

Metric by which to order results.

Provides aggregate metrics grouped by mailbox provider region over the time window specified.

Request

GET /api/v1/metrics/deliverability/time-series?from=2020-10-04T00:00&domains=gmail.com&campaigns=summerSale&ip_pools=ip-pool-1&precision=day&timezone=America/New_York

Response

{
  "results": [
    {
      "count_accepted": 217489,
      "count_admin_bounce": 295,
      "count_block_bounce": 16789,
      "count_bounce": 24176,
      "count_clicked": 16319,
      "count_delayed": 61224,
      "count_delayed_first": 5115,
      "count_delivered": 219916,
      "count_delivered_first": 18171,
      "count_delivered_subsequent": 201745,
      "count_generation_failed": 609,
      "count_generation_rejection": 635,
      "count_hard_bounce": 4296,
      "count_inband_bounce": 21777,
      "count_initial_rendered": 139690,
      "count_nonprefetched_initial_rendered": 77213,
      "count_injected": 246682,
      "count_outofband_bounce": 2399,
      "count_policy_rejection": 1072,
      "count_rejected": 2316,
      "count_rendered": 128385,
      "count_nonprefetched_rendered": 64192,
      "count_sent": 241693,
      "count_soft_bounce": 1961,
      "count_spam_complaint": 3,
      "count_targeted": 248998,
      "count_undetermined_bounce": 1130,
      "count_unique_clicked": 9123,
      "count_unique_confirmed_opened": 81140,
      "count_unique_initial_rendered": 81140,
      "count_nonprefetched_unique_initial_rendered": 40970,
      "count_unique_rendered": 69643,
      "count_nonprefetched_unique_rendered": 33512,
      "count_unsubscribe": 1,
      "total_delivery_time_first": 90854824,
      "total_delivery_time_subsequent": 1008767467,
      "total_msg_volume": 1111464137,
      "ts": "2020-10-04T00:00:00-04:00"
    },
    {
      "count_accepted": 143977,
      "count_admin_bounce": 202,
      "count_block_bounce": 11176,
      "count_bounce": 16120,
      "count_clicked": 10687,
      "count_delayed": 40527,
      "count_delayed_first": 3499,
      "count_delivered": 145617,
      "count_delivered_first": 12169,
      "count_delivered_subsequent": 133448,
      "count_generation_failed": 404,
      "count_generation_rejection": 417,
      "count_hard_bounce": 2817,
      "count_inband_bounce": 14501,
      "count_initial_rendered": 92769,
      "count_nonprefetched_initial_rendered": 45612,
      "count_injected": 163372,
      "count_outofband_bounce": 1619,
      "count_policy_rejection": 728,
      "count_rejected": 1549,
      "count_rendered": 85483,
      "count_nonprefetched_rendered": 42741,
      "count_sent": 160118,
      "count_soft_bounce": 1357,
      "count_spam_complaint": 2,
      "count_targeted": 164921,
      "count_undetermined_bounce": 770,
      "count_unique_clicked": 5999,
      "count_unique_confirmed_opened": 55592,
      "count_unique_initial_rendered": 55592,
      "count_nonprefetched_unique_initial_rendered": 26913,
      "count_unique_rendered": 48206,
      "count_nonprefetched_unique_rendered": 25712,
      "count_unsubscribe": 3,
      "total_delivery_time_first": 60928506,
      "total_delivery_time_subsequent": 665233402,
      "total_msg_volume": 736088556,
      "ts": "2020-10-05T00:00:00-04:00"
    }
  ]
}

Time-Series Metrics

GET/api/v1/metrics/deliverability/time-series{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,precision,metrics,timezone}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains string

Delimited list of domains for filtering.

campaigns list

Delimited list of campaigns for filtering.

subject_campaigns list

Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

precision enum

Precision of timeseries data returned. Precisions day, week, and month will return data in the UTC timezone regardless of the specified timezone.

Possible Values: 1min, 5min, 15min, hour, 12hr, day, week, month

metrics list required

Delimited list of metrics for filtering.

Possible Values: count_injected, count_bounce, count_rejected, count_delivered, count_delivered_first, count_delivered_subsequent, total_delivery_time_first, total_delivery_time_subsequent, total_msg_volume, count_policy_rejection, count_generation_rejection, count_generation_failed, count_inband_bounce, count_initial_rendered, count_nonprefetched_initial_rendered, count_outofband_bounce, count_soft_bounce, count_hard_bounce, count_block_bounce, count_admin_bounce, count_undetermined_bounce, count_delayed, count_delayed_first, count_rendered, count_nonprefetched_rendered, count_unique_rendered, count_nonprefetched_unique_rendered, count_unique_confirmed_opened, count_nonprefetched_unique_confirmed_opened, count_unique_initial_rendered, count_nonprefetched_unique_initial_rendered, count_clicked, count_unique_clicked, count_targeted, count_sent, count_accepted, count_spam_complaint, count_inbox_panel, count_spam_panel, count_inbox_seed, count_spam_seed, count_inbox_seed_private, count_spam_seed_private, count_inbox_seed_virtual, count_spam_seed_virtual, count_moved_to_inbox, count_moved_to_spam

timezone string, default is UTC

Standard timezone identification string. Precisions day, week, and month will return data in the UTC timezone regardless of the specified timezone.

Provides aggregate metrics ordered by a precision of time.

Request

GET /api/v1/metrics/deliverability/bounce-reason?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "reason": "Some Fake Reason",
      "bounce_class_name": "Undetermined",
      "bounce_class_description": "The response text could not be identified",
      "bounce_category_id": 0,
      "bounce_category_name": "Undetermined",
      "classification_id": 1,
      "count_inband_bounce": 119,
      "count_outofband_bounce": 118,
      "count_bounce": 237
    },
    {
      "reason": "Some Fake Reason",
      "bounce_class_name": "Invalid Recipient",
      "bounce_class_description": "The recipient is invalid",
      "bounce_category_id": 1,
      "bounce_category_name": "Hard",
      "classification_id": 10,
      "count_inband_bounce": 133,
      "count_outofband_bounce": 126,
      "count_bounce": 259
    }
  ]
}

Bounce Reason Metrics

GET/api/v1/metrics/deliverability/bounce-reason{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,metrics,timezone,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

metrics list required

Delimited list of metrics to include.

Possible Values: count_bounce, count_inband_bounce, count_outofband_bounce, count_admin_bounce

timezone string, default is UTC

Standard timezone identification string.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

Provides aggregate metrics, specific to bounce events, grouped by the bounce reasons.

Request

GET /api/v1/metrics/deliverability/bounce-reason/domain?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "reason": "Some Fake Reason",
      "domain": "example.com",
      "bounce_class_name": "Undetermined",
      "bounce_class_description": "The response text could not be identified",
      "bounce_category_id": 0,
      "bounce_category_name": "Undetermined",
      "classification_id": 1,
      "count_inband_bounce": 119,
      "count_outofband_bounce": 118,
      "count_bounce": 237
    },
    {
      "reason": "Some Fake Reason",
      "domain": "aol.com",
      "bounce_class_name": "Invalid Recipient",
      "bounce_class_description": "The recipient is invalid",
      "bounce_category_id": 1,
      "bounce_category_name": "Hard",
      "classification_id": 10,
      "count_inband_bounce": 133,
      "count_outofband_bounce": 126,
      "count_bounce": 259
    }
  ]
}

Bounce Reason Metrics By Domain

GET/api/v1/metrics/deliverability/bounce-reason/domain{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,metrics,timezone,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

metrics list required

Delimited list of metrics to include.

Possible Values: count_bounce, count_inband_bounce, count_outofband_bounce, count_admin_bounce

timezone string, default is UTC

Standard timezone identification string.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

Provides aggregate metrics, specific to bounce events, grouped by the domain and bounce reasons.

Request

GET /api/v1/metrics/deliverability/bounce-classification?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "bounce_class_name": "Undetermined",
      "bounce_class_description": "The response text could not be identified",
      "bounce_category_name": "Undetermined",
      "count_bounce": 226,
      "count_inband_bounce": 205,
      "count_outofband_bounce": 21,
      "classification_id": 1
    },
    {
      "bounce_class_name": "Invalid Recipient",
      "bounce_class_description": "The recipient is invalid",
      "bounce_category_name": "Hard",
      "count_bounce": 249,
      "count_inband_bounce": 224,
      "count_outofband_bounce": 25,
      "classification_id": 10
    }
  ]
}

Bounce Classification Metrics

GET/api/v1/metrics/deliverability/bounce-classification{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,metrics,timezone,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

timezone string, default is UTC

Standard timezone identification string.

metrics list required

Delimited list of metrics to include.

Possible Values: count_bounce, count_inband_bounce, count_outofband_bounce, count_admin_bounce

limit int

Maximum number of results to return.

Provides aggregate metrics, specific to bounce events, grouped by the bounce classification. (See Bounce Classification Codes.)

Request

GET /api/v1/metrics/deliverability/rejection-reason?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "reason": "520 rejection message",
      "count_rejected": 30,
      "rejection_category_id": 2,
      "rejection_type": "Generation Rejection"
    },
    {
      "reason": "503 rejection message",
      "count_rejected": 24,
      "rejection_category_id": 1,
      "rejection_type": "Policy Rejection"
    }
  ]
}

Rejection Reason Metrics

GET/api/v1/metrics/deliverability/rejection-reason{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,timezone,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

timezone string, default is UTC

Standard timezone identification string.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

Provides aggregate metrics, specific to rejection events, grouped by the rejection reasons.

Request

GET /api/v1/metrics/deliverability/rejection-reason/domain?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "reason": "520 rejection message",
      "domain": "example.com",
      "count_rejected": 30,
      "rejection_category_id": 2,
      "rejection_type": "Generation Rejection"
    },
    {
      "reason": "503 rejection message",
      "domain": "aol.com",
      "count_rejected": 24,
      "rejection_category_id": 1,
      "rejection_type": "Policy Rejection"
    }
  ]
}

Rejection Reason Metrics By Domain

GET/api/v1/metrics/deliverability/rejection-reason/domain{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,timezone,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

timezone string, default is UTC

Standard timezone identification string.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

Provides aggregate metrics, specific to rejection events, grouped by the domain and rejection reasons.

Request

GET /api/v1/metrics/deliverability/delay-reason?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "reason": "400 fake tempfail reason",
      "count_delayed": 200,
      "count_delayed_first": 100
    },
    {
      "reason": "425 fake tempfail reason",
      "count_delayed": 100,
      "count_delayed_first": 50
    }
  ]
}

Delay Reason Metrics

GET/api/v1/metrics/deliverability/delay-reason{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,timezone,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

timezone string, default is UTC

Standard timezone identification string.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

Provides aggregate metrics, specific to delay events, grouped by the delay reasons.

Request

GET /api/v1/metrics/deliverability/delay-reason/domain?from=2018-07-11T08:00&limit=5

Response

{
  "results": [
    {
      "reason": "400 fake tempfail reason",
      "domain": "example.com",
      "count_delayed": 200,
      "count_delayed_first": 100
    },
    {
      "reason": "425 fake tempfail reason",
      "domain": "aol.com",
      "count_delayed": 100,
      "count_delayed_first": 50
    }
  ]
}

Delay Reason Metrics By Domain

GET/api/v1/metrics/deliverability/delay-reason/domain{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,timezone,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

timezone string, default is UTC

Standard timezone identification string.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

Provides aggregagte metrics, specific to delay events, grouped by the domain and delay reasons.

Request

GET /api/v1/metrics/deliverability/link-name?from=2014-07-11T09:00&metrics=count_clicked&limit=5

Response

{
  "results": [
    {
      "link_name": "top banner link",
      "count_clicked": 123,
      "count_raw_clicked": 456
    },
    {
      "link_name": "Raw URL",
      "count_clicked": 123,
      "count_raw_clicked": 456
    }
  ]
}

Engagement Details

GET/api/v1/metrics/deliverability/link-name{?from,to,delimiter,timezone,campaigns,templates,subaccounts,sending_domains,metrics,limit}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

timezone string, default is UTC

Standard timezone identification string.

metrics list required

Delimited list of metrics to include.

Possible Values: count_clicked, count_raw_clicked

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

limit int

Maximum number of results to return between 1 and 10000, inclusive.

Provides deliverability metrics, specific to engagement events (clicks/opens), grouped by the link name (or URL if no link name exists). To name the links in your messages, read about the data-msys-link-name HTML attribute here.

Request

GET /api/v1/metrics/deliverability/attempt?from=2018-07-11T08:00

Response

{
  "results": [
    {
      "attempt": "1",
      "count_delivered": 100
    },
    {
      "attempt": "2",
      "count_delivered": 150
    }
  ]
}

Deliveries By Attempt

GET/api/v1/metrics/deliverability/attempt{?from,to,delimiter,domains,campaigns,templates,sending_ips,ip_pools,sending_domains,subaccounts,timezone}

Parameters

from datetime required

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

to datetime

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

delimiter string, default is ,

Specifies the delimiter for query parameter lists.

query_filters string

An advanced query structure. See Advanced Filters.

domains list

Delimited list of recipient domains to include.

campaigns list

Delimited list of campaigns to include.

mailbox_providers list

Delimited list of mailbox providers to include.

mailbox_provider_regions list

Delimited list of mailbox provider regions to include.

templates list

Delimited list of template IDs to include.

sending_ips list

Delimited list of sending IPs to include.

ip_pools list

Delimited list of IP pools to include.

sending_domains list

Delimited list of sending domains to include.

subaccounts list

Delimited list of subaccount IDs to include.

timezone string, default is UTC

Standard timezone identification string.

Provides aggregate count of deliveries grouped by the attempt number. This endpoint supports at most 3 entries in the results Array, attempts: 1, attempts: 2, and attempts: 3+.

Lists

Each of the the following endpoints returns a list of their resources for which we have metrics. These help you get an overview of what metrics are available to you.

Request

GET /api/v1/metrics/ip-pools?from=2017-12-01T08:00&to=2017-12-01T09:00&limit=5

Response

{
  "results": {
    "ip-pools": [
      "ip-pool-1",
      "ip-pool-2",
      "ip-pool-3",
      "ip-pool-4",
      "ip-pool-5"
    ]
  }
}

IP Pools

GET/api/v1/metrics/ip-pools{?from,to,timezone,match,limit}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of IP pools that the Metrics API contains data on.

Request

GET /api/v1/metrics/sending-ips?from=2017-12-01T08:00&to=2017-12-01T09:00&limit=5

Response

{
  "results": {
    "sending-ips": [
      "sending-ip-1",
      "sending-ip-2",
      "sending-ip-3",
      "sending-ip-4",
      "sending-ip-5"
    ]
  }
}

Sending IPs

GET/api/v1/metrics/sending-ips{?from,to,timezone,match,limit}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of sending IPs that the Metrics API contains data on.

Request

GET /api/v1/metrics/mailbox-provider-regions?from=2017-12-01T08:00&to=2017-12-01T09:00&limit=5

Response

{
  "results": {
    "mailbox-provider-regions": [
      "mailbox-provider-region-1",
      "mailbox-provider-region-2",
      "mailbox-provider-region-3",
      "mailbox-provider-region-4",
      "mailbox-provider-region-5"
    ]
  }
}

Mailbox Provider Regions

GET/api/v1/metrics/mailbox-provider-regions{?from,to,timezone,match,limit}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of mailbox provider regions that the Metrics API contains data on.

Request

GET /api/v1/metrics/mailbox-providers?from=2017-12-01T08:00&to=2017-12-01T09:00&limit=5

Response

{
  "results": {
    "mailbox-providers": [
      "Hushmail",
      "Kinghost",
      "La Poste",
      "Mail.com",
      "Mailbird"
    ]
  }
}

Mailbox Providers

GET/api/v1/metrics/mailbox-providers{?from,to,timezone,match,limit}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of mailbox providers that the Metrics API contains data on.

Request

GET /api/v1/metrics/campaigns?from=2017-12-01T08:00&to=2017-12-01T09:00&limit

Response

{
  "results": {
    "campaigns": [
      "Labor Day Sale",
      "New Year's Sale",
      "Founder's Day Event",
      "Winter Event",
      "Promotion X"
    ]
  }
}

Campaigns

GET/api/v1/metrics/campaigns{?from,to,timezone,limit,match}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of campaigns that the Metrics API contains data on.

Request

GET /api/v1/metrics/templates?from=2017-12-01T08:00&to=2017-12-01T09:00&limit

Response

{
  "results": {
    "templates": [
      "labor-day-sale",
      "inline",
      "welcome-user",
      "winter-event-001",
      "promotion-x"
    ]
  }
}

Templates

GET/api/v1/metrics/templates{?from,to,timezone,limit,match}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of templates that the Metrics API contains data on.

Request

GET /api/v1/metrics/domains?from=2017-12-01T08:00&to=2017-12-01T09:00&limit

Response

{
  "results": {
    "domains": [
      "gmail.com",
      "yahoo.com",
      "msn.com",
      "aol.com",
      "hotmail.com"
    ]
  }
}

Domains

GET/api/v1/metrics/domains{?from,to,timezone,limit,match}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of domains that the Metrics API contains data on.

Request

GET /api/v1/metrics/subject-campaigns?from=2017-12-01T08:00&to=2017-12-01T09:00&limit

Response

{
  "results": {
    "subject-campaigns": [
      "Hi there!",
      "Hi [REDACTED]",
      "exciting offers.",
      "[REDACTED] there!",
      "[REDACTED] offers.",
      "exciting [REDACTED]"
    ]
  }
}

Subject Campaigns

GET/api/v1/metrics/subject-campaigns{?from,to,timezone,limit,match}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of deliverability add-on subject campaigns that the Metrics API contains data on.

Request

GET /api/v1/metrics/sending-domains?from=2017-12-01T08:00&to=2017-12-01T09:00&limit

Response

{
  "results": {
    "sending-domains": [
      "example1.com",
      "example2.com",
      "example3.com"
    ]
  }
}

Sending Domains

GET/api/v1/metrics/sending-domains{?from,to,timezone,limit,match}

Parameters

match string

Only return results containing this string.

limit int

Maximum number of results to return.

from datetime

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

to datetime

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

timezone string, default is UTC

Standard timezone identification string.

Returns a list of sending domains that the Metrics API contains data on.

Industry Benchmarks

The industry benchmarks endpoints allow you to compare your performance to your industry.

Deliverability Add-On

Request

GET /api/v1/metrics/benchmarks/inbox-rate?from=2021-01-02T08:00&industry_category=all&mailbox_provider=gmail

Response

{
  "results": [
    {
      "median": 0.894,
      "q25": 0.6,
      "q75": 0.97,
      "ts": "2021-01-02T13:00:00.000Z"
    },
    {
      "median": 0.94,
      "q25": 0.86,
      "q75": 0.974,
      "ts": "2021-01-02T13:00:00.000Z"
    },
    {
      "median": 0.783,
      "q25": 0.446,
      "q75": 0.95,
      "ts": "2021-01-02T13:00:00.000Z"
    }
  ]
}

Inbox Rate

GET/api/v1/metrics/benchmarks/inbox-rate{?from,to,industry_category,mailbox_provider,timezone}

Parameters

from datetime required

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

to datetime

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

industry_category string, default is all

The industry category for which you will receive benchmarks.

Possible Values: all, automotive, b2b, cpg, entertainment, finance, food_beverage_service, govt_education_charity, job_search, media_publishing, medical, misc, personal_services, retail_apparel, retail_online, retail_other, retail_supermarket_drug, social_review, telco, travel

mailbox_provider string, default is all

The mailbox provider for which you will receive benchmarks.

Possible Values: all, gmail, hotmail, verizon_media_group

timezone string, default is UTC

Standard timezone identification string.

Provides daily inbox rate industry benchmarks of 25th, 50th (median), and 75th percentile.

Note: The Inbox Rate Industry Benchmark endpoint is available to the SparkPost Deliverability Add-On customers only.