Retry strategies
Three different things can retry, and only two of them are automatic. Knowing which is which is the difference between a message that eventually arrives and one that sits still forever.
1. The mail server retries delivery
Once your message is handed to the mail server, it owns delivery. A temporary failure from the receiving side is retried on the server’s own schedule, for days, without involving you or us.
You do not configure this, and there is nothing to tune. A message in that state is working as intended, which is also why the platform deliberately leaves it alone rather than writing it off as unconfirmed.
2. We retry our own handoff, but only one failure
If our worker cannot reach the mail server before the message body is on the wire (connect, TLS or authentication failure), the message goes back on the queue and is tried again. That is safe precisely because nothing was transmitted.
Once the body has been sent, we never re-queue automatically, even if we never read the reply. The server may already hold a copy, and re-queueing would deliver twice. A duplicate receipt is worse than a delayed one.
3. We retry a refused submission, on a backoff
If the relay refused the message, we try again automatically: after 1 minute, 5, 15, an hour, then four hours. Five attempts over roughly five and a half hours, then it stops.
While a message is waiting for its next attempt it sits as queued, not
deferred, so a message in queued longer than you expect is usually one
being retried.
“Refused” is doing real work in that sentence. It means either an explicit
4xx reply at any stage, or a connection that dropped before the message
body went out. In both cases the relay demonstrably does not have a copy, so
another attempt cannot deliver twice.
4. Nothing retries an ambiguous failure
A message that exhausts its five attempts ends the same way, with a reason saying it gave up rather than just the last SMTP text.
So deferred now means “stopped, and somebody has to decide”, rather than
“stopped” covering both cases. Build for it:
- subscribe to
delivery.failedor pollGET /v1/messages?status=deferred; - decide whether the cause is fixed and whether a duplicate is acceptable;
- retry explicitly.
curl -X POST https://api.lockally.com/v1/messages/$ID/retry \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
POST /v1/messages/retry retries in bulk. Both need send:write, and both
reset the automatic attempt budget, so a message you retry by hand gets a
fresh five attempts rather than inheriting an exhausted counter.
What your own client should retry
Retry a 5xx from our API. That is us failing, not your request, and the
send did not happen. Exponential backoff with jitter.
Retry a 429, after the Retry-After header. Every 429 we return
carries one: 60 seconds for a rate cap, and the seconds remaining until UTC
midnight for a warm-up cap. Honour it rather than guessing.
Never retry a 400. The request is wrong and will be wrong next time.
Never blind-retry a timeout. You do not know whether we accepted it. Use an idempotency key and retry with the same key, which is exactly what it is for: a replay inside the window returns the original response instead of sending twice. See Idempotency.
const send = (body, key) =>
fetch('https://api.lockally.com/v1/send', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LOCKALLY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': key // the SAME key on every attempt
},
body: JSON.stringify(body)
});
What never to retry
A bounced message. The address was permanently rejected and is now
suppressed, so a retry is either skipped or is you asking to damage your own
reputation.
An unconfirmed message. It very probably arrived, and nothing recorded
it. Resending is a coin flip on sending a duplicate.
Summary
| Failure | Retried by | Automatic |
|---|---|---|
| Receiving server says 4xx | The mail server | Yes, for days |
| We cannot reach the mail server pre-transmission | Us | Yes, immediately |
| The relay refuses our submission (4xx, or a drop before the body) | Us | Yes, 5 attempts over about 5.5 hours |
| Submission fails ambiguously at or after the body | Nobody | No, status deferred |
| Retries exhausted | Nobody | No, status deferred |
| Our API returns 5xx or 429 | Your client | Only if you write it |
| Receiving server says 5xx | Nobody, by design | No |