Idempotency

POST requests accept an optional Idempotency-Key header to safely retry operations without creating duplicate resources.

How it works

When you include an Idempotency-Key header on a POST request, the API caches the response for 24 hours. If you send the same key with the same body again, you get the cached response back. The operation only runs once.

Key format

Max 255 characters.
Printable ASCII only (space through tilde).
UUIDs work well as idempotency keys.

Example

curl -X POST https://shipmail.to/api/v1/domains \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"name": "example.com"}'

Cached responses

When the API returns a cached response from a previous idempotent request, it includes an Idempotency-Replay header set to true. Check this header to distinguish between a fresh response and a replay.

HTTP/1.1 200 OK
Content-Type: application/json
Idempotency-Replay: true
X-Request-Id: req_abc123

{ ... }

The header is absent on the original (non-cached) response. It only appears on subsequent requests that match an existing idempotency key.

Conflict

If you reuse the same key with a different request body, the API returns a 409 Conflict error. Generate a new key for each distinct operation.