Idempotency

Add an Idempotency-Key header to your send request and Brixus365 will deduplicate retries automatically. The same key within a 24-hour window always returns the same response — and sends the email only once.

---

Why it matters

Network failures happen. When a POST /v1/emails request times out before you receive a response, you don’t know if the email was sent or not. Retrying without an idempotency key risks sending a duplicate.

With an Idempotency-Key:

• Brixus365 checks whether it has seen this exact request before.
• If yes, it returns the cached response — the email is not sent again.
• If no, it processes the request normally and caches the result.

This makes retries safe on password resets, receipts, and any other transactional email where a duplicate would be confusing or harmful.

---

How to use it

Add the header to any send request:

POST /v1/emails
X-API-Key: bx_live_yourkey
Idempotency-Key: order-1042-confirm-v1
Content-Type: application/json

{
  "to": "user@example.com",
  "subject": "Order confirmed",
  "template_id": "..."
}

The key must be:

• Unique per logical operation — one key per order confirmation, password reset, etc.
• Consistent across retries — the same key re-sent with the same body returns the cached response.
• Under 256 bytes.

---

Possible responses

Scenario	Response	Notes
First request — key is new	Normal 200 / 202 response	Email is sent. Result cached for 24 hours.
Retry — same key, same body, first request succeeded	200 with Idempotent-Replay: true header	Cached response returned. Email is NOT sent again.
Concurrent duplicate — same key, request still in progress	409 idempotency_in_flight with Retry-After: 5	Another request with this key is currently being processed. Wait 5 seconds and retry.
Key collision — same key, different request body	409 idempotency_key_mismatch	The key is already associated with a different request. Choose a new key for this request.
Retry of a failed request — same key, first request returned 4xx/5xx	New attempt processed normally	Failed responses are not cached. You can safely retry with the same key after fixing the error.

Check for the Idempotent-Replay: true response header to confirm a request was served from cache — useful for logging and debugging.

---

Choosing a good key

The key should uniquely identify the logical action, not the HTTP request. Recommended patterns:

# Order confirmation
order-{order_id}-confirm

# Password reset
password-reset-{user_id}-{timestamp}

# OTP
otp-{user_id}-{nonce}

# UUID v4 generated per operation (simplest)
8f14e45f-ceea-467a-a866-051f0f99e9b6

Avoid:

• Request-generated UUIDs on every retry attempt (defeats the purpose).
• Short or predictable keys like user-123 — they’re likely to collide across different operations.
• Timestamp-only keys — two rapid requests for different users could collide.

---

Supported endpoints

Idempotency keys are supported on send endpoints only:

Endpoint	Idempotency supported
POST /v1/emails	Yes
POST /v1/emails/batch	Yes
All other endpoints (GET, DELETE, etc.)	Not applicable — these are already idempotent by definition

---

Idempotency errors

Error code	HTTP status	Cause
idempotency_in_flight	409	A request with this key is currently being processed. The response includes Retry-After: 5 — wait and retry.
idempotency_key_mismatch	409	This key was already used with a different request body. Generate a new key for this operation.

---

What’s next

You want to…	Go to
See the full send request schema	Send email
Add files to your send request	Attachments
Understand all error codes	Error codes
See rate limits and quotas	Rate limits