Batch sending

Send multiple distinct emails in one request with POST /emails/batch. The body is a JSON array of email objects — each with the same shape as a single POST /emails body. A batch may contain up to 100 emails.

When to use batch sending

Reach for the batch endpoint when you need to send many distinct transactional emails at once — order confirmations, notifications, or per-recipient messages with unique content — and want to cut the number of API calls. For marketing email to an audience, use a campaign instead.

How a batch is processed

MailBlastr validates every email in the batch *before* sending any of them. If a single item fails validation, the whole request is rejected with that item's error and nothing is sent — so an invalid item late in the array can never leave earlier items already delivered. Once all items pass validation, they are sent in order.

Limitations

• A batch holds a maximum of 100 emails; an empty array is also rejected.
• The attachments field is not supported in a batch — send those as single POST /emails requests. See Attachments.
• The scheduled_at field is not supported in a batch — schedule those as single sends. See Schedule email.
• A single invalid item (missing required field, invalid data) fails the whole request and nothing is sent.

Send a batch

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.batch.send([
  {
    "from": "Acme <hello@yourdomain.com>",
    "to": ["first@example.com"],
    "subject": "Welcome, first user",
    "html": "<p>Hello!</p>"
  },
  {
    "from": "Acme <hello@yourdomain.com>",
    "to": ["second@example.com"],
    "subject": "Welcome, second user",
    "html": "<p>Hello!</p>"
  }
]);
console.log({ data, error });

Response

The response is a data array of the created emails, each with its id, in the same order as the request.

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