email-inbox-insights

Get inbox placement for a sending domain

Returns where a sending domain's measured mail landed over the period (inbox or spam): the domain-wide rates, a per-provider table, a time series, the Gmail tab split, and optionally per-IP detail for the domain's sending infrastructure.

Placement figures are estimates from a measurement panel of real mailboxes. Every rate is a percentage of measured placements, never of delivered volume, and the domain-wide summary is weighted against the audience mix described in measurement, so it can legitimately differ from any single provider row. Delta fields appear only when the request asks for a comparison and the prior period has data. Without a requested comparison or comparable prior data they are absent, not zero change.

The series is sparse: buckets with no measured placement are omitted, not returned as zeros, so charts index by date rather than by position. Each section carries its own status, and a successful response never implies every section is populated.

get/v1/email/inbox-insights/placement

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/inbox-insights/placement
  • 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, so figures from the two sources cover the same days. 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.

group_by'day' | 'week' | 'month'

The bucket size a series is grouped by. Day suits the product's charts; wider grains suit long ranges.

Example:day

Bucket size for the series. Defaults to day.

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 and every delta field.

series_providersstring[]

Providers to break the series down by, named as the provider table names them. Each named provider adds one series line; without this, the series carries the domain-wide line only. The provider table is never filtered by this parameter.

[
  "gmail",
  "yahoo"
]
include_ip_detailsboolean

Include per-IP placement detail for the domain's sending infrastructure. Off by default; only the sending-infrastructure view needs it.

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

Placement 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"
  },
  "summary": {
    "inbox_rate_percent": 87.4,
    "spam_rate_percent": 12.6,
    "raw_counts": {
      "inbox": 418211,
      "spam": 60233,
      "measured": 478444
    },
    "read_rate_percent": 21.4,
    "delta_pts": {
      "inbox": -3.1,
      "spam": 3.1
    },
    "status": "ok"
  },
  "providers": {
    "items": [
      {
        "mailbox_provider": "gmail",
        "inbox_rate_percent": 89.2,
        "spam_rate_percent": 10.8,
        "raw_counts": {
          "inbox": 418211,
          "spam": 60233,
          "measured": 478444
        },
        "delta_pts": 0.4,
        "read_rate_percent": 24.3
      }
    ],
    "status": "ok"
  },
  "series": {
    "items": [
      {
        "date": "2026-07-19",
        "mailbox_provider": "gmail",
        "inbox_rate_percent": 90.6,
        "spam_rate_percent": 9.4,
        "inbox_raw_count": 14201,
        "spam_raw_count": 1473
      }
    ],
    "status": "ok"
  },
  "gmail_tabs": {
    "categories": [
      {
        "category": "promotions",
        "overall_percent": 34,
        "inbox_percent": 94,
        "spam_percent": 6
      }
    ],
    "status": "ok"
  },
  "ip_details": {
    "items": [
      {
        "ip": "147.253.40.16",
        "inbox_rate_percent": 89.9,
        "raw_counts": {
          "inbox": 418211,
          "spam": 60233,
          "measured": 478444
        },
        "spf_pass_rate_percent": 99.8,
        "dkim_pass_rate_percent": 99.9
      }
    ],
    "status": "ok"
  }
}

Changes

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