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.

Regional Endpoints

Please use the appropriate API endpoint based on your workspace region:

EU workspaces: https://email.eu-west-1.api.bird.com
US workspaces: https://email.us-west-2.api.bird.com

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
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" ]
        }
      }
    },
    {
      "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%22campaigns%22%3A%7B%22like%22%3A%5B%22333%22%2C%22344%22%2C%22355%22%5D%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 campaign. 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

/workspaces/{workspaceId}/reach/metrics/deliverability/query-filters-schema

Retrieves the JSON schema for validating the query_filters JSON value.

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Responses

200

Successfully retrieved query filters schema

application/json

get

/workspaces/{workspaceId}/reach/metrics/deliverability/query-filters-schema

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

/workspaces/{workspaceId}/reach/metrics/

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Responses

200

Successfully retrieved discoverability links

application/json

get

/workspaces/{workspaceId}/reach/metrics/

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

/workspaces/{workspaceId}/reach/metrics/deliverability

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

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/domain

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/domain

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/domain?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/sending-ip

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/sending-ip

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/sending-ip?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/ip-pool

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/ip-pool

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/ip-pool?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/sending-domain

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/sending-domain

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/sending-domain?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/subaccount

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

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/subaccount

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/subaccount?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/campaign

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/campaign

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/campaign?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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 Subject Campaign

get

/workspaces/{workspaceId}/reach/metrics/deliverability/subject-campaign

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/subject-campaign

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/subject-campaign?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/watched-domain

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

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/watched-domain

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/watched-domain?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider-region

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

See the Precision Parameter section for more information.

Default: 1minPossible values:

metricsstringRequired

Delimited list of metrics for filtering.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider-region

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider-region?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/time-series

Provides aggregate metrics ordered by a precision of time.

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/time-series

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/time-series?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason/domain

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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.

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

/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason/domain

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason/domain?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-classification

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-classification

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-classification?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason?from=2026-02-17T13%3A20%3A13.444Z 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

/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason/domain

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason/domain

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason/domain?from=2026-02-17T13%3A20%3A13.444Z 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

/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason?from=2026-02-17T13%3A20%3A13.444Z 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

/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason/domain

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason/domain

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason/domain?from=2026-02-17T13%3A20%3A13.444Z 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

/workspaces/{workspaceId}/reach/metrics/deliverability/link-name

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

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/link-name

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/link-name?from=2026-02-17T13%3A20%3A13.444Z&metrics=text 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

/workspaces/{workspaceId}/reach/metrics/deliverability/attempt

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

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

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

/workspaces/{workspaceId}/reach/metrics/deliverability/attempt

GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/attempt?from=2026-02-17T13%3A20%3A13.444Z 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

/workspaces/{workspaceId}/reach/metrics/ip-pools

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/ip-pools

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

/workspaces/{workspaceId}/reach/metrics/sending-ips

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/sending-ips

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

/workspaces/{workspaceId}/reach/metrics/mailbox-provider-regions

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/mailbox-provider-regions

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

/workspaces/{workspaceId}/reach/metrics/mailbox-providers

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/mailbox-providers

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

/workspaces/{workspaceId}/reach/metrics/campaigns

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/campaigns

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

get

/workspaces/{workspaceId}/reach/metrics/domains

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/domains

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

/workspaces/{workspaceId}/reach/metrics/subject-campaigns

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/subject-campaigns

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

/workspaces/{workspaceId}/reach/metrics/sending-domains

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

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/sending-domains

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

/workspaces/{workspaceId}/reach/metrics/benchmarks/inbox-rate

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

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/metrics/benchmarks/inbox-rate

GET /api/workspaces/{workspaceId}/reach/metrics/benchmarks/inbox-rate?from=2026-02-17T13%3A20%3A13.444Z 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"
    }
  ]
}

Last updated 3 months ago

Was this helpful?

hashtagRegional Endpoints

hashtagData retention

hashtagTerminology

hashtagPrecision Parameter

hashtagTime-series Metrics

hashtagFilters

hashtagSimple Filters

hashtagAdvanced Filters

hashtagAggregations

hashtagLists

hashtagIndustry Benchmarks

hashtagAdvanced Query JSON Schema

hashtagDiscoverability Links

hashtagAggregations - Metrics Summary

hashtagAggregations - Metrics by Recipient Domain

hashtagAggregations - Metrics by Sending IP

hashtagAggregations - Metrics by IP Pool

hashtagAggregations - Metrics by Sending Domain

hashtagAggregations - Metrics by Subaccount

hashtagAggregations - Metrics by Campaign

hashtagAggregations - Metrics by Subject Campaign

hashtagAggregations - Metrics by Watched Domain

hashtagAggregations - Metrics by Mailbox Provider

hashtagAggregations - Metrics by Mailbox Provider Region

hashtagAggregations - Time-Series Metrics

hashtagAggregations - Bounce Reason Metrics

hashtagAggregations - Bounce Reason Metrics By Domain

hashtagAggregations - Bounce Classification Metrics

hashtagAggregations - Rejection Reason Metrics

hashtagAggregations - Rejection Reason Metrics By Domain

hashtagAggregations - Delay Reason Metrics

hashtagAggregations - Delay Reason Metrics By Domain

hashtagAggregations - Engagement Details

hashtagAggregations - Deliveries By Attempt

hashtagLists - IP Pools

hashtagLists - Sending IPs

hashtagLists - Mailbox Provider Regions

hashtagLists - Mailbox Providers

hashtagLists - Campaigns

hashtagLists - Domains

hashtagLists - Subject Campaigns

hashtagLists - Sending Domains

hashtagIndustry Benchmarks - Inbox Rate

Regional Endpoints

Data retention

Terminology

Precision Parameter

Time-series Metrics

Filters

Simple Filters

Advanced Filters

Aggregations

Lists

Industry Benchmarks

Advanced Query JSON Schema

Discoverability Links

Aggregations - Metrics Summary

Aggregations - Metrics by Recipient Domain

Aggregations - Metrics by Sending IP

Aggregations - Metrics by IP Pool

Aggregations - Metrics by Sending Domain

Aggregations - Metrics by Subaccount

Aggregations - Metrics by Campaign

Aggregations - Metrics by Subject Campaign

Aggregations - Metrics by Watched Domain

Aggregations - Metrics by Mailbox Provider

Aggregations - Metrics by Mailbox Provider Region

Aggregations - Time-Series Metrics

Aggregations - Bounce Reason Metrics

Aggregations - Bounce Reason Metrics By Domain

Aggregations - Bounce Classification Metrics

Aggregations - Rejection Reason Metrics

Aggregations - Rejection Reason Metrics By Domain

Aggregations - Delay Reason Metrics

Aggregations - Delay Reason Metrics By Domain

Aggregations - Engagement Details

Aggregations - Deliveries By Attempt

Lists - IP Pools

Lists - Sending IPs

Lists - Mailbox Provider Regions

Lists - Mailbox Providers

Lists - Campaigns

Lists - Domains

Lists - Subject Campaigns

Lists - Sending Domains

Industry Benchmarks - Inbox Rate