Metrics

Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.

This reporting data is available in the "Insights" page (under the "Developer" / "Channels" / "Email" section) in the app 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 Reach Email as well as rejected by it
count_injected	Messages injected to or received by Reach Email
count_sent	Messages that Reach Email 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 Reach Email due to policy
count_generation_failed	Message generation failed for an intended recipient
count_generation_rejection	Messages rejected by Reach Email 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 Reach Email Deliverability Add-On customers.

Note: 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 bird.com or example.org with the following query string:?sending_domains=bird.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": [ "bird.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": [ "bird.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%22bird.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

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.

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.

Industry Benchmarks

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

Advanced Query JSON Schema

get

Retrieves the JSON schema for validating the query_filters JSON value.

Authorizations

Responses

200

Successfully retrieved query filters schema

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/query-filters-schema HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved query filters schema

{
  "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": {}
    }
  }
}

Discoverability Links

get

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.

Authorizations

Responses

200

Successfully retrieved discoverability links

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/ HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved discoverability links

{
  "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"
    }
  ]
}

Aggregations - Metrics Summary

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies an alternate delimiter for all included query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

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

Aggregations - Metrics by Recipient Domain

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

Default: 1000

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/domain HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "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
    }
  ]
}

Aggregations - Metrics by Sending IP

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/sending-ip HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "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
    }
  ]
}

Aggregations - Metrics by IP Pool

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/ip-pool HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "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
    }
  ]
}

Aggregations - Metrics by Sending Domain

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/sending-domain HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "results": [
    {
      "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",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Aggregations - Metrics by Subaccount

get

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.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/subaccount HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "results": [
    {
      "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,
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Aggregations - Metrics by Campaign

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/campaign HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "results": [
    {
      "campaign_id": "christmas_campaign",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "campaign_id": "new_year_sale",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Aggregations - Metrics by Template

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/template HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "results": [
    {
      "template_id": "welcome_email",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "template_id": "password_reset",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Aggregations - Metrics by Subject Campaign

get

Provides aggregate metrics grouped by subject campaign over the time window specified. This endpoint supports deliverability add-on metrics only (Deliverability Add-On).

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/subject-campaign HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "results": [
    {
      "subject_campaign": "summer_sale_2024",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "subject_campaign": "winter_promotion_2024",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Aggregations - Metrics by Watched Domain

get

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.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/watched-domain HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "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
    }
  ]
}

Aggregations - Metrics by Mailbox Provider

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

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

Aggregations - Metrics by Mailbox Provider Region

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

Precision of the time window (from and 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 the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

order_bystringOptional

Metric by which to order results

Responses

200

Successfully retrieved metrics

application/json

400

Request validation error

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider-region HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "results": [
    {
      "mailbox_provider_region": "us-east",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    },
    {
      "mailbox_provider_region": "eu-west",
      "count_targeted": 34432,
      "count_injected": 32323,
      "count_rejected": 2343,
      "count_sent": 34344
    }
  ]
}

Aggregations - Time-Series Metrics

get

Provides aggregate metrics ordered by a precision of time.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Datetime in format of YYYY-MM-DDTHH:MM

tostring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of domains for filtering

campaignsstringOptional

Delimited list of campaigns for filtering

subject_campaignsstringOptional

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

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

precisionstring · enumOptional

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

Default: dayPossible values:

metricsstringRequired

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.

timezonestringOptional

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

Default: UTC

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/time-series HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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"
    }
  ]
}

Aggregations - Bounce Reason Metrics

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

metricsstringRequired

Delimited list of metrics for filtering.

Possible Values: count_bounce, count_inband_bounce, count_outofband_bounce, count_admin_bounce

timezonestringOptional

Standard timezone identification string

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

Default: 1000

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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
    }
  ]
}

Aggregations - Bounce Reason Metrics By Domain

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

metricsstringRequired

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.

timezonestringOptional

Standard timezone identification string

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

Default: 5

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason/domain HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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
    }
  ]
}

Aggregations - Bounce Classification Metrics

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

metricsstringRequired

Delimited list of metrics for filtering.

Possible Values: count_bounce, count_inband_bounce, count_outofband_bounce, count_admin_bounce

timezonestringOptional

Standard timezone identification string

Default: UTC

limitintegerOptional

Maximum number of results to return

