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
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
issues.code
string
required

A reason or delivery status affecting these copies. Unrecognized persisted reasons become unavailable.

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.count
integer
required
created_at
string
required
updated_at
string
required

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