broadcasts

Send (or schedule) a broadcast

POST /v1/broadcasts/{id}/send

Auth required api.broadcasts.manage

Dispatches a draft, scheduled or failed broadcast. A failed broadcast never started sending, so nothing was sent and it can be sent again this way. With no body, or no scheduled_at, it sends immediately. With a future RFC 3339 scheduled_at it schedules the broadcast for delivery at that time.

Consent and suppression are enforced at send time: suppressed, globally-unsubscribed, and (when the broadcast has a topic) topic-opted-out recipients are filtered before SES hand-off. Poll GET /v1/broadcasts/{id}/results for per-recipient outcomes.

A topic-less broadcast's unsubscribe link opts the recipient out of all email from this workspace (the one warning, no_topic_unsubscribe_degrades). Where the workspace still requires an acknowledgement of that, sending one without acknowledge_no_topic: true returns 422 no_topic_acknowledgement_required with that warning; a workspace on SendOps-owned topics needs no acknowledgement. Supports the Idempotency-Key header so a retried send does not double-fire. Returns 202 with the broadcast id and its accepted status.

Path parameters

id string<uuid> required

Resource UUID. An unparseable id reads as a clean 404 not_found.

Request body

Content type: application/json

scheduled_at string<date-time> optional

Optional future RFC 3339 UTC instant. Omit (or empty) to send immediately; supply a future time to schedule.

acknowledge_no_topic boolean optional

Deprecated. Workspaces moving to SendOps-owned topics no longer need it and ignore it; until that change reaches your workspace, a topic-less broadcast still needs it set to true.

Responses

Errors follow the RFC 7807 problem format — see the error reference.

202 Send accepted (immediate) or scheduled application/json

id string<uuid> required

status string enum required

sending for an immediate send (the pipeline runs asynchronously) or scheduled when a future scheduled_at was supplied.

One of: sending, scheduled

401 Missing, malformed, or unknown API key application/problem+json

402 The organization's plan does not allow this (code: plan_limit_exceeded). limit_type names the limit — a usage axis such as contacts, segments or active_workflows, or a feature the plan does not include (inboxes, platform_profile, audit_log, notification_presets). upgrade_url is the dashboard page that lifts it; overage_available says a Business organization can lift it by switching overage on instead. Retrying will not succeed until the plan changes or usage drops below the limit. application/problem+json

403 Either the credential lacks the required scope (code: invalid_scope), or it is bound to the test environment and this operation is irreversible (code: test_environment_forbidden). Branch on code: the first is fixed by granting the scope, the second only by using a live credential. See the "Live and test credentials" section of the API description. application/problem+json

404 Resource not found application/problem+json

422 A query parameter, path value or body field failed validation. The body is a validation_failed Problem. When the refusal is about a reference — a segment key, template slug, topic or attribute name the organization does not have — it additionally carries validation_code, field, line/column, missing, candidates and next_step, so a client can correct the call without a second round of guessing. See ValidationProblem. application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json

curl -X POST 'https://api.sendops.dev/v1/broadcasts/00000000-0000-0000-0000-000000000000/send' \ -H "Authorization: Bearer $SENDOPS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"scheduled_at":"2026-05-17T20:00:00Z","acknowledge_no_topic":true}'