Idempotency
Add an Idempotency-Key header to a POST, PATCH or PUT request, and you can retry it without creating a duplicate. The header is optional.
Last updated
One-time secrets are excluded
Mailbox app-password creation and the two upload-token endpoints (staged attachments and newsletter assets) reject Idempotency-Key. Each one returns a credential only once. If you lose the response, ask for a new credential instead of replaying the request. Revoke the app password you never received, and let an unused upload token expire after 5 minutes.
Webhook creation and webhook secret rotation accept the header. A retry with the same key within 24 hours returns the same signing secret and does not rotate it again. Shipmail stores that response encrypted.
How it works
Send an Idempotency-Key header on a request that changes something, and the API keeps the response for 24 hours. Send the same key with the same method, path and body again, and you get that stored response back. The operation does not run a second time. If the first request is still running, the retry gets 409 Conflict with a Retry-After header. Wait that long, then send the same request with the same key.
Key format
- Max 255 characters.
- Printable ASCII only (space through tilde).
- A UUID makes a good key.
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
A stored response sent back for a repeated key carries an Idempotency-Replay header set to true. Check it to tell a replay from a fresh response.
HTTP/1.1 200 OK
Content-Type: application/json
Idempotency-Replay: true
X-Request-Id: req_abc123
{ ... }The first response never has this header. Only later requests with the same key get it.
Conflict
Reuse a key with a different request body and the API returns 422 with error type conflict. Use a new key for each operation.
Message sends after 24 hours
A message send (POST /v1/messages and the reply endpoints) also uses the key to derive the message's ID, together with the method, path, organization and API key. So after the 24-hour response cache expires, a retry with the same key on the same endpoint still returns the message already sent, with status 201 and no Idempotency-Replay header, for as long as that message exists. Shipmail does not compare the body at that point, so a changed body sends nothing new. Use a new key for each new message.