Idempotency

Idempotency on the send endpoints is optional but strongly recommended: a retry with the same key never produces a second delivery, no matter how many times the request reaches us. Provide it either as the Idempotency-Key header or as an idempotency_key body field. If both are present, the header wins. Idempotency applies to the send endpoints, POST /v1/{channel}/send.

How

The first request with a given key is processed and its response stored. A replay returns the original response plus an X-Idempotency-Replay: true header. Subsequent requests with the same key:

• ...while the original is in flight: 409 idempotency_in_progress.
• ...after it completed with the same body: the original response (same status and body) with X-Idempotency-Replay: true.
• ...after it completed with a different body: 422 idempotency_mismatch.

What to use

A v4 UUID per logical operation is the easiest pattern:

curl https://api.dev.messagepipe.dev/v1/email/send \
  -H "Authorization: Bearer mp_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "to": "maya@example.com", "from": { "email": "hi@your-domain.com" },
        "subject": "Hi", "html": "<p>Hi</p>" }'

For higher-level operations (e.g. "send the order confirmation for order #12345"), use a stable deterministic key like order:12345:confirm so retries from any layer collapse safely.

Without an Idempotency-Key

The request is processed normally. Idempotency is optional, so omitting the key simply means a retry could produce a second delivery. Supply a key whenever a retry is possible.