A POST /v1/send timeout can leave an app unsure whether a receipt was sent or merely lost in transit. Good transactional email retry logic gives your team a way to recover without sending a second receipt or password reset by mistake. This guide lays out a retry policy, a queue-job shape, and a safe approach to ambiguous outcomes.
Retry only when the send was rejected or failed for a reason that may clear, such as throttling or a connection problem. Stop on permanent request errors, and treat a timeout after submission as unknown rather than as proof of failure. Persist jobs, use stable idempotency keys, follow provider retry guidance, and route exhausted or uncertain sends for review.
What transactional email retry logic should accomplish
Retries protect the handoff from your application to an email provider. If a worker cannot connect, or a provider explicitly rejects a request with a temporary error, your application can schedule another submission instead of losing a receipt, verification message, or password reset. Retries do not guarantee inbox placement, and they cannot fix an invalid address or an email rejected for its content.
Keep submission state separate from delivery state. Under RFC 5321, a positive final SMTP reply after message data means the receiving server accepted the message for delivery and took responsibility for it. Later bounces and complaints are delivery events, not proof that the initial submission failed. Acceptance also does not show whether the message reached an inbox or a spam folder.
That distinction gives each job a useful lifecycle: queued, submitting, accepted, retry scheduled, failed, or followed by a later delivery event. A retry policy should act on the submission outcome, while bounce and complaint handling updates delivery and recipient state.
Classify failures before retrying
Classify the actual response before scheduling another attempt. SMTP reply classes are useful, but an HTTP status class alone is not enough: the response body, provider guidance, and whether the request might already have been accepted all matter.
| Signal | What it indicates | Retry decision |
|---|---|---|
SMTP 4yz | RFC 5321 calls this a transient negative completion: the command was not accepted and may be tried again. | Usually schedule a retry, using the specific provider response to choose the delay. |
SMTP 5yz | A permanent negative completion; repeating the same request unchanged is discouraged. | Stop and correct the recipient, request, or configuration first. |
HTTP 429 | Rate limiting; the response may include Retry-After. | Delay according to Retry-After when supplied. |
HTTP 503 | Temporary unavailability or overload; it may include Retry-After. | Retry within a bounded policy if the outcome is not ambiguous. |
HTTP 400 or 403 | A malformed request or a refusal, rather than a generic temporary outage. | Do not repeat unchanged input or credentials automatically. |
HTTP 408, 502, or 504, or a network timeout | A request or upstream response timed out; acceptance may be uncertain. | Check idempotency and reconcile status before resubmitting. |
RFC 9110 says that a 4xx response indicates a client error, but whether a condition is temporary or permanent depends on the user agent and server. Likewise, not every 5xx is retryable: 501 Not Implemented indicates unsupported functionality, while 503 Service Unavailable may describe a temporary condition. A 429 response can include a Retry-After value expressed as seconds or an HTTP date (RFC 6585, RFC 9110).
Amazon SES offers a useful example of why the detail matters. Its SMTP 451 Temporary service failure means SES could not process the request; AWS says there might be issues with the request that prevent processing, so inspect the request instead of looping blindly. 451 Timeout waiting for data from client means too much time elapsed between requests and SES closed the connection. That points to client-side session timing as well as a transient reply (SES SMTP troubleshooting).
Choose a bounded backoff policy
Use exponential backoff to spread repeated attempts over time, add jitter to avoid synchronized retries, and set a maximum attempt count and an overall window. Treat provider-specified wait times as minimums: jitter may lengthen a requested delay, but should not cause your worker to retry earlier.
AWS gives a concrete SES SMTP example for requests receiving 400 errors: wait 5 seconds, then 10 seconds, then 30 seconds; if the third retry does not succeed, wait 20 minutes and repeat the process. That is SES guidance, not a universal interval for every temporary response. The following adds illustrative positive jitter and an application-level cap to that sequence:
| Retry | Example wait before retry |
|---|---|
| 1 | 5 seconds + random 0–2 seconds |
| 2 | 10 seconds + random 0–4 seconds |
| 3 | 30 seconds + random 0–10 seconds |
| 4, after the first cycle fails | 20 minutes + random 0–2 minutes, then begin another 5/10/30-second sequence |
In this example, stop after six retries or when the email is no longer useful, whichever comes first. The jitter ranges and cap are illustrative application choices, not AWS recommendations; the SES waits come from AWS’s SMTP troubleshooting guidance. For a password reset, for example, the token’s expiry may make further retries pointless. If a provider supplies Retry-After, schedule no earlier than that time, even if your normal backoff would be shorter.
Build retries around a durable queue
Persist a job before making the provider request. A worker claims it, records an attempt, submits the message, and either marks it accepted, schedules a retryable failure, or moves a permanent failure to a review state. Store available_at and attempt history durably so a process restart does not erase retry timing or reset the attempt count.
A compact job record might contain:
{
"job_id": "receipt:order_8472",
"recipient": "buyer@example.com",
"template": "receipt",
"status": "retry_scheduled",
"attempt_count": 2,
"available_at": "2026-11-11T12:05:10Z",
"last_error": "HTTP 429",
"provider_message_id": null,
"created_at": "2026-11-11T12:04:00Z"
}
Set the queue visibility timeout longer than the expected provider request duration. If it expires while the first worker is still submitting, a second worker can send the same job concurrently. Limit worker concurrency and sending rate, and pace retries separately from new work so a backlog does not cause a burst. For Amazon SES API or AWS SDK sends over account sending limits, AWS says to wait an interval of up to 10 minutes before retrying; SES SMTP can return 454 Throttling failure: Maximum sending rate exceeded. Save the delay in the queue instead of relying on an in-memory timer (SES sending quotas and errors).
For Volanea, the sending API documents POST /v1/send; its pipeline includes suppression checks, contact upserts, template rendering, tracking, and delivery. We do not publish a guaranteed internal retry schedule for SES throttling. If your app times out waiting for POST /v1/send, keep the job in an unknown-outcome state and reconcile available send records and event logs before replaying it. The pipeline’s suppression checks are not a substitute for your application’s idempotency key.
Prevent duplicate transactional emails
A timeout can happen after the provider accepted a message but before your application received the response. AWS says this can rarely happen with SES: a send request may return an error even though SES accepted the email, and retrying can create a second message with a different message ID (SES send process). Do not turn every lost response into a fresh job.
Create one stable key for each logical email, and use it to deduplicate requests before they enter the queue. Keep it unchanged across attempts; record attempt numbers separately. For example, receipt:order_8472 can identify the receipt for one order, while attempt_count records how many times the worker has tried to submit it.
key = "receipt:" + order_id
if job_store.has(key):
return existing_job(key)
job_store.insert(key, status="queued")
on_submission_timeout(key):
mark_unknown(key)
check_send_records_and_events(key)
if confirmed_not_accepted(key):
schedule_retry(key)
else:
hold_for_reconciliation(key)
An application-level key prevents duplicate queue jobs, but it cannot prove that an external provider did not accept a request. Record timestamps, responses, and any provider message ID for each attempt; reconcile uncertain sends before a manual replay. That restraint matters for a receipt that could be delivered twice or a password-reset email that could confuse a user with multiple links.
Handle exhausted retries and delivery events
Move jobs that exceed their attempt budget or useful lifetime to a dead-letter queue or failed-job store. Preserve the original job ID, recipient, attempt history, last error, and timestamps. Alert an operator with enough context to decide whether to correct the request, wait for provider recovery, or replay the job. A replay should retain the original logical ID and account for any uncertain acceptance.
Do not put bounces and complaints into the submission retry queue. Amazon SES retries soft bounces as post-submission delivery failures, but does not retry hard bounces except for DNS lookup failures; AWS advises against repeated attempts to hard-bouncing addresses. Complaints indicate that a recipient considered delivered mail to be spam, and AWS also advises against repeatedly sending to addresses that complain (SES deliverability guidance). Update delivery and suppression state instead of resubmitting the same message indefinitely.
Separate quota pauses from ordinary transient errors, too. Volanea offers 1,000 free emails per month, and when a monthly limit is reached sending pauses; there is no overage billing. A retry loop cannot create more available volume, so alert and hold eligible jobs rather than rapidly retrying them against the same limit.
Monitor and test the retry system
Track the complete path from job creation through submission and any later delivery event. At minimum, log the job ID, attempt count, response code, retry reason, next scheduled time, queue age, and final state. Monitor exhausted jobs and provider throttling alongside bounces and complaints, while keeping submission acceptance distinct from subsequent delivery outcomes.
Test failure paths deliberately, not only successful sends. A useful test matrix includes:
- A transient SMTP or HTTP response, such as SES throttling, schedules a later attempt.
- A permanent rejection, such as a malformed request, stops without an unchanged retry.
- A timeout after a possible provider acceptance marks the job unknown and avoids an immediate duplicate.
- Repeated application requests with the same idempotency key produce one logical job.
- A worker restart preserves queued jobs, attempt counts, and scheduled delays.
For a Volanea test environment, sk_test_ keys render and log requests but never deliver them. They can exercise request construction and application-side job handling, but not prove real delivery or bounce behavior. When testing the SMTP relay, the login username is volanea and the password is the project’s secret API key. Volanea’s send records, delivery, open, click, bounce, and unsubscribe statistics, plus event logs, can help investigate outcomes; queue age and application attempt history still come from your own worker.
FAQ
What should I do when POST /v1/send times out?
Keep the original job and idempotency key, mark its outcome unknown, and check available send records or event logs before replaying it. A timeout does not establish that Volanea or its underlying provider rejected the message. If you cannot resolve acceptance safely, hold the job for reconciliation rather than creating a new logical send.
What happens to queued sends when a Volanea monthly limit is reached?
Sending pauses at the monthly limit, and Volanea does not bill overages. A worker should stop tight retry loops, retain eligible jobs in durable storage, and alert the team. Resume them only when sending is available again and the message is still useful; expired password-reset links, for example, may need a newly generated message instead.
Can I test retries with a Volanea test key?
A sk_test_ key renders and logs requests but does not deliver email. Use it to test application behavior such as duplicate-job prevention, request formatting, and failure-state handling. It cannot validate inbox delivery, real bounces, or a recipient’s mail-server response; test those paths separately in an environment intended for actual delivery.
Build and exercise your queue with Volanea’s email platform, or see how AI coding agents can work with the Volanea API. Start free with 1,000 emails a month.