Mail API reference

Mail API · Broadcasts

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

Cancel a scheduled or sending broadcast

Recipients not sent yet are marked `canceled`; messages already handed off are not recalled.

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`.

Response · 200

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}/cancel
Authorization: Bearer YOUR_TOKEN

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