Skip to content

Request idempotency

Network errors and timeouts can leave you unsure whether a request reached Sender. If you retry a send that already went through, your recipient gets the same email twice. An idempotency key prevents that: send the same key with every retry, and Sender sends the email at most once.

EndpointDescription
POST https://api.sender.net/v2/message/sendSend transactional email (without template)
POST https://api.sender.net/v2/message/{id}/sendSend transactional campaign (with template)

Send the key in the Idempotency-Key header. It is optional, and requests without it work as before.

HeaderDescription
Idempotency-KeyA unique key for this email, up to 255 characters. Requests that use the same key within 1 hour send the email only once.
Terminal window
curl -X POST \
"https://api.sender.net/v2/message/send" \
-H "Authorization: Bearer [your-token]" \
-H "Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"from":{"email":"[email protected]","name":"Sender"},"to":{"email":"[email protected]"},"subject":"Your receipt","html":"Thanks for your order."}'

If you can’t set request headers, send the key as an idempotency parameter in the JSON or multipart/form-data body instead. If you send both, they must have the same value.

Use a value that identifies one email, such as a UUID you generate and store before the first attempt, or an ID from your own system (order-1042-receipt, password-reset-8812). Generate it once and reuse it on every retry of that email. Don’t create a new key per attempt, because a new key is a new email.

When a request carries a key, Sender checks it before doing anything else.

  • First request. The email is sent normally, and the response is stored under the key for 1 hour.
  • Retry after a successful send. The email is not sent again. You get the original response (same status code, message and emailId) with an extra header: Idempotent-Replayed: true. This works even if the request would fail today, for example because an attachment URL expired.
  • Retry while the first request is still running. The retry waits for the first request instead of sending in parallel, then returns its stored response with Idempotent-Replayed: true. If the first request is still running after 10 seconds, the retry gets 409 Conflict. Retry again later with the same key.
  • Retry after a failed send. Failures are not stored. If the original request returned an error (for example 400, 422 or a mailer error), fix the problem and retry with the same key, and the email is sent.
  • After 1 hour. The key expires and can be used again. Reusing it starts a new send.
HTTP/1.1 200 OK
Idempotent-Replayed: true
Content-Type: application/json
{
"success": true,
"message": "Email sent",
"emailId": "ep2W4y-7pn8o21-YPpLY9PR5Jy9-x7GYQ"
}

If the original email was queued, the replayed message is "Email queued", as in the original response.

Keys are scoped to your account. Another Sender account can use the same key without any effect on your emails.

Within your account, a key belongs to one request. A retry must send exactly the same request as the original: the same endpoint and transactional campaign, and the same parameters (recipient, subject, content, variables, headers and attachments). Only the key itself is left out of this comparison, so you can move it between the header and the body.

StatusMeaning
409Another request with this key is still being processed. Retry later with the same key.
422The key is longer than 255 characters, the header and the body parameter have different values, or the key was already used for a different request.
408 / 5xxThe request timed out or could not be completed. Retry with the same key: if the email was already sent, you get the stored response instead of a duplicate.

Idempotency errors use the standard error format with "type": "idempotency":

{
"success": false,
"type": "idempotency",
"message": "A request with this idempotency key is still being processed. Retry later with the same key."
}