email-inbox-insights

Get email authentication standing for a sending domain

Returns whether the domain's mail authenticates and who sends as the domain: SPF and DKIM pass rates, the DMARC standing with its published policy and a conservative ready-for-reject judgement, and a per-source table showing every system observed sending under the domain's name, forwarders and unidentified senders included.

The DMARC figures name their source: authoritative aggregate reporting that covers every sender, or Google Postmaster as a fallback covering only mail Google received. Aggregate reports arrive on reporters' own schedules, routinely a day or more behind, so the source table names its latest included day; label from it rather than reading the newest days' sparseness as a regression. For a domain with neither reporting source configured, sections report not_configured with a setup path, not an error.

get/v1/email/inbox-insights/authentication

Request

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

Query parameters

sending_domainstring required
Example:mail.acme.com

The sending domain to report on: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found.

fromstring date
Example:2026-07-19

First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints. Defaults to 30 days before to.

It may be at most 30 days before to, which is also the default, so a request naming neither date is already at the limit. Asking for more answers 422: the page pairs these figures with Bird's own per-provider sending statistics, and those are kept for 30 days, so a longer period could only describe two different spans side by side.

tostring date
Example:2026-08-17

Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today.

compare'previous_period'

Set to previous_period to include the immediately preceding window of equal length in the same response, so deltas need no second request.

Example:previous_period

Include the prior equal-length period, populating compared_to.

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

Authentication standing for the requested domain and period.

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.

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",
  "window": {
    "start": "2026-08-12",
    "end": "2026-08-18",
    "group_by": "day"
  },
  "compared_to": {
    "start": "2026-06-19",
    "end": "2026-07-18"
  },
  "spf": {
    "pass_rate_percent": 99.8,
    "delta_pts": 0.1,
    "source": "dmarc_rua",
    "status": "ok"
  },
  "dkim": {
    "pass_rate_percent": 99.8,
    "delta_pts": 0.1,
    "source": "dmarc_rua",
    "status": "ok"
  },
  "dmarc": {
    "aligned_rate_percent": 98.6,
    "policy": "quarantine",
    "readiness_reasons": [
      "source_below_threshold"
    ],
    "delta_pts": -0.2,
    "source": "dmarc_rua",
    "status": "ok"
  },
  "sources": {
    "items": [
      {
        "name": "Bird (mail.acme.com)",
        "category": "esp",
        "volume": 4820000,
        "spf_aligned_rate_percent": 99.8,
        "dkim_aligned_rate_percent": 99.9,
        "dmarc_pass_rate_percent": 99.9,
        "verdict": "aligned",
        "qualifies_for_readiness": true
      }
    ],
    "latest_data_date": "2026-08-15",
    "status": "ok"
  }
}

Changes

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