---
title: "Get the industry placement benchmark for a sending domain"
method: GET
path: "/v1/email/inbox-insights/benchmarks/industry"
tags: ["email-inbox-insights"]
---

# Get the industry placement benchmark for a sending domain

`GET /v1/email/inbox-insights/benchmarks/industry`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/email/inbox-insights/benchmarks/industry`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Returns how senders in a sending domain's industry place: the median inbox
rate across the industry's measured senders, how many senders that median
covers, and the industry the domain was classified into.

The benchmark describes the industry rather than the domain, so it carries
no comparison of its own. Compare it against the domain's own inbox rate
from the placement resource. Its weighting is a general default rather than
any one account's audience mix, a deliberate asymmetry with the placement
figure it is compared against, and one worth naming wherever the two
appear together.

The status is `no_data` when too few measured senders share the industry
for a median to be meaningful, when the domain's industry is not
classified, or before the industry figures have been computed. That state
is normal for a young cohort rather than an edge case, so handle it from
the start.

## Query parameters

- `sending_domain` string, required

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

The industry benchmark for the requested domain's industry.

- EmailInboxInsightsIndustryBenchmark: The meta every Inbox Insights resource carries, whatever it measures, so one client adapter serves them all.
  - `resource` string, required: Which resource this response is, echoed for self-description.
  - `domain` string, required: The sending domain the figures describe.
  - `measurement` EmailInboxInsightsMeasurement: How the figures in this response were measured, so a number is self-describing in a screenshot or a bug report.
    - `sources` string[], required: Identifiers of the measurement systems that contributed to these figures. The set grows as measurement coverage does, so treat the values as labels rather than a closed list.
    - `weighting` EmailInboxInsightsWeighting: How the placement figures in this response were weighted, so a number is self-describing wherever it is quoted or screenshotted. Placement rates are a weighted average of per-provider rates against an audience mix (the share of recipients expected at each mailbox provider) rather than a share of delivered volume.
      - `weight_set_id` string, required: The measurement's own identifier for the audience mix, carried through so a client can tell two weightings apart without comparing `basis` strings. No operation accepts it.
      - `source` 'account' | 'global', required: Where the audience mix behind the placement weighting came from: `account` when it was configured for this account, `global` when a general default was used instead.
      - `basis` string, nullable, required: The weighting method behind the rates, as the measurement names it. A slug rather than a sentence, so render it as a label and do not expect it to read as English. Null when the measurement did not state one, which pairs with `source`: both describe the method, so neither can claim to know it when the measurement was silent.
  - `generated_at` string, date-time, required: When these figures were computed. The measurement service's own stamp where it publishes one; on the resources Bird derives from daily rates it has none to publish, and this is when Bird computed them.
  - `freshness` EmailInboxInsightsFreshness, required: How current the figures are. Freshness differs per resource (authentication data can lag a day or more while blocklist lookups are near real time), so any "as of" label binds from this field, never from a fixed string.
    - `as_of` string, date, nullable, required: The most recent UTC day the figures include, or null for a live lookup that has no measurement window.
    - `lag_hint` string, nullable, required: How far behind real time this resource usually runs. A lowercase identifier rather than a display label, so pick your own wording for it, and treat the set as open: the measurement names a hint per resource and can add one without notice. Null when the measurement reports no hint, which several resources do: show the figures without an age rather than inventing one.
  - `cached_at` string, date-time: Present when the response was served from a short-lived copy rather than fetched for this request: when that copy was fetched.
  - `industry` EmailInboxInsightsIndustry, required: The industry a sending domain was classified into.
    - `id` string, required: The measurement's own identifier for this industry, carried through so a client can tell two cohorts apart without comparing labels. No operation accepts it.
    - `name` string, required: Display name of the industry. The classification is broad, so bind this label rather than assuming a finer category exists.
  - `median_inbox_rate_percent` number, nullable, required: The industry's median inbox rate, as a percentage.
  - `window_days` integer: How many days the cohort figure covers. Reported rather than assumed because the period is the one the nightly computation produced, not one the caller chose, so a label built from a requested window would be wrong. Absent when the computation does not report it, in which case a label must not name a period at all.
  - `cohort_size` integer, nullable, required: How many measured senders the median was computed across.
  - `status` 'ok' | 'no_data' | 'not_configured' | 'unavailable' | 'not_applicable', required: Whether a section of the response carries figures, and when it does not, why. `ok` means the section is populated. `no_data` means the measurement ran and observed nothing to report for this domain in the period. `not_configured` means the section needs a setup step that has not been completed yet, such as connecting Google Postmaster Tools; treat it as an invitation to finish setup rather than a fault. `unavailable` means the figures could not be retrieved this time and the same request may well succeed on a retry; the rest of the response is unaffected. `not_applicable` means the section is meaningless for this domain in this period, so there is nothing to show or fix. A successful response never implies every section is populated; read each section's status rather than assuming figures are present.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `412`: Precondition failed
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)