API reliability
What are idempotency keys?
An idempotency key is a value you supply with a request to guarantee that retrying the same request never causes a duplicate action. For email, that means a network error, a timeout, or a retry loop can never send the same message twice. This guide explains how idempotency works, why it matters for transactional email, and how to use it in Rovela.
Network calls fail. A request times out, a pod restarts mid-send, your retry library fires twice — any of these can cause a second send if your email API does not protect against it. Idempotency keys are the standard way to solve this at the API layer.
The problem without idempotency
You call POST /emails, the request reaches the server, the server sends the message, and then the connection drops before the 200 response arrives. Your code sees a timeout and retries. Without idempotency, the server treats the second call as a new request and sends a second copy. The recipient gets two password-reset emails, two invoices, or two confirmation messages — a real support problem that is hard to diagnose after the fact.
How idempotency keys work
You generate a unique key — usually a UUID — for each logical send and include it as a request header. The server records the key when it processes the request. If the same key arrives again within the deduplication window (24 hours for Rovela), the server returns the original response without taking any action. From the caller's perspective, the request succeeded; no duplicate was sent.
Generating the right key
The key must be unique per logical send, not per HTTP request. Generate it once, before any retry loop, and use the same value on every attempt for that logical operation. A common mistake is generating a new UUID on each retry — that defeats the purpose entirely. Tie the key to the entity: a hash of the order ID plus event type works well for order confirmations; a random UUID generated once at the start of the send flow works for one-off messages.
What Rovela returns on a duplicate
When Rovela receives a request with a key it has already processed, it returns HTTP 200 with the original response body, including the original message ID. Your code sees a success and can safely record the message ID. The recipient received exactly one message. Rovela's deduplication window is 24 hours; keys older than that are expired and a new send will go through.
When to omit the key
Omit the key only when you deliberately want to allow duplicates — for example, a user clicking a resend button should generate a new key so the message actually goes out again. Most transactional sends should include a key. Bulk marketing sends usually do not need idempotency because they are not retried in the same way as transactional calls.
Common questions
- Is an idempotency key the same as a message ID?
- No. The message ID is assigned by Rovela after the message is accepted; it identifies the message in logs and webhooks. The idempotency key is supplied by the caller before the message is sent; it identifies the logical send operation for deduplication. You supply the key; Rovela returns the ID.
- What format should the key be in?
- Any string up to 256 characters works. A UUID v4 is the conventional choice because it is collision-resistant and widely available in every runtime. Do not use values that repeat across sends, such as a recipient address or a timestamp alone.
- Does the key work across different API keys?
- Yes, within the same organization. Rovela's deduplication is scoped to the organization, not the individual API key. Two requests made with different API keys that belong to the same organization share the same deduplication space, so the same idempotency key prevents a duplicate regardless of which key sent the request. Keys from different organizations are always independent.
- What happens if the key collides accidentally?
- Rovela returns the original response rather than sending a new message. If you accidentally reuse a key for a genuinely different send, that second send will be silently deduplicated. Generate keys with sufficient entropy — a UUID v4 has 122 bits of randomness, making accidental collision essentially impossible.