Reporting
Bounces
A bounce occurs when a recipient mail server refuses to accept a message. PostMTA categorizes bounces as hard or soft.
Hard vs Soft Bounces
| Type | Category | Auto-Suppressed |
|---|---|---|
| Hard | Permanent failure | Yes, immediately |
| Soft | Temporary failure | After 7 days of repeated failures |
Bounce Category Codes
| Code | Type | Description |
|---|---|---|
INVALID_RECIPIENT | Hard | Mailbox does not exist |
INVALID_DOMAIN | Hard | Domain has no MX or A record |
UNREACHABLE | Soft | DNS timeout, connection refused |
MAILBOX_FULL | Soft | Recipient mailbox at capacity |
CONTENT_REJECTED | Soft | ISP filtered the content |
Bounce Webhook Event
{"id":"evt_01HXABC123","event":"message.bounced","timestamp":"2026-01-15T10:32:00Z","data":{"message_id":"msg_01HX5K9P7N3M4Q6R8T2V4W6Y8","to":"nonexistent@example.com","bounce":{"type":"hard","category":"INVALID_RECIPIENT","code":"550 5.1.1 User unknown","bounced_at":"2026-01-15T10:32:00Z"}}}Bounce Rate Benchmarks
| Category | Good | Warning | Poor |
|---|---|---|---|
| Hard bounce rate | Less than 1% | 1-2% | Greater than 2% |
| Soft bounce rate | Less than 3% | 3-5% | Greater than 5% |
Soft Bounce Retries
PostMTA retries soft bounces automatically before permanently failing: 30min, 2hr, 8hr, 24hr, then 48hr before hard-bounce.