Sign inGet started

Check whether a sending domain's infrastructure is blocklisted

GET
/v1/email/inbox-insights/blocklists
// Requires Insights preview access for the organization.
let sendingDomain: string | undefined;
for await (const domain of bird.email.inboxInsights.domains.list({ search: "mail.example.com" })) {
  if (domain.domain === "mail.example.com") { sendingDomain = domain.domain; break; }
}
if (!sendingDomain) throw new Error("Verify mail.example.com in this workspace first");
const report = await bird.email.inboxInsights.blocklists({ sending_domain: sendingDomain });
console.log(report);
Respons200
{
  "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",
  "active_count": 0,
  "targets": [
    {
      "target": "147.253.40.18",
      "target_type": "ip",
      "is_listed": false,
      "status": "ok",
      "checked_at": "2026-08-20T09:12:04Z",
      "listings": [
        {
          "is_active": false,
          "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"
        }
      ]
    }
  ]
}
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.
API-key calls require Insights preview access for your organization.
Parameter Kueri
sending_domain
string
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.
Payload Respons
resource
string
wajib
Which resource this response is, echoed for self-description.
domain
string
wajib
The sending domain the figures describe.
measurement
object
How the figures were measured. Present only where a figure was weighted or drawn from a named set of sources, which today means placement and the industry benchmark. Absent on the reputation resources and on a live lookup, neither of which weights anything.
Tampilkan atribut turunan
measurement.sources
array of string
wajib
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.
measurement.weighting
object
How the figures were weighted. Present on figures weighted against an audience mix, which is placement's method; measurements that weight nothing carry no weighting block.
Tampilkan atribut turunan
measurement.weighting.weight_set_id
string
wajib
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.
measurement.weighting.source
nullable string
wajib
Which audience mix the weighting used. Null when the measurement weighted these figures by a method this API does not model: the enum is closed so that a client can branch on it exhaustively, which means an unfamiliar method has to answer "not one of these" rather than be passed through. basis usually still describes the method in words when that happens.
measurement.weighting.basis
nullable string
wajib
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
wajib
When the measurement service computed these figures.
freshness
object
wajib
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.
Tampilkan atribut turunan
freshness.as_of
nullable string
wajib
The most recent UTC day the figures include, or null for a live lookup that has no measurement window.
freshness.lag_hint
nullable string
wajib
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.
Possible values (may grow over time): daily, nightly, near_real_time
cached_at
string
Present when the response was served from a short-lived copy rather than fetched for this request: when that copy was fetched.
active_count
nullable integer
wajib
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
array of object
wajib
Returned sending IP or domain lookup results, including failed lookups. An empty array does not establish that the domain or its IPs are clear.
Tampilkan atribut turunan
targets.target
string
wajib
The sending IP or domain selected for lookup.
targets.target_type
nullable string
wajib
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.
Possible values (may grow over time): ip, domain
targets.is_listed
boolean
wajib
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.
targets.status
string
wajib
Whether this target was actually checked. unavailable means the lookup failed or timed out for this target while others may have succeeded, so the honest rendering is "could not check" rather than a result.
Possible values: ok, no_data, not_configured, unavailable, not_applicable
targets.checked_at
nullable string
wajib
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.
targets.listings
array of object
wajib
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.
Tampilkan atribut turunan
targets.listings.is_active
boolean
wajib
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.
targets.listings.reason_code
nullable string
wajib
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.
targets.listings.provider
string
wajib
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.
targets.listings.reason
nullable string
wajib
The reason the provider gives for the listing, or null when it publishes none.
targets.listings.first_detected
string
wajib
When this listing was first observed.
targets.listings.last_detected
nullable string
wajib
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".

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Dapatkan ringkasan implementasi