Idempotency-Key header. mailkube processes each key at most once. A retry with the same key returns the original result instead of executing again. The header is honored on every write operation: sending, and canceling or rescheduling a scheduled email or batch.
Using an idempotency key
Send a unique key (a UUID is a good choice) with your request:202 with its scheduled_email acknowledgment.
Keys are remembered for 24 hours. After that window a key is forgotten and reusing it starts a new request.
Only successful responses (
2xx) are cached. If the first request fails, the key is released so you can retry it.Rules
- Generate a unique key per logical send. Reuse the same key only when you’re retrying that exact send.
- The key may be at most 256 characters; a longer key returns
400 invalid_idempotency_key. - Reusing a key with a different body returns
409 invalid_idempotent_request. The key is bound to the first payload it saw. - The comparison is over the raw request bytes. Re-serializing the same JSON with different key order or whitespace counts as a different body and gets the
409, so send the identical bytes when you retry. - Sending a request while another with the same key is still in flight returns
409 concurrent_idempotent_requests; wait for the first to finish before retrying.