Sign inGet Started

Automatic email seeding

A seed test measures where one real send lands at each mailbox provider. A manual seed test makes you register the test, copy a list of seed addresses, and add them to a send before a deadline. An automatic seed test removes those steps: you send your email to one address, the trigger address, and we send it to the seed mailboxes for you and report where it landed.

Use automatic seeding to test a release or a template change from your own tooling. Each test counts against your monthly seed test allowance, so trigger it on releases, not on every commit.

Before you start

You need:

  • Inbox Insights write permission in the workspace, to turn automatic seeding on and change its settings.
  • A verified sending domain that Inbox Insights measures. Track it to see its results on the Seed tests tab; Tracked domains explains how. Tracking only controls what the dashboard shows: an untracked domain still starts automatic seed tests and uses your allowance.
  • A seed test left in your allowance. The Automatic seeding page shows how many remain.

Turn on automatic seeding

Automatic seeding is off until you turn it on. Its settings and its trigger address are shared by every sending domain in the workspace.

To turn it on:

  1. In the dashboard, open Email > Inbox Insights and select the Seed tests tab.
  2. Select Automatic seeding. It appears once the tab shows a tracked domain and your role has Inbox Insights write permission, so track a domain first if the tab has none.
  3. Choose a Seed pool (the batch of real mailboxes the test draws from), an Engagement profile (how those mailboxes behave: engaged, dormant, or a split of both), and one or more Regions and mailbox groups. The page shows how many seed addresses are available for your choices.
  4. Select Enable automatic seeding.

The page now shows your Trigger address, an address at seeds.bird.com that belongs to this workspace. Copy it. You reuse the same address for every test.

Knowing the trigger address does not let anyone else start a test. A trigger email has to be sent from this workspace, with its API key or SMTP login.

Saving settings does not use a seed test. Each trigger email takes the settings in force when we pick it up: just after an API or SMTP send is accepted, or when a scheduled send is due. It keeps those settings while it waits to start, so a change you save later applies to the next trigger email we pick up.

To turn automatic seeding off, read the current settings with GET /v1/email/inbox-insights/automatic-seeding, then send them back to PATCH /v1/email/inbox-insights/automatic-seeding with enabled: false. Pass the revision you read as expected_revision, and include list_type, engagement_profile, and regions as they were: the update replaces the saved settings, so any choice you leave out is cleared. To replace the trigger address, call POST /v1/email/inbox-insights/automatic-seeding/rotate. The dashboard has no control for either yet. Both stop the seed copies of a test that is already sending, except copies we have already handed over for delivery, and that test still counts against your allowance.

What a seed test uses

Each automatic seed test uses:

  • One seed test from your organization's monthly seed test allowance, counted when the test starts.
  • Send allowance for the seed copies. We send one seed copy to each seed address assigned to the test, and each copy counts as a normal email. The trigger email itself is not counted.

The Automatic seeding page shows how many seed addresses are available for your choices when you view it. Each test is assigned its seed addresses when it starts, so its number of seed copies can differ from that figure. Use it as an estimate before you add regions.

Start a seed test

To start a seed test, send the email you want measured with the trigger address as its only recipient across to, cc, and bcc. Use a from address on your tracked sending domain.

We do not deliver the trigger email to any recipient. We keep it as the example for the test and send the seed copies, spread over about 15 minutes.

Your send is accepted the same way as any other email. Acceptance means we received the email, not that a test started, and the response gives no sign either way. Confirm that the test appears on the Seed tests tab or in the list from GET /v1/email/inbox-insights/seed-tests.

Send the trigger email once for each test you want. Sending it again starts another test and uses another seed test. To retry a request that failed in transit, reuse its idempotency key.

From the API

Send the trigger email with POST /v1/email/messages. Use your regional host (https://us1.platform.bird.com or https://eu1.platform.bird.com) with a matching bk_{region}_... key:

代码示例
curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "news@yourdomain.com",
    "to": ["YOUR_TRIGGER_ADDRESS"],
    "subject": "Spring catalog",
    "html": "<p>The email you want measured.</p>"
  }'

The API returns 202, as it does for any send. Because the trigger address is not a delivery recipient, the response lists no recipients and reports an accepted_count of 0. That is expected, so do not retry because of it.

