--- title: "Register a seed test and get its addresses" method: POST path: "/v1/email/inbox-insights/seed-tests" tags: ["email-inbox-insights"] --- # Register a seed test and get its addresses `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` 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. ## Headers - `Idempotency-Key` string - `X-Workspace-Id` string - `X-Organization-Id` string ## Request body - EmailInboxInsightsSeedTestCreate: How to configure a seed test. The choices available for a domain come from the seed-test configuration. - `sending_domain` string, required: The sending domain the test measures: one of the workspace's verified sending domains, exactly as it appears there. - `list_type` string, 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_profile` string, 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. - `regions` string[], required: The regions to place seeds in, as the seed-test configuration names them. - `label` string: A name attached to this registration. It is not returned in seed-test history. ## Response `201` The seed test was registered. - EmailInboxInsightsSeedTestRegistration: A registered seed test and the addresses it measures. Registering a test does not put the addresses into a send. Add them to the recipients of the send you want measured, and the test appears in the seed-test list for the domain once its seed mail has been measured. There is no status field. The measurement reports none for a seed test at any point, so read the test's own fields instead: a registered test has addresses and an expiry date, and it gains a subject and a tested-at date once its send goes out. - `registration_id` string, 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_addresses` EmailInboxInsightsSeedAddress[], required: Every address to include in the tested send. Copy them into the send's recipients; results are measured from mail these addresses receive. - `address` string, required: The address to add to the send's recipients. Include it exactly as given; an altered address is not a seed and will not be measured. - `mailbox_provider` string, required: A mailbox provider, as the measurement identifies it. A lowercase identifier rather than a display name, so pick your own label for it, and treat the set as open: this is a long tail rather than a handful of household names, and some entries are domains (`fastmail.com`, `seznam.cz`) rather than brands. The measurement places mail into its own seed lists, so its buckets are not the ones the [mailbox-provider stats breakdown](/docs/api/reference/get-email-stats-by-mailbox-provider) reports: Microsoft's properties appear here as `hotmail` rather than `microsoft`, and `apple` appears here where the Competitive Insights panel has no measurement for it at all. None of the three is a joinable dimension against the others. - `region` string, required: The region this address sits in, as the seed-test choices name it. - `engaging` boolean, required: Whether this address simulates a recipient who engages with mail. There are two behaviours rather than a scale, so a test either mixes both or uses one of them. - `seed_count` integer, required: How many seed addresses the test issued. - `expires_at` string, 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. ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `409`: Resource conflict - `412`: Precondition failed - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error - `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation. --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)