Metrics

Run in Postman
Import the SparkPost API as a Postman collection

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

TermDefinition
count_targetedMessages successfully injected into SparkPost as well as rejected by it
count_injectedMessages injected to or received by SparkPost
count_sentMessages that SparkPost attempted to deliver, which includes both Deliveries and Bounces
count_acceptedMessages an ISP or other remote domain accepted (less Out-of-Band Bounces)
count_deliveredMessages delivered
count_delivered_firstMessages delivered on the first attempt
count_delivered_subsequentMessages delivered that required more than one delivery attempt
count_renderedTotal renderings of a message
count_nonprefetched_renderedTotal non-prefetched renderings of a message
count_initial_renderedTotal initial renderings of a message
count_nonprefetched_initial_renderedTotal initial non-prefetched renderings of a message
count_unique_renderedTotal number of messages that were rendered at least once
count_nonprefetched_unique_renderedTotal number of non-prefetched messages that were rendered at least once
count_unique_initial_renderedTotal number of messages that were initally rendered at least once
count_nonprefetched_unique_initial_renderedTotal number of non-prefetched messages that were initally rendered at least once
count_unique_confirmed_openedTotal number of messages that were rendered or had at least one link selected
count_nonprefetched_unique_confirmed_openedTotal number of non-prefetched messages that were rendered or had at least one link selected
count_clickedTotal number of times that links were selected across all messages
count_unique_clickedTotal number of messages which had at least one link selected one or more times
count_bounceTotal number of bounced messages, which includes both In-Band and Out-of-Band bounces
count_hard_bounceTotal number of Bounced messages due to hard bounce classification reasons
count_soft_bounceTotal number of Bounced messages due to soft bounce classification reasons
count_block_bounceTotal number of Bounced messages due to an IP block
count_admin_bounceTotal number of Bounced messages due to admin bounce classification reasons, also includes Rejected
count_undetermined_bounceTotal number of Bounced messages due to undetermined bounce reasons
count_rejectedMessages rejected due to policy or that failed to generate
count_policy_rejectionMessages rejected by SparkPost due to policy
count_generation_failedMessage generation failed for an intended recipient
count_generation_rejectionMessages rejected by SparkPost due to policy
count_inband_bounceMessages that bounced on delivery attempt during the SMTP session
count_outofband_bounceMessages that the ISP bounced subsequent to a successful delivery
count_delayedTotal number of delays due to any temporary failure
count_delayed_firstMessages delayed on the first delivery attempt
total_msg_volumeTotal size of delivered messages, in bytes (including attachments)
count_spam_complaintNumber of spam complaints received from an ISP
total_delivery_time_firstTotal time taken to deliver messages on first attempt (milliseconds)
total_delivery_time_subsequentTotal time taken to delivery messages on subsequent attempts (milliseconds)
count_unsubscribeTotal number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature
count_inbox_panelDeliverability Add-On Panel messages delivered to the inbox.
count_spam_panelDeliverability Add-On Panel messages delivered to the spam folder.
count_inbox_seedDeliverability Add-On All Seed messages delivered to the inbox.
count_spam_seedDeliverability Add-On All Seed messages delivered to the spam folder.
count_inbox_seed_privateDeliverability Add-On Private Seed messages delivered to the inbox.
count_spam_seed_privateDeliverability Add-On Private Seed messages delivered to the spam folder.
count_inbox_seed_virtualDeliverability Add-On Virtual Seed messages delivered to the inbox.
count_spam_seed_virtualDeliverability Add-On Virtual Seed messages delivered to the spam folder.
count_moved_to_inboxDeliverability Add-On Panel messages delivered to the spam folder then moved to the inbox.
count_moved_to_spamDeliverability 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.

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:

PrecisionRounded time windowMax time window
1min04:22:00 - 06:36:5924 hours
5min04:20:00 - 06:39:5924 hours
15min04:15:00 - 06:44:5948 hours
hour04:00:00 - 06:59:5931 days
day00:00:00 - 23:59:59No 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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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. 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

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.

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

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.

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

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.

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.