Send finished content (html, text, or both), or a template with the parameters it needs. If the template reads contact attributes, add the trigger address as a contact first. The seed test uses that contact's values, except the email address, which is each seed mailbox's own. Without a matching contact the API refuses the send with 422, as it does for any template that cannot resolve its values.

Over SMTP

If your application sends through SMTP, submit the message with the trigger address as the only recipient. Authenticate as you do for any other message. The seed test uses the message exactly as your application built it.

At a scheduled time

Add scheduled_at to the API request to schedule the trigger email. It uses your scheduled-email allowance like any other scheduled send. The seed test starts when the send is due, not when you schedule it, and a scheduled send you cancel before it is due does not start one. SMTP has no scheduling.

Read a seed test's results

An automatic seed test appears on the Seed tests tab with your manual seed tests, under the sending domain the trigger email was sent from. The tab does not mark which tests were automatic. Seed tests explains what a finished test reports.

Results fill in as the seed mailboxes receive their seed copies, which takes about 15 minutes after the test starts.

To follow one trigger email from your own tooling, pass its email ID to GET /v1/email/inbox-insights/automatic-seeding/sources as source_email_id. For an API or scheduled send, that is the id in the send response. For an SMTP send, it is the ID after queued as in the server's final reply. Call it with a key from the same workspace and region that has Inbox Insights read permission; a send-only key is refused.

Read the result's state and reason first. scheduled and capturing are still in progress, so wait rather than send again. skipped and failed give the reason the email did not become a test. A run_id links to the test's sending progress at GET /v1/email/inbox-insights/automatic-seeding/runs/{run_id}, but on its own it does not mean the test started. Recent activity can take a moment to appear, so an empty result does not prove the trigger email was dropped.

Placement results are listed with the domain's other seed tests by GET /v1/email/inbox-insights/seed-tests, which requires sending_domain. A listed test carries no reference to its trigger email, so match it by subject and time. The newest test includes its per-provider breakdown, and the default view can be up to 15 minutes old. If your release pipeline waits for placement, give the wait a time limit.

Seed copies count against your send allowance, but they are kept out of your own reporting. The trigger email and its seed copies do not appear in your email log, and they send no webhook events.

A marketing email carries our unsubscribe link. An API send takes its template's category, or is marketing when it carries its own content, unless you set a category in the request. An SMTP send takes the category of its SMTP key, which is transactional unless you configure it, so set the key to marketing to test a marketing email over SMTP. Each seed copy gets its own working link for the seed mailbox that receives it. An unsubscribe from a seed mailbox adds no suppression and updates no preference for your contacts. It only stops later marketing seed copies to that mailbox.

A transactional email gets no unsubscribe link. A link you add yourself is sent unchanged.

Limits on automatic seed tests

Automatic seeding runs within these limits for each sending domain in a workspace:

  • One seed test at a time. A trigger email for a domain that already has a test running waits for that test to finish sending.
  • 30 minutes between seed tests. A new test starts no sooner than 30 minutes after the previous one started. A trigger email that arrives earlier waits.

A waiting trigger email that cannot start a test within 1 hour of its send time, or of its scheduled time, is dropped. It uses no seed test, and the dashboard shows nothing for it.

Fix a seed test that does not start

The dashboard shows nothing for a trigger email that did not start a seed test. Check these causes in order:

  1. The email has other recipients. The trigger address must be the only recipient across to, cc, and bcc. Other recipients receive the email as usual, and no test starts.
  2. Automatic seeding is off, or the address is not the current one. Open Automatic seeding on the Seed tests tab. Confirm that it is enabled and that you are sending to the address shown there.
  3. The sending domain is not measured yet. See When figures are missing. A test for a domain you have not tracked does start, but it does not appear on the Seed tests tab until you track the domain.
  4. No seed tests are left this month. The Automatic seeding page shows how many remain. We check the allowance when a test is about to start, so a trigger email that is still waiting starts on its own if the allowance resets or is raised first. Send the email again only after its run shows the reason allowance_exhausted and your allowance is back. The source keeps showing the example as captured; use its run_id to read the run.
  5. The content was refused or too large. An example that we block as scam content, or that is larger than 10 MiB, is not sent to seed mailboxes.

If another seed test for the domain is running or started in the last 30 minutes, the trigger email is waiting. See Limits on automatic seed tests.

Next steps