API Reference

Send a batch

POST /emails/batch — send up to 100 emails in one request.

POST/emails/batch

Send up to 100 emails in a single request. The body is a JSON array of email objects, each with the same shape as a single send. Every item is validated before any email is sent; if one fails validation, the whole batch is rejected and nothing is sent. See Batch sending.

A small batch returns 200 once every email has been sent; a large one returns `202` with queued: true and is delivered by the background sender. Both bodies carry data with one id per email in request order, so a client that reads data needs no change. Batch delivery modes covers the boundary, following a queued batch, and the batch_incomplete case.

Body

(array)object[]required

An array of 1–100 email objects. Each object accepts the same fields as POST /emails (from, to, subject, html/text, cc, bcc, reply_to, headers, topic_id, template).

The attachments and scheduled_at fields are not supported on the batch endpoint. An optional Idempotency-Key header (max 255 characters, expires after 24 hours) applies to the whole batch.

Request

import { Mailblastr } from 'mailblastr';

const mb = new Mailblastr('mb_xxxxxxxxx');

const { data, error } = await mb.batch.send([
  { "from": "Acme <hello@yourdomain.com>", "to": ["delivered+a@mailblastr.dev"], "subject": "Hi A", "html": "<p>Hello A</p>" },
  { "from": "Acme <hello@yourdomain.com>", "to": ["delivered+b@mailblastr.dev"], "subject": "Hi B", "html": "<p>Hello B</p>" }
]);
console.log({ data, error });

Response

A data array of created emails, in request order.

{
  "data": [
    { "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794" },
    { "id": "1b2c3d4e-5f60-7a8b-9c0d-1e2f3a4b5c6d" }
  ]
}

Errors

Returns validation_error if the body is not a non-empty array, if it contains more than 100 emails, or if any item fails validation (the failing item's error is returned and nothing is sent). See the error reference.