Skip to Content
Docs
API referenceBroadcasts

Validate and send (or schedule) a draft broadcast

POST
/v1/broadcasts/{id}/send

Only callable from draft (else 409 not_draft). Requires a non-empty subject, a non-empty body_html or body_text, a postal address in the workspace's settings (409 missing_postal_address; CAN-SPAM puts it in every marketing email), a target that still resolves, and a verified from_domain_id. If the address is removed before the fan-out runs, the broadcast is paused. Computes a best-effort total_recipients snapshot, then sets status = scheduled (if scheduled_at is in the future) or status = sending (the fan-out cron picks it up on its next per-minute tick — this call does not enqueue anything itself). Under a key's guardrails the whole broadcast is one decision: refused (403 policy_violation), over the key's daily cap (429 key_daily_cap_exceeded, counting every recipient), or held for a person (202, status = pending_approval). A guarded key's broadcast then sends to at most the total_recipients it was checked against. A guarded key can only use placeholders in the words: one in a tag, a comment, a style block or a link in the text part is refused with 403 policy_placeholder_in_link, which lists them in placeholders. An edit that lands during this call stops it with 409 broadcast_changed.

Authorization

bearerAuth
headerAuthorizationBearer <token>

API key sent as Authorization: Bearer <key>. Looked up by SHA-256 hash (email_core::sha256_hex) against api_keys.hash; revoked keys and keys belonging to a suspended tenant are rejected. See the top-level Authentication section for permission levels.

Path Parameters

id*string

Request Body

application/json
  1. body
scheduled_at?integer

Epoch milliseconds. Omitted or in the past → send now.

Formatint64

Response Body

Transitioned to scheduled or sending.

application/json
  1. response
id?string
name?string
subject?string
from_domain_id?string|null
body_html?string|null
body_text?string|null
target_kind?|
Value in"audience""segment"null
target_id?string|null
status?string
Value in"draft""scheduled""sending""paused""sent""cancelled""pending_approval"
scheduled_at?|
Formatint64
total_recipients?integer

A best-effort snapshot computed at send time (audience member count, or a segment's live match count).

sent_count?integer

Advanced by the fan-out cron as recipients are enqueued.

created_at?integer
Formatint64
updated_at?integer
Formatint64
sent_at?|
Formatint64
Example Request
curl -X POST 'https://api.emitd.com/v1/broadcasts/string/send' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "name": "string",  "subject": "string",  "from_domain_id": "string",  "body_html": "string",  "body_text": "string",  "target_kind": "audience",  "target_id": "string",  "status": "draft",  "scheduled_at": 0,  "total_recipients": 0,  "sent_count": 0,  "created_at": 0,  "updated_at": 0,  "sent_at": 0}