Batch email API for up to 100
transactional emails in one request.

Queue up to 100 transactional emails in one POST. Each entry keeps its own content, recipients, email record, and index-aligned result.

Get an API keyRead batch docs

Batch entries queue immediately. Use the same Idempotency-Key to retry safely. Use the single-send path for attachments or scheduling.

POST/api/v1/email/batch3 items
[0]first@example.comAcceptedem_01
[1]second@example.comRecipient suppressederror
[2]third@example.comAcceptedem_03
The response preserves the request order.
100items per POST
10recipients per item
1project per batch
Indexaligned results
Request to result

One authorization boundary covers the batch, and each item still returns its own outcome.

Request-wide authorization and capacity gates run before the per-item loop. After that boundary clears, each entry receives its own durable delivery record.

01Parse

Validate the complete array

The body must contain 1–100 valid entries. A schema error returns 422 before any item is processed and includes the item index when available.

02Authorize

Resolve one project boundary

The key, project, and sender-domain scope are checked for the request. Every production sender in the batch must resolve to the same allowed project.

03Queue

Store each eligible entry

NoticeAPI stores the batch record, each delivery record, and every outbox job before provider dispatch begins.

04Return

Keep the request index

data[0] describes request item 0. Every item returns an email ID and status. Poll the ID for provider and delivery updates.

Same payload, two clients

Send a compact array, not a custom job protocol.

Each object accepts the normal transactional fields, including templates, variables, custom headers, and tracking overrides.

REST requestcurl
curl -X POST https://www.noticeapi.com/api/v1/email/batch \
  -H "Authorization: Bearer $NOTICEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipts-2026-08-13" \
  -d '[
    {
      "from": "Acme <billing@acme.com>",
      "to": "first@example.com",
      "subject": "Receipt #1042",
      "html": "<p>Your receipt is ready.</p>"
    },
    {
      "from": "Acme <billing@acme.com>",
      "to": "second@example.com",
      "subject": "Receipt #1043",
      "html": "<p>Your receipt is ready.</p>"
    }
  ]'
Node SDKTypeScript
import NoticeAPI from "noticeapi";

const notice = new NoticeAPI(process.env.NOTICEAPI_API_KEY);

const result = await notice.emails.batch([
  {
    from: "Acme <billing@acme.com>",
    to: "first@example.com",
    subject: "Receipt #1042",
    html: "<p>Your receipt is ready.</p>",
  },
  {
    from: "Acme <billing@acme.com>",
    to: "second@example.com",
    subject: "Receipt #1043",
    html: "<p>Your receipt is ready.</p>",
  },
], { idempotencyKey: "receipts-2026-08-13" });
Partial success, durable retry

Read the array before deciding what runs again.

A 202 response means NoticeAPI stored the eligible work before provider dispatch. Match each entry to the request index, then poll its email ID for the final state.

Retry the same payload with the same Idempotency-Key.NoticeAPI returns the original durable batch and does not submit another provider request for the retry.
Read the per-item contract
202 responseJSON
{
  "ok": true,
  "id": "batch_01",
  "data": [
    { "id": "em_01", "status": "queued", "messageId": null },
    {
      "id": "em_02",
      "status": "failed",
      "messageId": null,
      "error": "Suppressed recipient(s): second@example.com",
      "code": "recipient_suppressed"
    }
  ]
}
Know what is request-wide

Independent items still share one safety boundary.

“Partial success” starts after the batch clears its shared project, key, quota, warm-up, and health checks.

Before any send

Request-wide gates

Payload schema, API-key capability, project and domain scope, monthly quota, daily warm-up capacity, and deliverability autopilot.

Inside the loop

Item-level outcomes

Template resolution, simulator classification, sender readiness, recipient suppressions, queued provider work, and stored email records.

Published contract

The limits to encode before production.

1–100

Items per request

The request body is a JSON array with at least one and at most one hundred entries.

10

Recipients per item

Each entry can address up to ten recipients total across to, cc, and bcc.

No

Attachments

Batch entries do not accept attachments. Use the single-send endpoint when files are required.

Queue

Immediate queueing

Batch entries are queued immediately. sendAt is not accepted. Scheduled work belongs on the single-send endpoint.

One

Project boundary

One batch belongs to one project, including batches that use more than one sender domain.

Yes

Simulator items

Simulator recipients work per item, but one item cannot mix simulator and real recipient addresses.

Choose the right send path

Batch when the messages are ready now.

Batch contractPayload fields, per-item response shape, and current limits.Single sendUse scheduling, attachments, and safe retry support for one message.SimulatorExercise delivered, bounced, complained, and suppressed outcomes.Scoped API keysGive a batch worker only the project, domain, and email:send access it needs.
One request, inspectable outcomes

Send the first batch through the simulator.

Use delivered, bounced, complained, and suppressed simulator recipients to exercise your index-matching and retry logic before production traffic.

Get an API keyRead batch docs