Send Message Batch
Send 1 to 100 messages in one request. Results are positional: the i-th
element of items is the outcome of the i-th message you sent.
RRay-Batch-Validation: strict (the default) rejects the whole batch with 422 if any
message is invalid and sends nothing; permissive sends the valid messages and returns a
per-position error object for each invalid one. Allowance rejections are positional too:
all accepted is 202, some turned away for allowance is 207, and a batch refused in
full is one top-level 402, 403 or 429 naming the ceiling that stopped it.
207 Multi-Status means exactly one thing: part of the batch was turned away by an
allowance ceiling. A delivery failure on an otherwise-sent batch is not a 207 — that
position carries message.injection_failed and the batch stays 202, because the
request itself was accepted.
Authentication
A workspace key (rray_live_…, bound to one workspace) or the account’s platform key. Platform keys name the target workspace with RRay-Workspace-Id. See Credentials.
Headers
strict (the default) rejects the whole batch with 422 if any message is invalid and sends nothing; permissive sends the valid messages and returns a per-position error object for each invalid one.
Makes a retry safe. The first request with a key performs the batch; a retry with the same key and the same body replays the whole positional result, sending nothing again. The same key with a different body is 409 idempotency.body_mismatch. Claims are kept for 24 hours, then the key is free to reuse. Omit the header and every attempt sends.
The workspace to act on. Required with a platform key; rejected with a workspace key, which already carries its workspace — a matching value is rejected too, rather than silently ignored. An id that is not yours returns 404 workspace.not_found.
Request
Sender address, optionally with a display name (Acme Receipts <receipts@mail.rray.app>). Use an address on a sending domain you have added, so the message can be signed — unsigned mail is very likely to be refused by the recipient’s provider.
Primary recipients, at least one. An address may not repeat anywhere across to, cc and bcc.
Carbon-copy recipients. Visible to every recipient.
Blind carbon-copy recipients. Not visible to other recipients, but each one is a delivery you can track like any other.
Where replies should go instead of from — one address or several.
Subject line. Single-line text.
HTML body. Send html, text, or both; with both, the recipient’s client picks the part it prefers.
Plain-text body.
Response
Per-request tally so the caller can branch without scanning items. Endpoint-
agnostic (total / success_count / error_count mirror the result
discriminator) so every batch response across the API reuses this one model.