POST /emails/batch
Send a batch of emails
1 to 100 messages, each tracked by its own job; the idempotency of each message derives from the batch's Idempotency-Key and its position. Atomicity covers only the initial registration of all the jobs: it guarantees neither their joint execution nor their joint delivery. A replay requires the same key and exactly the same ordered list; any addition, removal or reordering returns 409. No attachments in batches.
API key (Bearer), on the public API endpoint.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string · required |
Request body
application/json · schema MailBatch
| Field | Type | Description |
|---|---|---|
emails | array<any> · required |
Responses
| Status | Description | Body |
|---|---|---|
202 | Atomic registration of the batch: one job per message, in order; execution and delivery remain independent | EmailBatchResponse |
400 | content_length_invalid, body_invalid or idempotency_key_invalid | |
401 | Key missing or invalid | Error |
403 | scope_missing, test_key_not_allowed, live_key_not_allowed, mail_key_restriction_unreadable, mail_sender_not_allowed or mail_key_domain_mismatch | |
404 | not_found (service not opened) | |
409 | idempotency_conflict: same key with a different list (content, size or order) | |
413 | body_too_large (more than 8 MiB) | |
422 | Invalid parameters | Error |
429 | mail_budget_exceeded | |
503 | mail_route_unavailable, mail_unavailable or job_projection_invalid | Error |
Examples
curl
curl -X POST "$GALON_API_BASE/emails/batch" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Idempotency-Key: <unique-key>" \
-H "Content-Type: application/json" \
-d '{"emails": []}'Node.js (SDK)
import { Galon } from "galon";
const galon = new Galon(process.env.GALON_API_KEY);
const result = await galon.batch.send({"emails": []}, { idempotencyKey: "<unique-key>" });Python (SDK)
from galon import Galon
galon = Galon() # reads GALON_API_KEY
result = galon.batch.send({"emails": []}, idempotency_key="<unique-key>")