How does idempotency work?
Choose a unique string per logical send, for example an order number plus the message purpose, or a random UUID. If the same key is sent again by the same API key, the API does not send again. It replays the first response with HTTP 200 and the header Idempotent-Replayed: true.
curl -X POST "https://api.tuskmail.africa/v1/messages" \
-H "X-API-Key: $TK_API_KEY" \
-u "$MAILBOX_EMAIL:$APP_PASSWORD" \
-H "Idempotency-Key: order-1001-confirmation" \
-H "Content-Type: application/json" \
-d '{
"to": [
"[email protected]"
],
"subject": "Your order is confirmed",
"text": "Thanks for your order."
}'What are the rules?
- Keys can be up to 200 characters and are scoped to your API key.
- Stored results are kept for 24 hours.
- Only successful sends are remembered, so a request that failed can be retried with the same key.
- The key identifies the request; it does not compare the body. Never reuse a key for a different message.
When should I use it?
Always, for sends. Network timeouts leave you unsure whether a message went out, and an idempotent retry resolves that safely. See best practices.