Sign inGet Started

Update automatic seeding settings

PATCH
/v1/email/inbox-insights/automatic-seeding
// Requires inbox_insights:write permission in the target workspace.
const current = await bird.email.seeding.settings.get();
const settings = await bird.email.seeding.settings.update({
  expected_revision: current.revision,
  enabled: true,
  list_type: "private",
  engagement_profile: "all",
  regions: ["North America - US"],
});
console.log(settings.enabled, settings.revision);
Response200
{
  "revision": 3,
  "trigger_address": "4f9a2c7e1b8d4a60935ce7f2b1d0a8c3@seeds.bird.com",
  "enabled": true,
  "list_type": "private",
  "engagement_profile": "all",
  "regions": [
    "North America - US"
  ]
}

Replace settings at the expected revision; omitted selections clear the saved values. Disabling enabled settings permanently stops ungranted copies in existing runs; re-enabling does not resume them. Already granted copies may still send. Use revision zero for initial setup; the first successful update creates a trigger address. A stale revision returns 409 without changing settings. Where automatic seeding is active for the workspace, enabling it lets a send to the trigger address start a seed run, which uses seed-test and email-send allowance.

Request Payload

expected_revision
integer
required

Revision from the latest settings read, or zero for initial setup.

enabled
boolean
required

Saved automatic-seeding preference.

list_type
string

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.

Possible values (may grow over time): private, public, exclusive

engagement_profile
string

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.

Possible values (may grow over time): all, engaging, non_engaging

regions
array of string

Regions to place seeds in. Use regions[].value exactly as returned by GET /v1/email/inbox-insights/seed-tests/configuration for the sending domain your examples come from. Whitespace-only names are rejected, but names are not checked against that list when saved; a name it does not offer makes a later run end with selection_unavailable.

Response Payload

revision
integer
required

Current settings revision. Supply it when updating settings. Initialize settings before rotating the trigger address.

trigger_address
string

Workspace trigger address for seeding examples. Absent before the first settings update. Using it requires authenticated sending access to this workspace; the address itself grants no access.

enabled
boolean
required

Saved automatic-seeding preference.

list_type
string

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.

Possible values (may grow over time): private, public, exclusive

engagement_profile
string

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.

Possible values (may grow over time): all, engaging, non_engaging

regions
array of string

Saved regions to place seeds in, as regions[].value names from GET /v1/email/inbox-insights/seed-tests/configuration. They are not checked against that list when saved.

Continue with the documentation, guides and examples for this topic.