Default: 5

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-classification HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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
    }
  ]
}

Aggregations - Rejection Reason Metrics

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

timezonestringOptional

Standard timezone identification string

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

Default: 5

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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"
    }
  ]
}

Aggregations - Rejection Reason Metrics By Domain

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

timezonestringOptional

Standard timezone identification string

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

Default: 5

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason/domain HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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"
    }
  ]
}

Aggregations - Delay Reason Metrics

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

timezonestringOptional

Standard timezone identification string

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

Default: 5

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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
    }
  ]
}

Aggregations - Delay Reason Metrics By Domain

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

timezonestringOptional

Standard timezone identification string

Default: UTC

limitinteger · min: 1 · max: 10000Optional

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

Default: 5

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason/domain HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

{
  "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
    }
  ]
}

Aggregations - Engagement Details

get

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.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

timezonestringOptional

Standard timezone identification string

Default: UTC

metricsstringRequired

Delimited list of metrics for filtering.

Possible Values: count_clicked, count_raw_clicked.

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

limitinteger · min: 1 · max: 10000Optional

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

Default: 5

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/link-name HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

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

Aggregations - Deliveries By Attempt

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

query_filtersobjectOptional

An advanced query structure. See the Advanced Filters section.

domainsstringOptional

Delimited list of recipient domains to include

campaignsstringOptional

Delimited list of campaigns to include

mailbox_providersstringOptional

Delimited list of mailbox providers to include

mailbox_provider_regionsstringOptional

Delimited list of mailbox provider regions to include

templatesstringOptional

Delimited list of template IDs to include

sending_ipsstringOptional

Delimited list of sending IPs to include

ip_poolsstringOptional

Delimited list of IP pools to include

sending_domainsstringOptional

Delimited list of sending domains to include

subaccountsstringOptional

Delimited list of subaccount IDs to include

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved metrics

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/attempt HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved metrics

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

Lists - IP Pools

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved IP pools

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/ip-pools HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved IP pools

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

Lists - Sending IPs

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

Example: 2017-12-01T08:00

tostring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

Example: 2017-12-01T09:00

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved sending IPs

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/sending-ips HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved sending IPs

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

Lists - Mailbox Provider Regions

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved mailbox provider regions

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/mailbox-provider-regions HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved mailbox provider regions

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

Lists - Mailbox Providers

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

Example: 2017-12-01T08:00

tostring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

Example: 2017-12-01T09:00

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved mailbox providers

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/mailbox-providers HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved mailbox providers

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

Lists - Campaigns

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

tostring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved campaigns

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/campaigns HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved campaigns

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

Lists - Templates

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

Example: 2017-12-01T08:00

tostring · date-timeOptional

Datetime in format of YYYY-MM-DDTHH:MM

Example: 2017-12-01T09:00

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved templates

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/templates HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved templates

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

Lists - Domains

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved domains

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/domains HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved domains

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

Lists - Subject Campaigns

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string

limitintegerOptional

Maximum number of results to return

Default: 5

fromstring · date-timeOptional

Start datetime (YYYY-MM-DDTHH:MM)

Example: 2017-12-01T08:00

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

Example: 2017-12-01T09:00

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved subject campaigns

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/subject-campaigns HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved subject campaigns

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

Lists - Sending Domains

get

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

matchstringOptional

Only return results containing this string.

limitintegerOptional

Maximum number of results to return.

Default: 5

fromstring · date-timeOptional

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

tostring · date-timeOptional

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

Default: now

timezonestringOptional

Standard timezone identification string.

Default: UTC

Responses

200

Successfully retrieved sending domains

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/sending-domains HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved sending domains

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

Industry Benchmarks - Inbox Rate

get

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

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

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeRequired

Start datetime (YYYY-MM-DDTHH:MM)

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM)

industry_categorystring · enumOptional

The industry category for which you will receive benchmarks

Default: allPossible values:

mailbox_providerstring · enumOptional

The mailbox provider for which you will receive benchmarks

Default: allPossible values:

timezonestringOptional

Standard timezone identification string

Default: UTC

Responses

200

Successfully retrieved inbox rate benchmarks

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/metrics/benchmarks/inbox-rate HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved inbox rate benchmarks

{
  "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"
    }
  ]
}