Batch sending
Send up to 100 different emails in one API call.
Send up to 100 different emails in one request. Each email has its own recipients, subject and body. Use it for a receipt run, a set of alerts or anything where each person gets their own message.
A batch is for different messages. To send the same message to a contact list, use a broadcast instead.
Send a batch
Send a JSON array to /v1/emails/batch. Each item takes the same fields as Send emails.
curl -X POST https://app.usenotix.dev/api/v1/emails/batch \
-H "Authorization: Bearer $NOTIX_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{ "from": "Acme <hello@acme.com>", "to": "ada@example.com", "subject": "Welcome, Ada", "html": "<p>Hi Ada</p>" },
{ "from": "Acme <hello@acme.com>", "to": "tunde@example.com", "subject": "Welcome, Tunde", "html": "<p>Hi Tunde</p>" }
]'
import { Notix } from "notix-js";
const notix = new Notix(process.env.NOTIX_API_KEY);
const { data, error } = await notix.emails.batch([
{ from: "Acme <hello@acme.com>", to: "ada@example.com", subject: "Welcome, Ada", html: "<p>Hi Ada</p>" },
{ from: "Acme <hello@acme.com>", to: "tunde@example.com", subject: "Welcome, Tunde", html: "<p>Hi Tunde</p>" },
]);
from notix import Notix
notix = Notix() # reads NOTIX_API_KEY
data, error = notix.emails.batch([
{"from": "Acme <hello@acme.com>", "to": "ada@example.com", "subject": "Welcome, Ada", "html": "<p>Hi Ada</p>"},
{"from": "Acme <hello@acme.com>", "to": "tunde@example.com", "subject": "Welcome, Tunde", "html": "<p>Hi Tunde</p>"},
])
use Notix\Notix;
$notix = new Notix(getenv('NOTIX_API_KEY'));
$result = $notix->emails->batch([
['from' => 'Acme <hello@acme.com>', 'to' => 'ada@example.com', 'subject' => 'Welcome, Ada', 'html' => '<p>Hi Ada</p>'],
['from' => 'Acme <hello@acme.com>', 'to' => 'tunde@example.com', 'subject' => 'Welcome, Tunde', 'html' => '<p>Hi Tunde</p>'],
]);
Read the answer
The answer lists what happened to each email, in the order you sent them. Some emails can fail while the rest go out, so check each one.
{
"data": [{ "emailId": "cmg8x2k4b0001qz8v3hf7d2ab" }, { "emailId": "cmg8x2k4b0002qz8v9c1d0e4f" }],
"results": [
{ "index": 0, "emailId": "cmg8x2k4b0001qz8v3hf7d2ab", "status": "QUEUED", "error": null },
{ "index": 1, "emailId": "cmg8x2k4b0002qz8v9c1d0e4f", "status": "SUPPRESSED", "error": null }
],
"summary": { "total": 2, "queued": 1, "scheduled": 0, "suppressed": 1, "failed": 0 }
}
| Status | Meaning |
|---|---|
QUEUED | Going out now. |
SCHEDULED | Going out at its scheduledAt time. |
SUPPRESSED | Every recipient is on your suppression list, so nothing was sent. |
FAILED | Not sent. error says why. |
The Node.js and PHP SDKs return the data list of email ids. Call the API directly if you need results and summary.
Limits
| Scope | Limit |
|---|---|
| Emails per request | 100 |
| Recipients per email | 50 across to, cc and bcc |
| Attachments across the whole batch | 40 MB, measured after base64 decoding |
| Request body | 20 MB |
The recipient limit is per email, not per request. A batch of 100 emails with three people each is fine. One email in the batch that names 51 people refuses the whole batch with 422.
Every recipient counts as one email against your limits and on your bill. That batch of 100 emails with three people each counts as 300.
Retry safely
Add an Idempotency-Key header, the same as for a single send. If the request times out, send it again with the same key and the same body. Notix answers with the first result and sends nothing twice. See Idempotency keys.
await notix.emails.batch(emails, { idempotencyKey: "welcome-run-2026-10-05" });
The full field list is in the Send a batch of emails reference.