Sign inGet Started

Cancel a seeding run

POST
/v1/email/inbox-insights/automatic-seeding/runs/{run_id}/stop
// Requires inbox_insights:write permission in the target workspace.
const run = await bird.email.seeding.runs.cancel("esrun_01krdgeqcxet5s7t44vh8rt9mg");
console.log(run.state, run.progress);
Response200
{
  "id": "esrun_01krdgeqcxet5s7t44vh8rt9mg",
  "state": "stopped",
  "source": {
    "kind": "api",
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg"
  },
  "label": "spring-launch",
  "source_created_at": "2026-05-20T09:14:52Z",
  "retain_until": "2027-06-19T09:14:52Z",
  "progress": {
    "planned": 48,
    "admitted": 30,
    "provider_accepted": 30,
    "delivered": 28,
    "failed": 0,
    "not_sent": 18,
    "unknown": 0,
    "pending": 2
  },
  "sending_domain": "mail.example.com",
  "list_type": "private",
  "engagement_profile": "all",
  "regions": [
    "North America - US"
  ],
  "registration_started_at": "2026-05-20T09:14:55Z",
  "registration_finished_at": "2026-05-20T09:15:02Z",
  "dispatch_deadline": "2026-05-20T10:14:52Z",
  "stop_requested_at": "2026-05-20T09:22:40Z",
  "reason": "run_stopped",
  "issues": [],
  "created_at": "2026-05-20T09:14:53Z",
  "updated_at": "2026-05-20T09:22:40Z"
}

Stop future seed admissions for this run. Already granted copies may still send; registration uncertainty and late registration results remain visible. The original email, schedule or broadcast is unchanged. Repeating stop is safe; finished or failed runs keep their terminal state. Requires Inbox Insights write permission. Reuse the same idempotency key after a lost response.

Parameters

run_idstring

Automatic seeding run to read or stop.

Response Payload

id
string
required
state
string
required

Execution state, separate from delivery and inbox placement:

  • pending: the run is recorded and registration has not started.
  • registering: registration is in progress. A stop request can coexist with an in-flight registration.
  • registration_uncertain: the registration result is unknown. Registration is not automatically repeated, and uncertainty remains visible after a stop.
  • ready: registration has produced a retained seed plan; dispatch scheduling has not started.
  • dispatching: the scheduler is admitting planned copies or recovering earlier handoffs.
  • dispatch_complete: scheduler work is acknowledged. Uncertain admission and pending delivery can remain.
  • stopped: new admissions are closed by a stop request, settings or trigger changes, or the dispatch deadline. Already granted copies may still send.
  • failed: registration failed or the source control was refused. New admissions cannot proceed; retained progress describes any copies already granted. Inspect progress and stop_requested_at alongside this state. A terminal run state does not recall previously granted or queued copies.

Possible values: pending, registering, registration_uncertain, ready, dispatching, dispatch_complete, stopped, failed

source
object
required

Original customer source. This never identifies a generated seed copy. Scheduled means an API-scheduled email.

Show child attributes
source.kind
string
required

Original source kind for this reference.

Possible values: api, smtp, scheduled

source.email_id
string
required
label
string

Label from a trigger address, such as spring-launch in <token>+spring-launch@.... It is a display name and selects nothing.

source_created_at
string
required

Original source execution time.

retain_until
string
required

Time after which this run is no longer available.

progress
object
required

Delivered, failed, not_sent, unknown and pending partition planned copies. Admitted and provider_accepted overlap those buckets and must not be added to them. Late outcomes can move a copy between buckets.

Show child attributes
sending_domain
string

Present after registration establishes the sending domain.

list_type
string

List type frozen at run admission.

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

engagement_profile
string

Engagement profile frozen at run admission.

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

regions
array of string

Regions frozen at run admission.

registration_started_at
string

Registration admission time.

registration_finished_at
string

Time the registration response was persisted.

dispatch_deadline
string

Fixed deadline for new seed admissions.

dispatch_finished_at
string

Time scheduler work completed; uncertain admission or delivery may remain.

stop_requested_at
string

First durable stop, whether requested explicitly or imposed automatically. Already granted copies may still send.

reason
string

Sanitized reason code. Unknown stored details become unavailable; provider error text is never returned.

Possible values (may grow over time): registration_rejected, allowance_exhausted, selection_unavailable, sending_domain_not_measured, vendor_outcome_unknown, invalid_registration_response, canceled_or_expired, run_stopped, settings_disabled, trigger_rotated, dispatch_deadline_exceeded, control_rejected, source_stopped, conflicting_examples, unsupported_source, mixed_recipients, invalid_trigger, seeding_unavailable, contact_template_unsupported, source_not_authorized, content_blocked, capture_expired, capture_failed, preparation_unavailable, policy_refused, unavailable, bounced, rejected, blocked, canceled, provider_outcome_unknown, admission_uncertain, admission_refused

issues
array of object
required

Counts of sanitized terminal or uncertain copy outcomes. No seed addresses or provider error text. Counts overlap the progress buckets.

Show child attributes
created_at
string
required
updated_at
string
required

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