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.
Supported endpoints
Section titled “Supported endpoints”| Endpoint | Description |
|---|---|
POST https://api.sender.net/v2/message/send | Send transactional email (without template) |
POST https://api.sender.net/v2/message/{id}/send | Send transactional campaign (with template) |
Sending a key
Section titled “Sending a key”Send the key in the Idempotency-Key header. It is optional, and requests without it work as before.
| Header | Description |
|---|---|
Idempotency-Key | A unique key for this email, up to 255 characters. Requests that use the same key within 1 hour send the email only once. |
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.
Choosing a key
Section titled “Choosing a key”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.
How it works
Section titled “How it works”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,
messageandemailId) 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 gets409 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,422or 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.
Replayed response
Section titled “Replayed response”HTTP/1.1 200 OKIdempotent-Replayed: trueContent-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.
Key scope
Section titled “Key scope”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.
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
409 | Another request with this key is still being processed. Retry later with the same key. |
422 | The 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 / 5xx | The 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."}