Sending

Idempotency keys

Safely retry a send without sending twice using the Idempotency-Key header.

Network failures and timeouts make it hard to know whether a POST /emails actually succeeded. Pass an Idempotency-Key header so that retrying the same request is safe: MailBlastr processes the send once and replays the original response for any repeat of that key.

Idempotency keys are supported on both the POST /emails and POST /emails/batch endpoints.

Using a key

Generate a unique key per logical send and send it on the request. If you have to retry, send the same key. A key must be between 1 and 256 characters; a UUID is a good choice. A practical pattern is to derive the key from the entity the email is about, e.g. welcome-user/123456789 for a single send or team-quota/123456789 for a batch.

curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f3a9c1e-2b4d-4e6f-9a1b-c2d3e4f5a6b7' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@example.com"],
    "subject": "Receipt",
    "html": "<p>Thanks!</p>"
  }'

Replay behavior

First request — the send is processed and the response (the email id) is stored against the key.
Retry with the same key — the stored response is replayed with its original status code. No second email is sent.
Concurrent retry — if a second request with the same key arrives while the first is *still in flight*, it is rejected with 409 concurrent_idempotent_requests rather than risking a double send.

Idempotency keys are scoped per account and remembered for 24 hours. After that window the key is forgotten and reusing it processes a fresh send.

Possible responses

A successful response returns the email id (replayed unchanged on a retry). Otherwise you may get one of these errors:

Status	Error	Meaning
`400`	`invalid_idempotency_key`	The key is outside the 1–256 character range. Retry with a valid key, or without an idempotency key.
`409`	`invalid_idempotent_request`	This key was already used for a request with a different payload. Retrying is futile until you change the key or the payload.
`409`	`concurrent_idempotent_requests`	Another request with the same key is still in flight. Its original response isn’t available yet — it is safe to retry later.

A key only protects against duplicate *delivery* of the same intended email. Reusing a key for a genuinely different payload returns invalid_idempotent_request rather than replaying — always use a fresh key for a new send.