/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/sendAuthSend or schedule a broadcast
Now, or at `scheduled_at`. When sending starts the audience is frozen (segment ∩ topic subscribers − unsubscribed − suppression list) and the messages go out at the broadcast rate (default 120 per minute; separate from the transactional limit), on the marketing stream, each with a one-click unsubscribe link and `List-Unsubscribe` headers. The send survives restarts: it continues from the recipients not yet sent.
Path parameters
workspace_id*string · uuidId of the workspace.
broadcast_id*string · uuidId of the broadcast.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.
Request body
scheduled_atstring · date-timeSend at this time instead of now (the draft `scheduled_at` when omitted; null forces now). The audience is frozen when sending starts, so people who unsubscribe meanwhile are left out.
Example: "2026-11-02T09:00:00Z"
Response · 202 `status` is `sending` or `scheduled`.
id*string · uuidThe broadcast id.
name*stringInternal name of the broadcast (not shown to recipients).
Example: "October product update"
from*stringNull on a draft that uses the workspace default sender.
Example: "Acme <news@acme.com>"
subject*stringSubject line; null until set (or when the template supplies it).
Example: "What shipped in October"
template_name*stringTemplate the broadcast renders; null when it has its own content.
Example: "october-update"
html*stringInline HTML body; null when a template is used.
text*stringPlain-text body; null when only HTML or a template is used.
segment_id*string · uuidNull when only a topic targets it, or the segment was deleted.
topic_id*string · uuidTopic the broadcast is sent on; recipients who opted out of it are skipped. Null for none.
status*object`draft`: editable. `scheduled`: waiting for `scheduled_at`. `sending`: going out. `sent`: every recipient handled. `canceled`: stopped before the end.
scheduled_at*string · date-timeWhen the broadcast is scheduled to go out; null when not scheduled.
started_at*string · date-timeWhen the audience froze and sending began.
completed_at*string · date-timeWhen sending finished; null until then.
canceled_at*string · date-timeWhen the broadcast was canceled; null when it was not.
rate_per_minute*numberNull: the workspace setting.
failure_reason*stringWhy the broadcast stopped on its own (its segment or topic was deleted).
counts*objectNull on a draft or a broadcast still scheduled.
created_at*string · date-timeWhen the broadcast was created.
updated_at*string · date-timeWhen the broadcast was last changed.
Example
Request
POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/send
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"scheduled_at": "2026-11-02T09:00:00Z"
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "October product update",
"from": "Acme <news@acme.com>",
"subject": "What shipped in October",
"template_name": "october-update",
"html": "string",
"text": "string",
"segment_id": "00000000-0000-0000-0000-000000000000",
"topic_id": "00000000-0000-0000-0000-000000000000",
"status": {},
"scheduled_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"canceled_at": "2026-01-01T00:00:00.000Z",
"rate_per_minute": 0,
"failure_reason": "string",
"counts": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}