Idempotency

Network failures happen. To safely retry a POST /emails request without risking a duplicate send, supply an Idempotency-Key header:

POST /emails
Authorization: Bearer am_YOUR_KEY
Idempotency-Key: order-12345-receipt
Content-Type: application/json

The key can be any string up to 256 chars. Most callers use a UUID or a stable business identifier (order-{id}-receipt).

Behavior

• First request with the key: processed normally, response cached for 24h.
• Retry with the same key + same body: returns the cached response (same id, same status, same timestamp). No new email is queued.
• Retry with the same key + different body: returns 409 Conflict to surface the inconsistency.

When to use it

• Webhook handlers in your app — retry-on-error is common.
• Cron jobs that may overlap.
• Anywhere a transient network error could cause a retry loop.

When not to bother

• One-off sends triggered by user actions where duplicate-prevention is not load-bearing.
• Campaign sends — the campaign dispatcher handles dedupe internally.

Window

Keys are remembered for 24 hours from the first request. After that, the same key can be reused without conflict.