バッチ送信

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

ボディは最大 100 個のオブジェクトからなる JSON 配列で、各オブジェクトのフィールドはメールを送信すると同じです。バッチ送信は通信の往復を減らし、レート制限では 1 リクエストとして数えられます。

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" }
  ]
}

id は、入力した配列と同じ順序で返されます。

動作

• 全件成功か全件失敗のどちらかです。 配列内のメールが 1 通でも不正だと、リクエスト全体が validation_error で失敗し、何も保存されません。message には、どのメールかが示されます（(email 1)）。
• クォータのチェックは 1 回だけで、宛先の合計数に対して行われます。上限を超える場合は、バッチ全体が拒否されます。
• メールごとにすべての機能を指定できます: 添付ファイル、タグ、カスタムヘッダー、scheduled_at、tenant_id。一時停止中のテナントや上限を超えたテナントがあると、バッチ全体が失敗します。
• 冪等キーはバッチ全体に適用されます。同じキーで安全に再試行できます。
• バッチのサイズ上限は 100 通です。それより大きい配列は 422 を返します。大きなリストは分割してください。

同じメッセージを大勢に送りますか？

オーディエンスへの一斉配信を使ってください。パーソナライズ、配信停止リンク、送信停止の処理を代わりに行います。

分割用のヘルパー

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}`);
  }
}