Design a Queue for Provider Rate Limits and Retry Safety
Design provider-aware retry queues with idempotency, backoff, quotas, dead letters, and clear handling for 4xx and 5xx outcomes.
Product & Engineering · September 25, 2026 · 2 min read
A safe email send queue treats provider feedback as a state transition, not a generic exception. Classify SMTP or API responses, apply provider-specific retry rules, and preserve enough evidence to explain every attempt.
Separate response classes
Use the SMTP error guide as a starting point, then map the actual provider response. A transient 4xx or quota signal may merit a delayed retry, but it is not permission to retry forever. A permanent 5xx, invalid recipient, authentication failure, or policy block generally needs correction or suppression rather than blind retry. Provider documentation and response text control the interpretation.
Make retries safe
Give each logical message a stable idempotency key. Store attempt number, provider response, next-attempt time, message identifier, recipient scope, and configuration version. Use bounded exponential backoff with jitter, but cap both attempts and total age. Honor provider quotas and per-stream rate limits. Separate a queue for scheduled retries from a dead-letter queue that requires review.
When a retry is accepted, record the provider event and reconcile it with sending observability. Avoid creating duplicate messages when a client timeout hides an accepted request. If the provider offers an idempotency facility, verify its documented scope; otherwise make the application decision explicit.
Escalate with evidence
Route exhausted retries to a dead-letter record containing raw response, timestamps, attempt history, configuration, and a safe replay decision. Do not replay permanently rejected recipients without fixing the cause. Alert on queue age, retry rate, quota responses, dead-letter growth, and missing provider events. The email infrastructure guide provides the system boundary around the queue.
Related resources
Use the Email Infrastructure academy for architecture context.
This workflow should be checked against the cited standards and current provider documentation 1.
Edge cases that change the design
A provider may impose separate limits by account, region, IP, domain, or message type. A retry queue that only has one global rate limiter can therefore starve one stream or overload another. Model the narrowest documented quota, expose queue age by stream, and pause a tenant or campaign without draining unrelated work. Keep recipient suppression decisions outside the retry loop so transient transport behavior cannot erase a permanent opt-out.
References
Resources in this guide
Frequently asked questions
Should every 4xx response be retried?
No. Classify the provider response and apply its documented behavior. Bound retries and escalate when the condition persists.
How do we prevent duplicate sends?
Use stable idempotency keys, persist provider identifiers, and handle client timeouts as ambiguous outcomes until provider evidence resolves them.
What belongs in a dead-letter queue?
The message or safe reference, recipient scope, response text, timestamps, attempt history, configuration version, and a decision about correction, suppression, or replay.
Continue learning
Review SMTP error handling
Continue with the closest operational guide.