Idempotency

Network calls fail in ambiguous ways: a timeout after POST /v1/messages leaves you unsure whether the message went out. Pass an idempotency_key on retry-prone callers and mailnix guarantees the send happens at most once per key.

How it works

Send idempotency_key (any string you choose, a UUID is typical) in the POST /v1/messages body, or the idempotency_key argument of the MCP tool email_send_test.
mailnix indexes the key per project for 24 hours. A retry with the same key returns the original trace_id without sending again.
The request body is hashed alongside the key. If a retry reuses a key with a different payload, the response carries a hint that the key matched an earlier, different request instead of silently returning a stale trace.

curl -X POST https://api.mailnix.ch/v1/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your order shipped",
    "text": "It is on the way.",
    "idempotency_key": "order-84315-shipped"
  }'

Derive the key from the business event ("order 84315 shipped"), not from the attempt, so every retry of the same logical send shares it.

Idempotent endpoints elsewhere

Beyond sends, several mutating endpoints are idempotent by design and safe to retry without a key:

POST /v1/suppressions upserts on (org, email)
DELETE /v1/suppressions/{id} and most other DELETEs
POST /v1/destinations/{id}/promote-to-live
email_scheduled_cancel(trace_id) on MCP

The REST error reference documents the standard error shape retries should inspect.