Email Queue

How the persistent retry queue and dead-letter queue work.

When an email cannot be delivered on the first attempt, it enters the PlatformXe persistent retry queue. The queue uses exponential backoff to retry delivery without overwhelming downstream providers.

Backoff schedule

Attempt	Delay
1	Immediate
2	30 seconds
3	1 minute
4	2 minutes
5	5 minutes
6	15 minutes
7	30 minutes
8	1 hour

After 7 retry attempts (8 total attempts including the first), the email moves to the dead-letter queue and is no longer retried automatically.

Dead-letter queue

Emails in the dead-letter queue have exhausted all retry attempts. These typically indicate a persistent issue such as:

• Invalid recipient address (hard bounce)
• Recipient mailbox full (soft bounce that never resolved)
• All providers in the fallback chain are down for an extended period

Queue statistics

Retrieve current queue stats to monitor delivery health.

GET /api/v1/messaging/queue/stats

Scope: messaging:send

Response

{
  "success": true,
  "data": {
    "pending": 12,
    "retrying": 3,
    "deadLettered": 1,
    "processedLast24h": 4821
  }
}

Field	Description
pending	Emails waiting for first delivery attempt
retrying	Emails in the retry backoff cycle
deadLettered	Emails that exhausted all retries
processedLast24h	Successfully delivered in the last 24 hours

Manual queue processing

Trigger queue processing manually, useful after resolving a known provider outage.

POST /api/v1/messaging/queue/process

Scope: messaging:send

Response

{
  "success": true,
  "data": {
    "processed": 15,
    "failed": 2,
    "remaining": 0
  }
}