email-inbox-insights

Check whether a sending domain's infrastructure is blocklisted

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.

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

Query parameters

sending_domainstring required
Example:mail.acme.com

The sending domain to check: one of the workspace's verified sending domains, exactly as it appears there. Inspect the returned targets and their statuses for lookup coverage. A domain that is not verified in this workspace answers not-found.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Blocklist standing for the requested domain's sending infrastructure.

resourcestring required

Which resource this response is, echoed for self-description.

domainstring required

The sending domain the figures describe.

generated_atstring 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.

cached_atstring 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_countinteger 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.

Example response

{
  "resource": "placement",
  "domain": "mail.acme.com",
  "measurement": {
    "sources": [
      "panel",
      "intelliseed_public"
    ],
    "weighting": {
      "weight_set_id": "12",
      "source": "account",
      "basis": "weighted-mean-of-per-isp-rates"
    }
  },
  "generated_at": "2026-08-18T09:34:00Z",
  "freshness": {
    "as_of": "2026-08-17",
    "lag_hint": "daily"
  },
  "cached_at": "2026-08-18T09:40:02Z",
  "targets": [
    {
      "target": "147.253.40.18",
      "target_type": "ip",
      "status": "ok",
      "checked_at": "2026-08-20T09:12:04Z",
      "listings": [
        {
          "reason_code": "CSS",
          "provider": "Spamhaus CSS",
          "reason": "Automated listing of a suspected snowshoe range",
          "first_detected": "2026-07-31T00:00:00Z",
          "last_detected": "2026-08-04T00:00:00Z"
        }
      ]
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.