---
title: "Check whether a sending domain's infrastructure is blocklisted"
method: GET
path: "/v1/email/inbox-insights/blocklists"
tags: ["email-inbox-insights"]
---

# Check whether a sending domain's infrastructure is blocklisted

`GET /v1/email/inbox-insights/blocklists`

## Request

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

Checks the sending IPs behind a sending domain against the blocklists
receivers consult, and returns what is listed now plus the listings seen
recently against each target. The vendor's default target selection includes
IPs seen sending in the last 30 days and the domain itself. The returned
targets and their statuses describe the coverage of this lookup; an empty
target list does not establish that the domain or its IPs are clear.
The 30-day period selects targets; listing status reflects the current lookup.

The check runs when the request is made, so this is a live lookup rather
than a measurement over a period: there is no window, and only the
freshness lag hint applies. Providers that publish several lists are
reported per list, because what a listing means and how it is cleared
differ between them.

Each target is looked up separately, so one can fail while the rest
succeed. A target nobody managed to check comes back with its `status`
reporting that and its `checked_at` null, rather than as a target that
came back clear. `active_count` is null when the lookup service supplies no
count; do not treat null as zero. Zero does not establish complete coverage:
inspect the returned targets and their statuses. A `503` means Bird
could not reach the lookup service at all, which is a different answer from
a lookup that ran and reported nothing.

## Query parameters

- `sending_domain` string, required

## Headers

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

## Response `200`

Blocklist standing for the requested domain's sending infrastructure.

- EmailInboxInsightsBlocklists: 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.
  - `active_count` integer, nullable, required: Number of successfully checked targets reported with an active listing. A target on three blocklists counts once. Null when the lookup service supplies no count; do not treat null as zero. Zero does not establish that the domain or its IPs were checked. Inspect `targets` and each target's `status` for lookup coverage, including partial failures.
  - `targets` EmailInboxInsightsBlocklistTarget[], required: Returned sending IP or domain lookup results, including failed lookups. An empty array does not establish that the domain or its IPs are clear.
    - `target` string, required: The sending IP or domain selected for lookup.
    - `target_type` string, nullable, required: Whether this target is an IP address or a hostname. Null when the measurement did not report a kind for it, which is possible on a target whose check did not complete.
    - `is_listed` boolean, required: Whether the target is on at least one blocklist right now. Meaningful only when `status` is `ok`: on any other status this target was not checked, so the value carries no finding either way.
    - `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.
    - `checked_at` string, date-time, nullable, required: When this target was looked up, or null when it was not. Per target rather than per response, because each is a separate live lookup.
    - `listings` EmailInboxInsightsBlocklistListing[], required: Listings seen against this target, including ones that have since cleared, so a recent history is visible even when nothing is active. Read each listing's `is_active` rather than assuming every entry is current.
      - `is_active` boolean, required: Whether this listing is in force now. A false entry is history: it shows the target was listed and has since cleared, which is why the target's `is_listed` can be false while listings are present.
      - `reason_code` string, nullable, required: The provider's own short code for the listing reason, or null when it gives none. Stable where the prose in `reason` is not, so branch on this and display that.
      - `provider` string, required: The blocklist that carries the listing. Providers publishing several lists are reported per list rather than under one combined name, because what a listing means and how it is cleared differ per list.
      - `reason` string, nullable, required: The reason the provider gives for the listing, or null when it publishes none.
      - `first_detected` string, date-time, required: When this listing was first observed.
      - `last_detected` string, date-time, nullable, required: When this listing was most recently observed, or null while the listing is still in force. A provider records a last sighting only once one exists, so a null here reads as "still listed" rather than "never seen".

## 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/6dfce1179799?raw)