> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/email-api/metrics.md). # 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: * US workspaces: ### 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](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message | | `count_initial_rendered` | Total initial renderings of a message | | `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) 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](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) 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](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) 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](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) 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](https://bird.com/email-plans) Panel messages delivered to the inbox. | | `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. | | `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. | | `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. | | `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. | | `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. | | `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. | | `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. | | `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. | | `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) 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](https://bird.com/email-plans) 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](https://tools.ietf.org/html/rfc3986#section-3.4) 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](https://json-schema.org/) 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: ```json { "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: ```json { "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: ```json { "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 > Retrieves the JSON schema for validating the \`query\_filters\` JSON value.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/query-filters-schema":{"get":{"tags":["Metrics"],"summary":"Advanced Query JSON Schema","description":"Retrieves the JSON schema for validating the `query_filters` JSON value.\n","responses":{"200":{"description":"Successfully retrieved query filters schema","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"$schema":{"type":"string"},"$id":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"default":{"type":"object"},"required":{"type":"array","items":{"type":"string"}},"properties":{"type":"object"},"additionalProperties":{"type":"boolean"},"$defs":{"type":"object","properties":{"groupings":{"type":"object"},"filters":{"type":"object"},"logicalOperators":{"type":"object"}}}}}}}}}}}}}}} ````` ## Discoverability Links > 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.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/":{"get":{"tags":["Metrics"],"summary":"Discoverability Links","description":"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.\n","responses":{"200":{"description":"Successfully retrieved discoverability links","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object"},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"rel":{"type":"string"},"method":{"type":"string"}}}}}}}}}}}}}} ````` ## Aggregations - Metrics Summary > Provides high-level summary of aggregate metrics and lists the child endpoints that contain\ > aggregate data, which can be used as "group by" qualifiers.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics Summary","description":"Provides high-level summary of aggregate metrics and lists the child endpoints that contain\naggregate data, which can be used as \"group by\" qualifiers.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies an alternate delimiter for all included query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"rel":{"type":"string"},"method":{"type":"string"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by Recipient Domain > Provides aggregate metrics grouped by domain over the time window specified.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/domain":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Recipient Domain","description":"Provides aggregate metrics grouped by domain over the time window specified.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by Sending IP > Provides aggregate metrics grouped by sending IP over the time window specified.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/sending-ip":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Sending IP","description":"Provides aggregate metrics grouped by sending IP over the time window specified.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"sending_ip":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by IP Pool > Provides aggregate metrics grouped by IP pool over the time window specified.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/ip-pool":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by IP Pool","description":"Provides aggregate metrics grouped by IP pool over the time window specified.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"ip_pool":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by Sending Domain > Provides aggregate metrics grouped by sending domain over the time window specified.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/sending-domain":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Sending Domain","description":"Provides aggregate metrics grouped by sending domain over the time window specified.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"sending_domain":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by 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\`.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/subaccount":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Subaccount","description":"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`.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"subaccount_id":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by Campaign > Provides aggregate metrics grouped by campaign over the time window specified.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/campaign":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Campaign","description":"Provides aggregate metrics grouped by campaign over the time window specified.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"campaign_id":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by 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]\()).
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/subject-campaign":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Subject Campaign","description":"Provides aggregate metrics grouped by subject campaign over the time window specified.\nThis endpoint supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans)).\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"subject_campaign":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by 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.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/watched-domain":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Watched Domain","description":"Provides aggregate metrics grouped by watched domain over the time window specified. The difference\nbetween domain and watched domain is that watched domains are comprised of the top 99% domains\nin the world.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"watched_domain":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by Mailbox Provider > Provides aggregate metrics grouped by mailbox provider over the time window specified.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Mailbox Provider","description":"Provides aggregate metrics grouped by mailbox provider over the time window specified.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"mailbox_provider":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Metrics by Mailbox Provider Region > Provides aggregate metrics grouped by mailbox provider region over the time window specified.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/mailbox-provider-region":{"get":{"tags":["Metrics"],"summary":"Aggregations - Metrics by Mailbox Provider Region","description":"Provides aggregate metrics grouped by mailbox provider region over the time window specified.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"Delimited list of subject campaigns to include. Supports deliverability add-on metrics only ([Deliverability Add-On](https://bird.com/email-plans))","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"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.\nThe `day` precision will return data in UTC regardless of the specified timezone.\n\nSee the [Precision Parameter](#precision-parameter) section for more information.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","day"],"default":"1min"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. The `day` precision will return data in UTC regardless of the specified timezone","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"order_by","in":"query","description":"Metric by which to order results","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"mailbox_provider_region":{"type":"string"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ````` ## Aggregations - Time-Series Metrics > Provides aggregate metrics ordered by a precision of time.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/time-series":{"get":{"tags":["Metrics"],"summary":"Aggregations - Time-Series Metrics","description":"Provides aggregate metrics ordered by a precision of time.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of domains for filtering","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns for filtering","schema":{"type":"string"}},{"name":"subject_campaigns","in":"query","description":"[Deliverability Add-On](https://bird.com/email-plans) Delimited list of subject campaigns to include. Supports deliverability add-on metrics only.","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"precision","in":"query","description":"Precision of timeseries data returned. Precisions `day`, `week`, and `month` will return data in the UTC timezone regardless of the specified timezone.\n","schema":{"type":"string","enum":["1min","5min","15min","hour","12hr","day","week","month"],"default":"day"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string. Precisions `day`, `week`, and `month` will return data in the UTC timezone regardless of the specified timezone","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string","format":"date-time"},"count_targeted":{"type":"integer"},"count_injected":{"type":"integer"},"count_rejected":{"type":"integer"},"count_sent":{"type":"integer"},"count_delivered":{"type":"integer"},"count_delivered_first":{"type":"integer"},"count_delivered_subsequent":{"type":"integer"},"total_delivery_time_first":{"type":"integer"},"total_delivery_time_subsequent":{"type":"integer"},"total_msg_volume":{"type":"integer"},"count_policy_rejection":{"type":"integer"},"count_generation_rejection":{"type":"integer"},"count_generation_failed":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_soft_bounce":{"type":"integer"},"count_hard_bounce":{"type":"integer"},"count_block_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"count_undetermined_bounce":{"type":"integer"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"},"count_rendered":{"type":"integer"},"count_nonprefetched_rendered":{"type":"integer"},"count_unique_rendered":{"type":"integer"},"count_nonprefetched_unique_rendered":{"type":"integer"},"count_unique_confirmed_opened":{"type":"integer"},"count_nonprefetched_unique_confirmed_opened":{"type":"integer"},"count_clicked":{"type":"integer"},"count_unique_clicked":{"type":"integer"},"count_accepted":{"type":"integer"},"count_spam_complaint":{"type":"integer"},"count_inbox_panel":{"type":"integer"},"count_spam_panel":{"type":"integer"},"count_inbox_seed":{"type":"integer"},"count_spam_seed":{"type":"integer"},"count_inbox_seed_private":{"type":"integer"},"count_spam_seed_private":{"type":"integer"},"count_inbox_seed_virtual":{"type":"integer"},"count_spam_seed_virtual":{"type":"integer"},"count_moved_to_inbox":{"type":"integer"},"count_moved_to_spam":{"type":"integer"},"count_initial_rendered":{"type":"integer"},"count_nonprefetched_initial_rendered":{"type":"integer"},"count_unique_initial_rendered":{"type":"integer"},"count_nonprefetched_unique_initial_rendered":{"type":"integer"},"count_unsubscribe":{"type":"integer"}}}}}}}}}}}}}} ````` ## Aggregations - Bounce Reason Metrics > Provides aggregate metrics, specific to bounce events, grouped by the bounce reasons.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason":{"get":{"tags":["Metrics"],"summary":"Aggregations - Bounce Reason Metrics","description":"Provides aggregate metrics, specific to bounce events, grouped by the bounce reasons.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**Possible Values**: `count_bounce`, `count_inband_bounce`, `count_outofband_bounce`, `count_admin_bounce`\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1000}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"bounce_class_name":{"type":"string"},"bounce_class_description":{"type":"string"},"bounce_category_id":{"type":"integer"},"bounce_category_name":{"type":"string"},"classification_id":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}}}}}}} ````` ## Aggregations - Bounce Reason Metrics By Domain > Provides aggregate metrics, specific to bounce events, grouped by the domain and bounce reasons.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-reason/domain":{"get":{"tags":["Metrics"],"summary":"Aggregations - Bounce Reason Metrics By Domain","description":"Provides aggregate metrics, specific to bounce events, grouped by the domain and bounce reasons.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**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`.\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":5}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"domain":{"type":"string"},"bounce_class_name":{"type":"string"},"bounce_class_description":{"type":"string"},"bounce_category_id":{"type":"integer"},"bounce_category_name":{"type":"string"},"classification_id":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_bounce":{"type":"integer"}}}}}}}}}}}}}} ````` ## Aggregations - Bounce Classification Metrics > Provides aggregate metrics, specific to bounce events, grouped by the bounce classification. (See \[Bounce Classification Codes]\())
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/bounce-classification":{"get":{"tags":["Metrics"],"summary":"Aggregations - Bounce Classification Metrics","description":"Provides aggregate metrics, specific to bounce events, grouped by the bounce classification. (See [Bounce Classification Codes](https://support.sparkpost.com/docs/deliverability/bounce-classification-codes))\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**Possible Values**: `count_bounce`, `count_inband_bounce`, `count_outofband_bounce`, `count_admin_bounce`\n","required":true,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"bounce_class_name":{"type":"string"},"bounce_class_description":{"type":"string"},"bounce_category_name":{"type":"string"},"count_bounce":{"type":"integer"},"count_inband_bounce":{"type":"integer"},"count_outofband_bounce":{"type":"integer"},"count_admin_bounce":{"type":"integer"},"classification_id":{"type":"integer"}}}}}}}}}}}}}} ````` ## Aggregations - Rejection Reason Metrics > Provides aggregate metrics, specific to rejection events, grouped by the rejection reasons.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason":{"get":{"tags":["Metrics"],"summary":"Aggregations - Rejection Reason Metrics","description":"Provides aggregate metrics, specific to rejection events, grouped by the rejection reasons.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":5}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"count_rejected":{"type":"integer"},"rejection_category_id":{"type":"integer"},"rejection_type":{"type":"string"}}}}}}}}}}}}}} ````` ## Aggregations - Rejection Reason Metrics By Domain > Provides aggregate metrics, specific to rejection events, grouped by the domain and rejection reasons.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/rejection-reason/domain":{"get":{"tags":["Metrics"],"summary":"Aggregations - Rejection Reason Metrics By Domain","description":"Provides aggregate metrics, specific to rejection events, grouped by the domain and rejection reasons.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":5}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"domain":{"type":"string"},"count_rejected":{"type":"integer"},"rejection_category_id":{"type":"integer"},"rejection_type":{"type":"string"}}}}}}}}}}}}}} ````` ## Aggregations - Delay Reason Metrics > Provides aggregate metrics, specific to delay events, grouped by the delay reasons.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason":{"get":{"tags":["Metrics"],"summary":"Aggregations - Delay Reason Metrics","description":"Provides aggregate metrics, specific to delay events, grouped by the delay reasons.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":5}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"}}}}}}}}}}}}}} ````` ## Aggregations - Delay Reason Metrics By Domain > Provides aggregagte metrics, specific to delay events, grouped by the domain and delay reasons.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/delay-reason/domain":{"get":{"tags":["Metrics"],"summary":"Aggregations - Delay Reason Metrics By Domain","description":"Provides aggregagte metrics, specific to delay events, grouped by the domain and delay reasons.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":5}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"domain":{"type":"string"},"count_delayed":{"type":"integer"},"count_delayed_first":{"type":"integer"}}}}}}}}}}}}}} ````` ## Aggregations - Engagement Details > 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]\().
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/link-name":{"get":{"tags":["Metrics"],"summary":"Aggregations - Engagement Details","description":"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](https://developers.sparkpost.com/api/template-language/#header-link-names).\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}},{"name":"metrics","in":"query","description":"Delimited list of metrics for filtering.\n\n**Possible Values**: `count_clicked`, `count_raw_clicked`.\n","required":true,"schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return between 1 and 10000, inclusive","schema":{"type":"integer","minimum":1,"maximum":10000,"default":5}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"link_name":{"type":"string"},"count_clicked":{"type":"integer"},"count_raw_clicked":{"type":"integer"}}}}}}}}}}}}}} ````` ## Aggregations - Deliveries By 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+.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/deliverability/attempt":{"get":{"tags":["Metrics"],"summary":"Aggregations - Deliveries By Attempt","description":"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+.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"query_filters","in":"query","description":"An advanced query structure. See the [Advanced Filters](#advanced-filters) section.","schema":{"type":"object"}},{"name":"domains","in":"query","description":"Delimited list of recipient domains to include","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Delimited list of campaigns to include","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Delimited list of mailbox providers to include","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Delimited list of mailbox provider regions to include","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Delimited list of sending IPs to include","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Delimited list of IP pools to include","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Delimited list of sending domains to include","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Delimited list of subaccount IDs to include","schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved metrics","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"string"},"count_delivered":{"type":"integer"}}}}}}}}}}}}}} ````` ## Lists - IP Pools > Returns a list of IP pools that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/ip-pools":{"get":{"tags":["Metrics"],"summary":"Lists - IP Pools","description":"Returns a list of IP pools that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved IP pools","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"ip-pools":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Lists - Sending IPs > Returns a list of sending IPs that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/sending-ips":{"get":{"tags":["Metrics"],"summary":"Lists - Sending IPs","description":"Returns a list of sending IPs that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved sending IPs","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"sending-ips":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Lists - Mailbox Provider Regions > Returns a list of mailbox provider regions that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/mailbox-provider-regions":{"get":{"tags":["Metrics"],"summary":"Lists - Mailbox Provider Regions","description":"Returns a list of mailbox provider regions that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved mailbox provider regions","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"mailbox-provider-regions":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Lists - Mailbox Providers > Returns a list of mailbox providers that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/mailbox-providers":{"get":{"tags":["Metrics"],"summary":"Lists - Mailbox Providers","description":"Returns a list of mailbox providers that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved mailbox providers","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"mailbox-providers":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Lists - Campaigns > Returns a list of campaigns that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/campaigns":{"get":{"tags":["Metrics"],"summary":"Lists - Campaigns","description":"Returns a list of campaigns that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`","schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"campaigns":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Lists - Domains > Returns a list of domains that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/domains":{"get":{"tags":["Metrics"],"summary":"Lists - Domains","description":"Returns a list of domains that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved domains","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Lists - Subject Campaigns > Returns a list of deliverability add-on subject campaigns that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/subject-campaigns":{"get":{"tags":["Metrics"],"summary":"Lists - Subject Campaigns","description":"Returns a list of deliverability add-on subject campaigns that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved subject campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"subject-campaigns":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Lists - Sending Domains > Returns a list of sending domains that the Metrics API contains data on.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/sending-domains":{"get":{"tags":["Metrics"],"summary":"Lists - Sending Domains","description":"Returns a list of sending domains that the Metrics API contains data on.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"match","in":"query","description":"Only return results containing this string.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","default":5}},{"name":"from","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Datetime in format of `YYYY-MM-DDTHH:MM`.","schema":{"type":"string","format":"date-time","default":"now"}},{"name":"timezone","in":"query","description":"Standard timezone identification string.","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved sending domains","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"sending-domains":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}} ````` ## Industry 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.
`````json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Metrics","description":"Reach Email logs copious amounts of statistical, real-time data about message processing, message disposition, and campaign performance.\n\nThis reporting data is available in the \"Insights\" page (under the \"Developer\" / \"Channels\" / \"Email\" section) in the app or through the Metrics API.\n\nThe 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.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data retention\n\nMetrics API data is retained for 6 months.\n\n## Terminology\n\nDefinitions for terms found in Metrics API\n\n| Term | Definition |\n|----------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `count_targeted` | Messages successfully injected into Reach Email as well as rejected by it |\n| `count_injected` | Messages injected to or received by Reach Email |\n| `count_sent` | Messages that Reach Email attempted to deliver, which includes both Deliveries and Bounces |\n| `count_accepted` | Messages an ISP or other remote domain accepted (less Out-of-Band Bounces) |\n| `count_delivered` | Messages delivered |\n| `count_delivered_first` | Messages delivered on the first attempt |\n| `count_delivered_subsequent` | Messages delivered that required more than one delivery attempt |\n| `count_rendered` | Total renderings of a message |\n| `count_nonprefetched_rendered` | Total [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_initial_rendered` | Total initial renderings of a message |\n| `count_nonprefetched_initial_rendered` | Total initial [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) renderings of a message |\n| `count_unique_rendered` | Total number of messages that were rendered at least once |\n| `count_nonprefetched_unique_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered at least once |\n| `count_unique_initial_rendered` | Total number of messages that were initally rendered at least once |\n| `count_nonprefetched_unique_initial_rendered` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were initally rendered at least once |\n| `count_unique_confirmed_opened` | Total number of messages that were rendered or had at least one link selected |\n| `count_nonprefetched_unique_confirmed_opened` | Total number of [non-prefetched](https://bird.com/blog/impact-of-ios-15-update-on-open-tracking) messages that were rendered or had at least one link selected |\n| `count_clicked` | Total number of times that links were selected across all messages |\n| `count_unique_clicked` | Total number of messages which had at least one link selected one or more times |\n| `count_bounce` | Total number of bounced messages, which includes both In-Band and Out-of-Band bounces |\n| `count_hard_bounce` | Total number of Bounced messages due to hard bounce classification reasons |\n| `count_soft_bounce` | Total number of Bounced messages due to soft bounce classification reasons |\n| `count_block_bounce` | Total number of Bounced messages due to an IP block |\n| `count_admin_bounce` | Total number of Bounced messages due to admin bounce classification reasons, also includes Rejected |\n| `count_undetermined_bounce` | Total number of Bounced messages due to undetermined bounce reasons |\n| `count_rejected` | Messages rejected due to policy or that failed to generate |\n| `count_policy_rejection` | Messages rejected by Reach Email due to policy |\n| `count_generation_failed` | Message generation failed for an intended recipient |\n| `count_generation_rejection` | Messages rejected by Reach Email due to policy |\n| `count_inband_bounce` | Messages that bounced on delivery attempt during the SMTP session |\n| `count_outofband_bounce` | Messages that the ISP bounced subsequent to a successful delivery |\n| `count_delayed` | Total number of delays due to any temporary failure |\n| `count_delayed_first` | Messages delayed on the first delivery attempt |\n| `total_msg_volume` | Total size of delivered messages, in bytes (including attachments) |\n| `count_spam_complaint` | Number of spam complaints received from an ISP |\n| `total_delivery_time_first` | Total time taken to deliver messages on first attempt (milliseconds) |\n| `total_delivery_time_subsequent` | Total time taken to delivery messages on subsequent attempts (milliseconds) |\n| `count_unsubscribe` | Total number of unsubscribes as a result of clicked links and the ISP list unsubscribe feature |\n| `count_inbox_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox. |\n| `count_spam_panel` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder. |\n| `count_inbox_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the inbox. |\n| `count_spam_seed` | [Deliverability Add-On](https://bird.com/email-plans) All Seed messages delivered to the spam folder. |\n| `count_inbox_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the inbox. |\n| `count_spam_seed_private` | [Deliverability Add-On](https://bird.com/email-plans) Private Seed messages delivered to the spam folder. |\n| `count_inbox_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the inbox. |\n| `count_spam_seed_virtual` | [Deliverability Add-On](https://bird.com/email-plans) Virtual Seed messages delivered to the spam folder. |\n| `count_moved_to_inbox` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the spam folder then moved to the inbox. |\n| `count_moved_to_spam` | [Deliverability Add-On](https://bird.com/email-plans) Panel messages delivered to the inbox then moved to the spam folder. |\n\n**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](https://bird.com/email-plans) customers.\n\n**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`.\n\n## Precision Parameter\n\nWhen 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.\nFor example, requesting data between `4:22` to `6:37` would return results within the following time windows:\n\n| Precision | Rounded time window | Max time window |\n|-----------|-------------------------|-----------------|\n| `1min` | `04:22:00` - `06:36:59` | `24 hours` |\n| `5min` | `04:20:00` - `06:39:59` | `24 hours` |\n| `15min` | `04:15:00` - `06:44:59` | `48 hours` |\n| `hour` | `04:00:00` - `06:59:59` | `31 days` |\n| `day` | `00:00:00` - `23:59:59` | `No max` |\n\n### Time-series Metrics\n\nWhen the `precision` parameter is specified for the [time-series request](#metrics-get-time-series-metrics), it reflects the period of time the data is grouped by.\nThe 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.\n\n## Filters\n\nMetric data can be filtered by using query parameters in the [query component](https://tools.ietf.org/html/rfc3986#section-3.4) of the request URI.\nEach Metrics endpoint specifies certain filters that can be set as query parameters.\nThe exact filters and query parameters available to each route are listed in the respective route's \"parameters\" section below.\nThe filters can be specified using either a simple or advanced query syntax.\n\n### Simple Filters\n\nSimple query filters can be specified as key-value pairs in the request URI and multiple values can be listed with a delimiter separating them.\nFor example metrics can be limited to sending domains equal to `bird.com` or `example.org` with the following query string:\n`?sending_domains=bird.com,example.org`\n\n### Advanced Filters\n\nThe Metrics API allows for more advanced data filtering with multiple conditions, groupings, and comparators via the `query_filters` query parameter.\n\nThe value of the `query_filters` query parameter must be structured as a URL-encoded JSON object.\nThe Metrics API uses [JSON Schema](https://json-schema.org/) to define and validate advanced filters.\nAdvanced Filter requests that do not adhere to the schema will result in a `400` error response.\nSpecific schema violations will be attached to the `validationErrors` property of the error response.\nThe exact schema can be retrieved through the `/deliverability/query-filters-schema` endpoint.\nSee [Advanced Query JSON Schema](#metrics-get-advanced-query-json-schema).\n\nPlease note, advanced filters cannot be used in conjunction with simple filters. Simple filters will be ignored if the `query_filters` parameter is used.\ne.g. in `?domains=mailing.com&query_filters={}`, the domains query parameter will be ignored.\nOther query parameters like `from`, `to`, `metrics`, `limit`, etc., will be processed as expected.\n\n#### Groupings Structure\nThe 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.\n\nExample:\n````json\n{\n \"groupings\": [\n {\n ... compare group\n },\n {\n ... compare group\n }\n ]\n}\n\n````\n\n#### Compare Group\n\nThe 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.\n\nExample:\n````json\n{\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ],\n \"notLike\": [ \".io\" ]\n }\n }\n}\n````\n\nEach filter group is comprised of the filter keys and comparator keywords.\nFilter keys must be unique within a grouping, but the same filter key can appear in multiple groupings.\n\n#### Filter Keys\n\n- `domains`\n- `sending_ips`\n- `ip_pools`\n- `campaigns`\n- `subject_campaigns`\n- `sending_domains`\n- `mailbox_providers`\n- `subaccounts`\n- `mailbox_provider_regions`\n\n#### Comparator Keywords\n\n- `eq` - array of exact values to match\n- `like` - array of substrings to match on; values must be at least 3 characters long\n- `notEq` - array of exact values to NOT match\n- `notLike` - array of substrings to NOT match on; values must be at least 3 characters long\n\n\n#### Put it all together\n\nJSON query object:\n```json\n{\n \"groupings\": [\n {\n \"AND\": {\n \"domains\": {\n \"eq\": [ \"gmail.com\", \"yahoo.com\", \"hotmail.com\" ],\n \"like\": [ \"mail\" ]\n },\n \"sending_domains\": {\n \"notEq\": [ \"bird.com\" ]\n }\n }\n },\n {\n \"campaigns\": {\n \"like\": [ \"333\", \"344\", \"355\" ]\n }\n },\n {\n \"OR\": {\n \"campaigns\": {\n \"notLike\": [ \"Friday\" ],\n \"notEq\": [ \"stuff\", \"things\" ]\n }\n }\n }\n ]\n}\n```\n\nCompressed (whitespace and line end characters removed) and URL encoded:\n```\n?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\n```\n\n## Aggregations\n\nThe 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.\n\nUse the `subaccount` field to get metrics about individual subaccounts or set it to 0 to get only the primary account's data.\n\n## Lists\n\nEach 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.\n\n## Industry Benchmarks\n\nThe industry benchmarks endpoints allow you to compare your performance to your industry.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/metrics/benchmarks/inbox-rate":{"get":{"tags":["Metrics"],"summary":"Industry Benchmarks - Inbox Rate","description":"Provides daily inbox rate industry benchmarks of 25th, 50th (median), and 75th percentile.\n\n**Note:** The Inbox Rate Industry Benchmark endpoint is available to the [Deliverability Add-On](https://bird.com/email-plans) customers only.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM`)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM`)","schema":{"type":"string","format":"date-time"}},{"name":"industry_category","in":"query","description":"The industry category for which you will receive benchmarks","schema":{"type":"string","enum":["all","automotive","b2b","cpg","entertainment","finance","food_beverage_service","govt_education_charity","job_search","media_publishing","medical","misc","personal_services","retail_apparel","retail_online","retail_other","retail_supermarket_drug","social_review","telco","travel"],"default":"all"}},{"name":"mailbox_provider","in":"query","description":"The mailbox provider for which you will receive benchmarks","schema":{"type":"string","enum":["all","gmail","hotmail","verizon_media_group"],"default":"all"}},{"name":"timezone","in":"query","description":"Standard timezone identification string","schema":{"type":"string","default":"UTC"}}],"responses":{"200":{"description":"Successfully retrieved inbox rate benchmarks","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"median":{"type":"number","format":"float"},"q25":{"type":"number","format":"float"},"q75":{"type":"number","format":"float"},"ts":{"type":"string","format":"date-time"}}}}}}}}}}}}}} ````` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/email-api/metrics.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.