Skip to main content
Network calls fail halfway. To retry a write without repeating its effect, attach an 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:
The first request runs normally. Any later request with the same key and the byte-identical body short-circuits and returns the original response verbatim, with an extra header:
The replay preserves the original status code. A scheduled send replays as 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.
See Errors for the full envelope and every code.