Send Batch
POST /v1/emails/batchQueues up to 10,000 emails in one request. The request is all-or-nothing: if
any email fails validation, nothing is queued. A worker sends them at the
provider rate and retries transient failures. Emails that exhaust their
retries are marked failed.
Track progress with Get Batch, on the dashboard’s Emails page, or through per-email Webhooks.
Request headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer followed by your API key. |
Idempotency-Key | No | Makes the request safe to retry. One key covers the whole batch. See Idempotency. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
emails | object[] | Yes | 1 to 10,000 email objects, each with the same fields as Send Email. |
Every from domain in the batch must be registered and verified on your
account. A batch may mix several verified domains.
Example
Node.js
import { Retransmit } from "retransmit.dev";
const retransmit = new Retransmit(process.env.RETRANSMIT_API_KEY);
const { data, error } = await retransmit.batch.send([
{
from: "Acme <hello@yourdomain.com>",
to: "one@example.com",
subject: "Hello",
html: "<p>Hi one</p>",
tags: [{ name: "campaign", value: "outreach-1" }],
},
{
from: "Acme <hello@yourdomain.com>",
to: "two@example.com",
subject: "Hello",
html: "<p>Hi two</p>",
tags: [{ name: "campaign", value: "outreach-1" }],
},
]);Idempotency
A batch that times out on your side may still have been queued. Send an
Idempotency-Key header and retrying is safe: for 24 hours, the same key
with the same body returns the original batch id instead of queuing 10,000
emails again. Pick a key that represents the whole batch, such as
weekly-digest/2026-09-07 or team-invites/<team-id>.
Node.js
await retransmit.batch.send(emails, { idempotencyKey: "weekly-digest/2026-09-07" });The rules are the same as for a single email. See Send Email: Idempotency.
Response
202 Accepted
{
"id": "bt_xxxxxxxxxxxx",
"total": 2,
"status": "queued",
"created_at": "2026-09-01T12:00:00.000Z"
}Errors
| Status | Code | Cause |
|---|---|---|
400 | invalid_json | Body is not valid JSON. |
400 | invalid_idempotency_key | Idempotency-Key is empty or longer than 256 characters. |
422 | validation_error | An email failed validation. The message includes its index, e.g. emails.42.subject: .... Nothing is queued. |
403 | domain_not_found / domain_not_verified | A from domain in the batch is missing or unverified. Nothing is queued. |
409 | invalid_idempotent_request | Idempotency-Key was already used with a different body. |
409 | concurrent_idempotent_requests | The first request with this Idempotency-Key is still running. Retry shortly. |
401 | unauthorized | Missing, malformed, or revoked API key. |