Skip to main content
Concepts

Idempotency and sandbox

How to repeat a request without duplicating the email and how to test without really sending.

Idempotency

Send x-idempotency-key on POST /emails. If the same key arrives again within 24 hours, the API returns the same email instead of creating another. Use an id from your domain, such as order-4821-shipped.

The SDKs take the key as a send field (idempotencyKey) and turn it into the header.

POST /emails
curl -X POST https://api.coffeemail.com.br/v1/product/emails \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "x-idempotency-key: pedido-4821-enviado" \  -H "x-coffeemail-sandbox: true" \  -H "Content-Type: application/json" \  -d '{ "from": { "email": "pedidos@acme.com.br" }, "to": [{ "email": "ana@exemplo.com.br" }], "subject": "Teste", "html": "<p>Oi</p>" }'

Sandbox

With x-coffeemail-sandbox: true, the email goes through every validation and produces events, but is not delivered to the recipient. Use it for automated tests and development environments.

Test keys turn the sandbox on by themselves. The plan must include sandbox.