What the dead letter queue is
When an email cannot be delivered, EuroMail retries it on a backoff schedule. If every retry is exhausted, or the failure is permanent, the email moves to the dead letter queue (DLQ) instead of being silently dropped. The DLQ is your safety net: nothing fails invisibly, and you get a chance to fix the cause and resend.
For the API surface, see the Dead Letters API reference.
Listing dead letters
curl "https://api.euromail.dev/v1/dead-letters" \
-H "X-EuroMail-Api-Key: em_live_your_key_here"Each entry includes the original message, the recipient, and the failure reason and timestamp. Common reasons:
| Reason | Meaning | Fix |
|---|---|---|
| Hard bounce | The mailbox does not exist. | The address is now suppressed; correct your data. |
| Repeated soft bounce | Mailbox full / temporarily unavailable through every retry. | Often resolves later. Retry. |
| Domain not verified | Sent from an unverified from domain. | Verify the domain, then retry. |
| Content rejected | The message tripped a content/spam gate. | Fix the content, then resend. |
Retrying
After fixing the underlying cause, requeue a dead letter for delivery from the
Dead Letters page in the dashboard, which
exposes a retry action per message (/dead-letters/{id}/retry). Retry is the
right move for transient failures (a mailbox that was full, a domain you have
since verified). It is the wrong move for hard bounces. The address is invalid
and is already suppressed.
Clearing
Dead letters you do not intend to retry can be deleted
(/dead-letters/{id}/delete) once you have recorded what you needed. Keeping the
DLQ tidy makes the genuinely actionable failures easy to see.
Monitoring the queue
The DLQ depth is exported as a Prometheus metric, so you can alert when failures accumulate rather than discovering them by chance. A sudden rise in DLQ volume is an early warning of a broken integration, an expired DKIM key, or a deliverability problem. Investigate it the same way you would a spike in bounces.
Designing for failure
- Treat a send as "accepted", not "delivered." The
202response means queued; final state arrives via webhooks. - Make sends idempotent with an
idempotency_key(see Sending Emails) so a retry after your own outage never double-sends. - Alert on DLQ depth so a class of failures surfaces immediately.