Charchy Senddocs

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 422 with every problem by the email's index, each item with its own code and a field naming 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 200 while 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 — answers 400 validation_error.

  • The workspace checks (from domain, approval, caps, balance) run on the whole batch: the first email that fails refuses the batch with that one error, its field naming 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.

On this page