Send a test of a broadcast to explicit recipients

Search Documentation

Search across all developer documentation

broadcasts

Send a test of a broadcast to explicit recipients

POST /v1/broadcasts/{id}/test
Auth required api.broadcasts.manage

Renders the broadcast and dispatches it to an explicit set of 1–10 recipients through the exact production plan + merge + SES path — the same from-address, template resolution, tracking, and unsubscribe footer the audience would receive — so you can eyeball the real email before sending to the audience.

A test send deliberately bypasses the audience and the consent filter: it goes to exactly the addresses you name, even if they are suppressed or opted out (it is a deliberate self-send). It never mutates the broadcast or its counts — test rows are excluded from GET /v1/broadcasts/{id}/results and from the broadcast's rollup. Allowed in any state; testing a draft is the common case.

sample_data overlays the broadcast's default_template_data for this render, so you can preview merge output for addresses that aren't contacts (for example, inject a rendered body_html). A recipient who is a contact still renders from their own attributes, which win over the sample.

Because it delivers real email, a test send is rate-limited per org (default 10/hour) on top of the general API limit — 429 rate_limited when the window is exhausted. An Idempotency-Key is accepted and ignored (test sends are intentionally repeatable). Returns 200 with one outcome per recipient, in request order.

Path parameters

id string<uuid> required

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

Request body

Content type: application/json

{
  "recipients": [
    "user@example.com"
  ],
  "sample_data": {}
}

Responses

200 Per-recipient test-send outcomes, in request order application/json
401 Missing, malformed, or unknown API key application/problem+json
403 Key lacks the required scope or plan limit violated application/problem+json
404 Resource not found application/problem+json
422 Query parameter or path value failed validation 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