Mail API reference

Mail API · Broadcasts

post/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/sendAuth

Send 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 · uuid

Id of the workspace.

broadcast_id*string · uuid

Id of the broadcast.

Headers

Idempotency-Keystring

Opaque 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-time

Send 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 · uuid

The broadcast id.

name*string

Internal name of the broadcast (not shown to recipients).

Example: "October product update"

from*string

Null on a draft that uses the workspace default sender.

Example: "Acme <news@acme.com>"

subject*string

Subject line; null until set (or when the template supplies it).

Example: "What shipped in October"

template_name*string

Template the broadcast renders; null when it has its own content.

Example: "october-update"

html*string

Inline HTML body; null when a template is used.

text*string

Plain-text body; null when only HTML or a template is used.

segment_id*string · uuid

Null when only a topic targets it, or the segment was deleted.

topic_id*string · uuid

Topic 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-time

When the broadcast is scheduled to go out; null when not scheduled.

started_at*string · date-time

When the audience froze and sending began.

completed_at*string · date-time

When sending finished; null until then.

canceled_at*string · date-time

When the broadcast was canceled; null when it was not.

rate_per_minute*number

Null: the workspace setting.

failure_reason*string

Why the broadcast stopped on its own (its segment or topic was deleted).

counts*object

Null on a draft or a broadcast still scheduled.

created_at*string · date-time

When the broadcast was created.

updated_at*string · date-time

When 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"
}