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
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:
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
domainssending_ipsip_poolscampaignssubject_campaignstemplatessending_domainsmailbox_providerssubaccountsmailbox_provider_regions
Comparator Keywords
eq- array of exact values to matchlike- array of substrings to match on; values must be at least 3 characters longnotEq- array of exact values to NOT matchnotLike- 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%7DAggregations
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.
Retrieves the JSON schema for validating the query_filters JSON value.
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: */*
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": {}
}
}
}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.
GET /api/workspaces/{workspaceId}/reach/metrics/ HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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"
}
]
}Provides high-level summary of aggregate metrics and lists the child endpoints that contain aggregate data, which can be used as "group by" qualifiers.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies an alternate delimiter for all included query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCGET /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"
}
]
}Provides aggregate metrics grouped by domain over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
1000Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by sending IP over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by IP pool over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by sending domain over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}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.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by campaign over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by template over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by subject campaign over the time window specified. This endpoint supports deliverability add-on metrics only (Deliverability Add-On).
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}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.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by mailbox provider over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics grouped by mailbox provider region over the time window specified.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of subject campaigns to include. Supports deliverability add-on metrics only (Deliverability Add-On)
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
1minPossible values: 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.
Standard timezone identification string. The day precision will return data in UTC regardless of the specified timezone
UTCMaximum number of results to return between 1 and 10000, inclusive
Metric by which to order results
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
}
]
}Provides aggregate metrics ordered by a precision of time.
The ID of the workspace
Datetime in format of YYYY-MM-DDTHH:MM
Datetime in format of YYYY-MM-DDTHH:MM
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of domains for filtering
Delimited list of campaigns for filtering
Deliverability Add-On Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Precision of timeseries data returned. Precisions day, week, and month will return data in the UTC timezone regardless of the specified timezone.
dayPossible values: 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.
Standard timezone identification string. Precisions day, week, and month will return data in the UTC timezone regardless of the specified timezone
UTCGET /api/workspaces/{workspaceId}/reach/metrics/deliverability/time-series HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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"
}
]
}Provides aggregate metrics, specific to bounce events, grouped by the bounce reasons.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Delimited list of metrics for filtering.
Possible Values: count_bounce, count_inband_bounce, count_outofband_bounce, count_admin_bounce
Standard timezone identification string
UTCMaximum number of results to return between 1 and 10000, inclusive
1000GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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
}
]
}Provides aggregate metrics, specific to bounce events, grouped by the domain and bounce reasons.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
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.
Standard timezone identification string
UTCMaximum number of results to return between 1 and 10000, inclusive
5GET /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: */*
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
}
]
}Provides aggregate metrics, specific to bounce events, grouped by the bounce classification. (See Bounce Classification Codes)
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Delimited list of metrics for filtering.
Possible Values: count_bounce, count_inband_bounce, count_outofband_bounce, count_admin_bounce
Standard timezone identification string
UTCMaximum number of results to return
5GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-classification HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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
}
]
}Provides aggregate metrics, specific to rejection events, grouped by the rejection reasons.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Standard timezone identification string
UTCMaximum number of results to return between 1 and 10000, inclusive
5GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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"
}
]
}Provides aggregate metrics, specific to rejection events, grouped by the domain and rejection reasons.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Standard timezone identification string
UTCMaximum number of results to return between 1 and 10000, inclusive
5GET /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: */*
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"
}
]
}Provides aggregate metrics, specific to delay events, grouped by the delay reasons.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Standard timezone identification string
UTCMaximum number of results to return between 1 and 10000, inclusive
5GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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
}
]
}Provides aggregagte metrics, specific to delay events, grouped by the domain and delay reasons.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Standard timezone identification string
UTCMaximum number of results to return between 1 and 10000, inclusive
5GET /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: */*
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
}
]
}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.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Standard timezone identification string
UTCDelimited list of metrics for filtering.
Possible Values: count_clicked, count_raw_clicked.
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Maximum number of results to return between 1 and 10000, inclusive
5GET /api/workspaces/{workspaceId}/reach/metrics/deliverability/link-name HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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
}
]
}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+.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Specifies the delimiter for query parameter lists
,An advanced query structure. See the Advanced Filters section.
Delimited list of recipient domains to include
Delimited list of campaigns to include
Delimited list of mailbox providers to include
Delimited list of mailbox provider regions to include
Delimited list of template IDs to include
Delimited list of sending IPs to include
Delimited list of IP pools to include
Delimited list of sending domains to include
Delimited list of subaccount IDs to include
Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/deliverability/attempt HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved metrics
{
"results": [
{
"attempt": "1",
"count_delivered": 100
},
{
"attempt": "2",
"count_delivered": 150
}
]
}Returns a list of IP pools that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/ip-pools HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved IP pools
{
"results": {
"ip-pools": [
"ip-pool-1",
"ip-pool-2",
"ip-pool-3",
"ip-pool-4",
"ip-pool-5"
]
}
}Returns a list of sending IPs that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Datetime in format of YYYY-MM-DDTHH:MM
2017-12-01T08:00Datetime in format of YYYY-MM-DDTHH:MM
2017-12-01T09:00Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/sending-ips HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved sending IPs
{
"results": {
"sending-ips": [
"sending-ip-1",
"sending-ip-2",
"sending-ip-3",
"sending-ip-4",
"sending-ip-5"
]
}
}Returns a list of mailbox provider regions that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/mailbox-provider-regions HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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"
]
}
}Returns a list of mailbox providers that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Datetime in format of YYYY-MM-DDTHH:MM
2017-12-01T08:00Datetime in format of YYYY-MM-DDTHH:MM
2017-12-01T09:00Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/mailbox-providers HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved mailbox providers
{
"results": {
"mailbox-providers": [
"Hushmail",
"Kinghost",
"La Poste",
"Mail.com",
"Mailbird"
]
}
}Returns a list of campaigns that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Datetime in format of YYYY-MM-DDTHH:MM
Datetime in format of YYYY-MM-DDTHH:MM
Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/campaigns HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved campaigns
{
"results": {
"campaigns": [
"Labor Day Sale",
"New Year's Sale",
"Founder's Day Event",
"Winter Event",
"Promotion X"
]
}
}Returns a list of templates that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Datetime in format of YYYY-MM-DDTHH:MM
2017-12-01T08:00Datetime in format of YYYY-MM-DDTHH:MM
2017-12-01T09:00Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/templates HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved templates
{
"results": {
"templates": [
"labor-day-sale",
"inline",
"welcome-user",
"winter-event-001",
"promotion-x"
]
}
}Returns a list of domains that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/domains HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved domains
{
"results": {
"domains": [
"gmail.com",
"yahoo.com",
"msn.com",
"aol.com",
"hotmail.com"
]
}
}Returns a list of deliverability add-on subject campaigns that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string
Maximum number of results to return
5Start datetime (YYYY-MM-DDTHH:MM)
2017-12-01T08:00End datetime (YYYY-MM-DDTHH:MM)
2017-12-01T09:00Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/subject-campaigns HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved subject campaigns
{
"results": {
"subject-campaigns": [
"Hi there!",
"Hi [REDACTED]",
"exciting offers.",
"[REDACTED] there!",
"[REDACTED] offers.",
"exciting [REDACTED]"
]
}
}Returns a list of sending domains that the Metrics API contains data on.
The ID of the workspace
Only return results containing this string.
Maximum number of results to return.
5Datetime in format of YYYY-MM-DDTHH:MM.
Datetime in format of YYYY-MM-DDTHH:MM.
nowStandard timezone identification string.
UTCGET /api/workspaces/{workspaceId}/reach/metrics/sending-domains HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
Successfully retrieved sending domains
{
"results": {
"sending-domains": [
"example1.com",
"example2.com",
"example3.com"
]
}
}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.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM)
End datetime (YYYY-MM-DDTHH:MM)
The industry category for which you will receive benchmarks
allPossible values: The mailbox provider for which you will receive benchmarks
allPossible values: Standard timezone identification string
UTCGET /api/workspaces/{workspaceId}/reach/metrics/benchmarks/inbox-rate HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
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"
}
]
}Was this helpful?