A failed email request should not immediately become a failed signup. For an e-commerce account verification link, retry only failures that are plausibly temporary, use exponential backoff with jitter, and preserve an audit record for every attempt. The important output is not merely a delivered message. It is evidence that the system made a controlled decision about the signup and can explain that decision later.
I treat the retry queue as a small state machine. It receives a request, classifies the response, schedules at most a bounded number of attempts, and records the reason for each transition. That keeps deliverability work tied to revenue per hour: the system handles routine turbulence while I spend engineering time on cases that need judgment.
What should a retry prove?
The question is not “How many times should this call run?” It is “What evidence do we need before we stop trying?”
For signup verification, store an event ID, account ID, recipient hash, template revision, request timestamp, attempt number, outcome class, and next-attempt timestamp. Do not store the verification token in a general-purpose log. The event record should point to the token service or a protected token reference, while the email provider request gets a stable idempotency key when that interface supports one.
A timeout, connection reset, or HTTP 5xx can be temporary. A malformed address, an authentication failure, or a policy rejection is normally a configuration or input problem and should go to a visible failure path. Repeating it adds noise without adding evidence. The exact classification belongs to the API contract you use; the retry worker should not guess from a vague error string.
Keep it bounded.
SPF is part of the surrounding evidence, not a retry mechanism. RFC 7208 defines how a receiving system can evaluate whether an IPv4 or IPv6 address is authorized to send for a domain. A retry loop cannot repair an incorrect SPF policy, and sending the same request again will not turn a permanent authorization failure into a temporary one.
What are the best practices for retrying failed email API calls?
The implementation can stay boring. The delay grows from a base value, random jitter prevents a group of workers from waking together, and the cap prevents one poisoned event from occupying the queue forever.
type RetryableResult = {
kind: "retry" | "stop";
reason: string;
};
function retryDelayMs(attempt: number, baseMs = 1_000, capMs = 60_000): number {
const exponential = Math.min(capMs, baseMs * 2 ** Math.max(0, attempt - 1));
const jitter = Math.floor(Math.random() * Math.max(1, exponential * 0.2));
return exponential + jitter;
}
function classifyEmailFailure(status?: number, timedOut = false): RetryableResult {
if (timedOut || status === undefined || status >= 500) {
return { kind: "retry", reason: "transient transport or server failure" };
}
if (status === 408 || status === 429) {
return { kind: "retry", reason: "temporary request limit or timeout" };
}
return { kind: "stop", reason: `non-retryable response ${status}` };
}
The worker should persist the next-attempt timestamp before acknowledging the queue message. If the process dies between the provider call and that write, the event may be attempted again. That is why the event ID and idempotency key matter more than pretending the network offers exactly-once delivery. The record should distinguish “accepted by the email API” from “delivered to the mailbox”; those are different observations.
That distinction matters.
The first delay is 1 second in this example. It is a policy choice, not a law.
Here is the boundary I would test first: the API accepts the verification request, then the worker crashes before its database transaction commits. On restart, the outbox sees an unfinished event. A stable event ID lets the application correlate the second attempt; an idempotency key, when supported by the interface, can prevent the transport from creating a second request. If neither guarantee exists, the honest state is “delivery outcome unknown.” Marking it as delivered would create cleaner dashboards and worse compliance evidence. This is the kind of small failure window that makes retry design an audit problem as much as a networking problem.
Respect a provider-supplied Retry-After value when the API contract defines one. Otherwise, use a maximum attempt count and a maximum elapsed time. I prefer a short first delay for a signup flow, then a longer schedule that stops retrying before the verification experience becomes confusing. The product can offer a fresh link after expiry, but the old event should remain auditable.
How do you test the failure boundaries?
A happy-path test proves very little. Build a table of injected outcomes: timeout, connection reset, 408, 429 with a retry hint, 500, malformed input, authentication failure, and an accepted request followed by a worker crash. Assert the classification, the delay range, the attempt count, and the stored evidence. Test that two workers processing the same event do not create two active verification workflows.
The useful metric is not retry count by itself. Track attempts by outcome class, time from signup to accepted request, events moved to the terminal failure state, and the share of retries that end in acceptance. Keep recipient data out of general metrics. A daily review of these numbers can expose a broken sender policy or a new upstream failure pattern before support tickets become the monitoring system.
What changes at scale?
At higher volume, move scheduling out of the web process and make the outbox durable. Partition work by event ID, enforce a lease with an expiry, and make the terminal state explicit. Add a dead-letter view that an operator can inspect without editing the original evidence.
The trade-off is operational surface area. A queue, worker, metrics pipeline, and retention policy take time to own. For a one-person SaaS, I would ship the smallest durable state machine first, then outsource the undifferentiated transport plumbing to a standards-compatible component. I would not outsource the decision about what counts as evidence. That decision belongs with the signup and compliance requirements.
Do not optimize for the lowest email cost or the largest retry count. Optimize for a clear, bounded decision: the request was accepted, the attempt stopped for a recorded reason, or an operator has a precise next action. That is the artifact the business can defend.
Further reading
- RFC 7208: Sender Policy Framework (SPF): https://datatracker.ietf.org/doc/html/rfc7208
Top comments (0)