Batch sending

POST https://api.spacepost.dev/emails/batch

The body is a JSON array of up to 100 objects, each with the same fields as Send an email. Batching saves round trips and counts as a single request against your rate limit.

Node.js

batch.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.batch.send(
  [
    { from: "Acme <hello@acme.com>", to: ["a@example.com"], subject: "Hi Ada", html: "<p>Hi Ada</p>" },
    { from: "Acme <hello@acme.com>", to: ["b@example.com"], subject: "Hi Bob", html: "<p>Hi Bob</p>" },
  ],
  { idempotencyKey: "weekly-digest-2026-w43" },
);

if (error) console.error(error);
else console.log(data.data.map((e) => e.id)); // ids in input order

cURL

curl -X POST https://api.spacepost.dev/emails/batch \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: weekly-digest-2026-w43" \
  -d '[
    { "from": "Acme <hello@acme.com>", "to": ["a@example.com"], "subject": "Hi Ada", "html": "<p>Hi Ada</p>" },
    { "from": "Acme <hello@acme.com>", "to": ["b@example.com"], "subject": "Hi Bob", "html": "<p>Hi Bob</p>" }
  ]'

Python

r = requests.post(
    "https://api.spacepost.dev/emails/batch",
    headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
    json=[
        {"from": "Acme <hello@acme.com>", "to": ["a@example.com"], "subject": "Hi Ada", "html": "<p>Hi Ada</p>"},
        {"from": "Acme <hello@acme.com>", "to": ["b@example.com"], "subject": "Hi Bob", "html": "<p>Hi Bob</p>"},
    ],
)
print(r.json())  # {"data": [{"id": "..."}, {"id": "..."}]}

Response (200)

{
  "data": [
    { "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" },
    { "id": "0192e1c4-7a3c-7a02-8e10-6c0f9d7a2b31" }
  ]
}

Ids are returned in the same order as the input array.

Behavior

• All or nothing. If any email in the array is invalid, the whole request fails with a validation_error and nothing is stored. The message says which email ((email 1)).
• Quota is checked once for the total recipient count. If it would exceed your limit, the whole batch is rejected.
• Everything is allowed per email: attachments, tags, custom headers, scheduled_at and tenant_id. A paused tenant or an over-cap tenant fails the whole batch.
• Idempotency keys apply to the whole batch. Retry safely with the same key.
• The batch size limit is 100 emails; larger arrays return 422. Chunk bigger lists.

Sending to many people the same message?

Use broadcasts to an audience. They handle personalization, unsubscribe links and suppression for you.

Chunking helper

chunks.ts

import { SpacePost, type SendEmailOptions } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

export async function sendAll(emails: SendEmailOptions[], jobId: string) {
  for (let i = 0; i < emails.length; i += 100) {
    const chunk = emails.slice(i, i + 100);
    const { error } = await spacepost.batch.send(chunk, { idempotencyKey: `${jobId}-chunk-${i / 100}` });
    if (error) throw new Error(`${error.name}: ${error.message}`);
  }
}