email-inbox-insights

Get seed tests for a sending domain

Returns the seed tests run for a sending domain over the period, newest first, together with the newest test's full results and the organization's seed-test allowance for the current billing period.

A seed test sends to a panel of real mailboxes across many providers and reports exactly where each copy landed, so unlike the placement estimates it is a direct measurement of one send. Seed counts are small by nature, so a single seed moves a rate noticeably.

The list is capped at 100 tests rather than paged: tests.truncated says whether the period holds more than that, and an earlier period reaches the ones left out. A test counts against the billing-period allowance when it is registered, whether or not its send goes out.

get/v1/email/inbox-insights/seed-tests

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/inbox-insights/seed-tests
  • 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-05-20

First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints. Defaults to 90 days before to, which is the span the history view shows.

It may be at most 90 days before to, which is also the default, so a request naming neither date is already at the limit. Asking for more answers 422. To reach older tests, request an earlier period.

tostring date
Example:2026-08-17

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

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

Seed tests 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"
  },
  "tests": {
    "items": [
      {
        "test_id": "91901",
        "subject": "Fall Preview, first look",
        "tested_at": "2026-08-13T09:12:00Z",
        "list_type": "private",
        "engagement_profile": "all",
        "seed_count": 212,
        "inbox_rate_percent": 89.2,
        "domain": "mail.acme.com",
        "regions": [
          "North America - US",
          "Europe - UK"
        ],
        "delta_pts_vs_prior": -3.1
      }
    ],
    "status": "ok"
  },
  "latest": {
    "test_id": "91901",
    "subject": "Fall Preview, first look",
    "tested_at": "2026-08-13T09:12:00Z",
    "list_type": "private",
    "engagement_profile": "all",
    "seed_count": 212,
    "inbox_rate_percent": 89.2,
    "providers": {
      "items": [
        {
          "mailbox_provider": "gmail",
          "inbox_rate_percent": 95,
          "spam_rate_percent": 5,
          "inbox_seeds": 61,
          "spam_seeds": 3,
          "total_seeds": 64,
          "gmail_category": {
            "category": "promotions",
            "share_percent": 61
          }
        }
      ],
      "status": "ok"
    },
    "auth": {
      "spf_pass_rate_percent": 100,
      "dkim_pass_rate_percent": 100,
      "dmarc_aligned_rate_percent": 100,
      "status": "ok"
    },
    "engagement_split": {
      "items": [
        {
          "mailbox_provider": "gmail",
          "engaged_inbox_rate_percent": 96,
          "dormant_inbox_rate_percent": 71,
          "gap_pts": 25,
          "engaged_seeds": 32,
          "dormant_seeds": 32
        }
      ],
      "status": "ok"
    }
  },
  "quota": {
    "used": 112,
    "limit": 300,
    "resets_at": "2026-09-01T00:00:00Z"
  }
}

Changes

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