Email queues and retries: how to never lose a message
What happens when a mail server is down or slow? How queues, backoff and safe retries keep transactional email from vanishing or being sent twice.
Mail servers go down. Networks hiccup. A relay restarts in the middle of your signup rush. None of that should mean a lost receipt, and it shouldn't mean two copies of one either.
Getting this right comes down to one question: when sending fails, do you know whether the message went? If you do, you can retry confidently. If you don't, retrying is a gamble.
Three kinds of failure
1. It definitely did not go
The connection was refused. DNS lookup failed. The login was rejected. The server answered with a temporary error (the 4xx class). In all of these the mail server never accepted the message. Retrying is safe, and it's what a queue is for.
2. It definitely failed for good
A permanent error, the 5xx class: the address doesn't exist, the sender is refused, the message is rejected as spam. Retrying won't help. Report the failure so someone can act.
3. You don't know
The connection broke after the message body was sent but before the server confirmed. The server may have accepted it, or it may not. This is the dangerous case. Retrying risks a duplicate, and doing nothing risks a loss.
A sensible system treats the three differently. It retries the first, fails the second immediately, and marks the third as unknown instead of retrying blindly.
What Mailions does
When the mail server can't take a message right now, the API answers 202 with status: queued and keeps the message safely stored. A background worker sends it as soon as the server is back, retrying with growing pauses, for up to 24 hours. If it's finally given up on, the log shows failed and the monthly allowance is returned.
Only failures of the first kind are queued. A permanent rejection fails at once. A hand-off that was interrupted after the body went out is reported as unknown and is never retried automatically, so nobody gets duplicates. For that status, contact support with the returned ID before you resend.
You can ask what happened at any time:
GET /api/v1/emails/<id>
Authorization: Bearer YOUR_API_KEY
The reply carries the current status. Webmail sends are queued the same way, with a "Message queued" notice instead of an error.
One deliberate exception: password-reset links are never queued, because they carry a secret and go stale quickly. If sending fails, the person is told and can try again. We explain the reasoning in password reset email security.
Designing it yourself
If you send through SMTP or write your own queue, these rules carry over.
Decouple sending from the user request. Put a job in a database table or a queue, return immediately, and let a worker do the send. The user doesn't wait, and a mail outage doesn't break your page.
Use the outbox pattern for important mail. Write the "send this email" row in the same database transaction as the change that caused it (the order, the account). A worker reads unsent rows and sends them. Either both happen or neither does, so you never confirm an order without queuing its receipt.
Back off between attempts. Retry after 30 seconds, then a few minutes, then longer, with a little random jitter so a thousand stuck jobs don't all retry in the same second.
Put an age limit on it. Giving up after a day is reasonable for most mail. For a login code, give up after minutes. A code that arrives late is useless.
Pause when the relay is down. If every attempt fails with connection errors, stop hammering. A circuit breaker that pauses the worker until one probe succeeds saves load and noise.
Record the outcome. Keep the status, the time and the error. When someone says "I never got the email", you can answer.
Make retries safe with keys
A queue without duplicate protection turns outages into double emails. Give each message a stable identifier and send it as an Idempotency-Key, so a retry can't create a second copy. The full approach is in idempotency keys for email APIs.
What a queue can't fix
- Bad addresses. A typo bounces however well you retry.
- Authentication problems. If SPF or DKIM are broken, the message is accepted and then junked.
- Time-sensitive mail. Codes need speed more than persistence.
- Receiver-side delays. After the message leaves, the other provider decides whether and when to deliver it.
Checklist
- Sending runs in the background, not in the request
- Retries only for failures where nothing was accepted
- Unknown outcomes are flagged for a human
- Exponential backoff with jitter
- An age limit suited to each message type
- A stable idempotency key on every message
- A status you can look up later
For where this fits in the bigger picture, see SMTP vs email API. To send with a queue behind you, read the API guide and contact us.
Frequently asked questions
Why do emails need a queue?
Mail servers and APIs are sometimes briefly unavailable. Without a queue, a message that fails at that moment is lost or the user sees an error. A queue stores it and retries with growing pauses until it is accepted or clearly cannot be sent.
How long should an email be retried?
Mail servers retry for days, but application mail is time-sensitive, so a few hours to a day is typical. Sign-in codes and password-reset links lose their value quickly and are better failed visibly than delivered late.
Can retrying an email cause duplicates?
Yes, if the first attempt was accepted but the reply was lost. Retry only failures where the message clearly was not taken, and send an idempotency key so a repeated request returns the original result instead of sending again.