--- title: "Register a seed test and get its addresses" canonical: "https://bird.com/docs/api/reference/create-email-inbox-insights-seed-test" --- # Register a seed test and get its addresses `POST /v1/email/inbox-insights/seed-tests` 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. Scoped API keys, OAuth and service accounts require organization preview access. ## Code samples **TypeScript** ```ts // Requires Insights preview access for the organization. const idempotencyKey = process.env.IDEMPOTENCY_KEY; if (!idempotencyKey) throw new Error("Set IDEMPOTENCY_KEY to a unique key for this registration and retain it for retries"); let sendingDomain: string | undefined; for await (const domain of bird.email.inboxInsights.domains.list({ search: "mail.example.com" })) { if (domain.domain === "mail.example.com") { sendingDomain = domain.domain; break; } } if (!sendingDomain) throw new Error("Verify mail.example.com in this workspace first"); const configuration = await bird.email.inboxInsights.seedTests.configuration.get({ sending_domain: sendingDomain }); const pool = configuration.list_types.find(choice => choice.available); const profile = configuration.engagement_profiles.find(choice => choice.available); const region = configuration.regions[0]; if (!pool || !profile || !region) throw new Error("No seed-test options available"); const report = await bird.email.inboxInsights.seedTests.create({ sending_domain: sendingDomain, list_type: pool.value, engagement_profile: profile.value, regions: [region.value] }, { idempotencyKey }); console.log(report); ``` Examples: [TypeScript](/docs/api/reference/create-email-inbox-insights-seed-test.ts.md) · [Python](/docs/api/reference/create-email-inbox-insights-seed-test.py.md) · [Go](/docs/api/reference/create-email-inbox-insights-seed-test.go.md) · [PHP](/docs/api/reference/create-email-inbox-insights-seed-test.php.md) · [CLI](/docs/api/reference/create-email-inbox-insights-seed-test.cli.md) · [MCP](/docs/api/reference/create-email-inbox-insights-seed-test.mcp.md) · [cURL](/docs/api/reference/create-email-inbox-insights-seed-test.curl.md) ## Example response `201` ```json { "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" } ``` ## Request body - `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 seed pool to draw addresses from. Use a value the seed-test configuration reports as available for this account. Possible values (may grow over time): `private`, `public`, `exclusive` - `engagement_profile` (string, required) Which engagement behaviour the seeds should simulate. Mixing both behaviours is what makes the engaged-against-dormant comparison measurable. Possible values (may grow over time): `all`, `engaging`, `non_engaging` - `regions` (array of 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 body - `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` (array of object, required): Every address to include in the tested send. Copy them into the send's recipients; results are measured from mail these addresses receive. - `seed_addresses.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. - `seed_addresses.mailbox_provider` (string, required): The provider this address is hosted at. - `seed_addresses.region` (string, required): The region this address sits in, as the seed-test choices name it. - `seed_addresses.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, 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. ## Related resources - [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer) - [Build your first integration](/learn/paths/integration) (course) - [Send your first email](/docs/get-started/send-your-first-email) (docs) [Get an implementation brief](/learn/workspace?topic=api-basics)