Send a batch of emails
POST/api/v1/email/batch
curl -X POST 'https://www.unitpost.com/api/v1/email/batch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'User-Agent: my-app/1.0' \
-H 'Content-Type: application/json' \
-d '{
"emails": [
{
"from": "you@yourdomain.com",
"to": "a@example.com",
"subject": "Hi A",
"html": "<p>Hi A</p>"
},
{
"from": "you@yourdomain.com",
"to": "b@example.com",
"subject": "Hi B",
"html": "<p>Hi B</p>"
}
]
}'{
"object": "list",
"batch_id": "batch_123",
"status": "queued",
"scheduled_at": "2026-01-01T00:00:00.000Z",
"data": [
{
"id": "id_123"
}
],
"failed": [
{
"index": 0,
"error": "string"
}
]
}Send up to 100 transactional emails in a single request. Validation is all-or-nothing: if any item is invalid the whole batch is rejected and nothing is queued, so you never end up with a partial send. Addresses on a reserved domain (example.com, example.net, example.org) can't receive mail: an item's are left out and the rest of it is sent (named in Unitpost-Warning), and an item with no to left is refused on its own and returned in failed with its index while the rest of the batch is sent. With Unitpost-Strict: true an item with any reserved recipient is refused the same way, on its own and in failed: strict mode doesn't refuse the whole batch for it. To schedule, use the object form { emails, scheduled_at } for the whole batch: an item that carries its own send time (scheduled_at, send_at, …) is rejected (422) and nothing is sent. An item with attachments is rejected (422). Pass an Idempotency-Key header to make retries safe — the same key replays the original result instead of re-sending. The response returns a batch_id; track the batch's per-status rollup with Retrieve a batch and stop the rest of it with Cancel a batch. The whole batch counts as one request against your workspace's rate limit (10 requests a second by default), so a list you keep in your own system goes out as one request per 100 recipients: give each batch its own Idempotency-Key and read failed[] in each answer. A batch sent with an Idempotency-Key stops starting messages 5 minutes after its request began and lists the ones it did not reach in failed: those were not sent. The same key replays that answer, so they are sent only by a new request with a new key. A batch is one request, so its messages together fit in 30 MB: a larger one is a 413 that sent nothing, to be sent as several batches. To send one email, use Send or schedule an email; to send the same content to a list, use Create a campaign, which takes up to 5,000 addresses inline. Requires the emails:send capability.
Parameters1 field
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string · header | Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`. |
Response · 200 fields1 field
| Field | Type | Description |
|---|---|---|
idrequired | string | — |