
When a send request times out, the email service may have received it even though your app missed the response. Record the outcome as unknown. If you retry the same send, use the same request body and the same idempotency key. Save the provider’s message ID when you receive it so you can check the status later.
Give each intended email a stable key
Suppose a store needs to send one order confirmation for order 84721. Create a job with a key such as order-84721-confirmation before the first request. Save the key with the job and keep the request data needed to retry it. If a worker restarts after a timeout, it can load the original key and submit the same request.
An intentional shipment notification for the same order is a separate message and can have its own key, such as order-84721-shipped. An attempt number or the current time would change the key on each retry and defeat the purpose.
EmailMassivo calls the request field idempotencyKey and recommends supplying it for retries after timeouts or network errors. A successful response returns a uuid for tracking the message. EmailMassivo API documentation
Decide what to do with the response
| What your app sees | What to do |
|---|---|
| Timeout or connection failure with no response | Keep the outcome unknown. Retry the same request with the saved key under a bounded retry policy. |
| 200 OK with a UUID | Save the UUID and stop retrying the send. Track message status with that ID. Verify delivery separately. |
| 429 | Wait for the interval indicated by Retry-After before retrying with the same key. |
| 503 | Retry later with the same key. Stop after the attempt limit and flag the job for review. |
| 400, 401, 403, or 404 | Read the error details and correct the request, credentials, permissions or configuration as appropriate. |
| 402 | Check the available balance or sending allowance before trying again. |
| 422 | Inspect the reason. An unsubscribed recipient, a complaint or an unavailable address needs handling before any further send. |
The status codes in the table follow EmailMassivo’s documented responses. Before relying on a delayed retry, confirm how long your provider retains idempotency keys and where they apply. If you cannot establish whether the original key still protects the send, review the provider’s records before trying again.
Test a lost response in a controlled inbox
- Create a test order and recipient. Use an existing test mailbox your team owns. Save one job and its key.
- Simulate a lost response in staging. Let the first request reach the API and simulate a worker failure before it saves the answer. Confirm that the original job remains available for retry.
- Retry the same job. Check the saved key and payload before sending. Look for one logical send in the provider’s records and check the test mailbox once delivery completes. Capture the UUID if the API returns it.
- Check the stopping condition. Simulate repeated failures. Verify that the worker stops at its configured limit. Log the job reference, response status and UUID when available. Keep API credentials out of logs.
For initial setup and request examples, see the guide to sending transactional email through an API.