Batch
POST /v1/emails/batch — up to 100 emails in one request, checked all-or-nothing.
Up to 100 emails in one request — a nightly digest of account alerts,
receipts for a bulk import. Each has its own recipients, subject, body, tags
and scheduled_at.
POST https://api.charchy.krd/v1/emails/batch
Authorization: Bearer chy_live_…
Content-Type: application/json
Idempotency-Key: november-invoices/2026-11{
"emails": [
{
"from": "Darin Game <billing@daringaming.com>",
"to": ["ara@example.com"],
"subject": "Your November invoice",
"html": "<p>Hi Ara, your invoice is ready…</p>",
"tags": { "type": "invoice" }
},
{
"from": "Darin Game <billing@daringaming.com>",
"to": ["shilan@example.com"],
"subject": "Your November invoice",
"html": "<p>Hi Shilan, your invoice is ready…</p>",
"tags": { "type": "invoice" },
"scheduled_at": "2026-11-17T08:00:00+03:00"
}
]
}A bare array, without the emails wrapper, works too.
Response 200 — the ids in the order you sent them:
{
"emails": [
{ "id": "em_3n8v2c7x1k5d9q4w7m2r6t1y", "status": "queued" },
{ "id": "em_9q4w7m2r6t1y3n8v2c7x1k5d", "status": "scheduled" }
]
}Rules
-
Same fields as Send an email, per email.
-
No attachments in a batch (
validation_error) — send those one by one. -
All or nothing. If any email is invalid, nothing is sent: you get
422with every problem by the email's index, each item with its owncodeand afieldnaming the email:{ "error": { "code": "validation_error", "message": "2 of the emails are invalid, so none were sent.", "docs": "https://charchy.krd/docs/errors#validation_error", "items": [ { "index": 0, "code": "validation_error", "field": "emails[0].to", "message": "\"ara@\" is not an email address." }, { "index": 7, "code": "schedule_out_of_range", "field": "emails[7].scheduled_at", "message": "scheduled_at is more than 30 days ahead." } ] } }We never answer
200while some emails failed — a partial success is too easy to miss in your logs. -
A problem with the batch itself — an empty list, more than 100 emails, a field other than
emails— answers400 validation_error. -
The workspace checks (
fromdomain, approval, caps, balance) run on the whole batch: the first email that fails refuses the batch with that one error, itsfieldnaming the email (emails[3].from). -
A suppressed recipient is skipped, as in a single send; it doesn't fail the batch.
-
One charge for the whole batch, counted per recipient like single sends.
-
One idempotency key covers the whole batch: a retry with the same key returns the same ids and sends nothing twice.
-
A batch counts as one request against the rate limit of 10 a second.
When to use it
Batch saves requests, not delivery time: queued emails go out at the same
pace either way. Use it when you already have many emails in hand; for one
email per user action, a single POST /v1/emails is simpler.