배치 발송

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

본문은 최대 100개 객체로 이루어진 JSON 배열이며, 각 객체는 이메일 보내기와 같은 필드를 가집니다. 배치를 사용하면 왕복 횟수가 줄고, 요청 한도에서는 요청 한 건으로 계산됩니다.

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는 입력 배열과 같은 순서로 반환됩니다.

동작

• 전부 성공하거나 전부 실패합니다. 배열의 이메일 중 하나라도 유효하지 않으면 요청 전체가 validation_error로 실패하고 아무것도 저장되지 않습니다. message에 어느 이메일인지가 표시됩니다((email 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}`);
  }
}