Send a test of a broadcast to explicit recipients
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.
Works for every content mode. A composed broadcast is sent as its body inside its layout, composed exactly as the real send would compose it, with its subject merged per recipient.
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 array<string<email>> required 1–10 explicit recipient email addresses. De-duplicated and lower-cased; an empty set, more than 10, or an invalid address is a 422.
Constraints: 1–10 items
sample_data object optional Optional merge values overlaid on the broadcast's default_template_data for this render. Lets you preview output for addresses that aren't contacts (e.g. inject a rendered body_html); a contact recipient's own attributes still win over these.
Responses
Errors follow the RFC 7807 problem format — see the error reference.
sent integer required Number of recipients SES accepted.
total integer required Total recipients attempted (after de-duplication).
recipients array<object> required Per-recipient outcome, in request order.
Each entry in recipients:
email string<email> required status string enum required sent when SES accepted it, failed otherwise.
One of: sent, failed
message_id string optional SES message id; present only when status is sent.
error string optional Failure reason; present only when status is failed.
code: invalid_scope), or it is bound to the test environment and this operation is irreversible (code: test_environment_forbidden). Branch on code: the first is fixed by granting the scope, the second only by using a live credential. See the "Live and test credentials" section of the API description. application/problem+json validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json