email-inbox-insights

Register a seed test and get its addresses

Registers a seed test for a sending domain and returns the seed addresses it measures.

Registering a test does not add the addresses to a send. Include them in the recipients of the send you want measured, and results appear as the seed mail arrives. A test that receives no seed mail before it expires never produces results.

The test appears in the seed-test list for the domain once its seed mail has been measured, carrying the subject and the date of the send it rode on. Those two fields are what tell you the send has happened.

Registering spends one of the organization's seed-test allowance whether or not the send goes out, and an expired test does not return it, so register when the send you want measured is ready. The configuration endpoint reports which seed pools, regions, and engagement behaviours this domain's account can use.

Send an Idempotency-Key and reuse it with the unchanged request when retrying a lost response. Before running the curl example, set IDEMPOTENCY_KEY to a unique key for this registration and retain it for retries of the same intent. If registration cannot be confirmed, the API returns 409 E27008 and retains that outcome for keyed retries while the replay result remains available. The allowance may have been used. Contact support before starting another test; a new key or a request without a key can register another batch. A replay does not recover addresses from an uncertain result.

post/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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

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.

Request body

sending_domainstring required

The sending domain the test measures: one of the workspace's verified sending domains, exactly as it appears there.

list_typestring required

Which pool of seed addresses a test uses. Which pools an account can use depends on what has been provisioned for it, so read the usable set from the seed-test options rather than assuming these are the only values.

engagement_profilestring required

Which engagement behaviour the seed addresses simulate. all mixes engaged and dormant seeds, which is what makes an engagement split measurable; single-cohort profiles exist too, and the usable set comes from the seed-test options rather than from this list.

regionsstring[] required

The regions to place seeds in, as the seed-test configuration names them.

labelstring

A name attached to this registration. It is not returned in seed-test history.

Example request

{
  "sending_domain": "mail.acme.com",
  "list_type": "private",
  "engagement_profile": "all",
  "regions": [
    "North America - US",
    "Europe - UK"
  ],
  "label": "Fall preview send"
}

Response

The seed test was registered.

registration_idstring required

Identifies this registration. It is not the identifier the seed-test list reports for the resulting test.

It is here so a registration can be quoted in a support conversation, and so a client can tell two registrations apart. To read the results, find the test in the seed-test list for this domain.

seed_countinteger required

How many seed addresses the test issued.

expires_atstring date-time required

When the test expires if no seed mail has arrived. An expired test never produces results, and the allowance it spent is not returned, so send before this time.

Example response

{
  "registration_id": "43ea66c8-6837-48a4-b81b-26fdf5cc8cd8",
  "seed_addresses": [
    {
      "address": "sd8241.hk@example-seeds.net",
      "mailbox_provider": "gmail",
      "region": "North America - US",
      "engaging": true
    }
  ],
  "seed_count": 212,
  "expires_at": "2026-08-27T09:12:00Z"
}

Changes

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