Transactional Email Bounces
Handle hard bounces, soft bounces, delayed bounces, complaints, and suppressions for transactional email.
TL;DR
A hard bounce should usually suppress the recipient. A soft bounce should be retried according to provider policy. Delayed bounces can arrive after SMTP acceptance, so final state must come from webhooks or bounce processing, not the initial send response.
What you will learn
- Distinguish hard, soft, and delayed bounces
- Update application state from delivery webhooks
- Prevent repeat sends to bad recipients
Bounce types
| Type | Meaning | Typical action |
|---|---|---|
| Hard bounce | Permanent failure, such as invalid address | Suppress recipient |
| Soft bounce | Temporary failure, such as mailbox full | Retry or defer |
| Delayed bounce | Failure reported after initial acceptance | Update final state from webhook |
| Complaint | Recipient marked as spam | Suppress and investigate |
The exact classification can vary by receiving server and provider. Store the raw status code and provider reason for audit.
Why bounces arrive late
SMTP is a relay protocol. A provider can accept a message, then later learn that the receiving system rejected it. That final failure can arrive minutes or hours later.
Your application should not mark a message as delivered from the send API response alone. Use delivery events and bounce webhooks.
Application states
Use explicit states:
queuedaccepteddelivereddeferredbouncedcomplainedsuppressed
Keep delivered separate from accepted. A reset token, login link, or receipt may be created before delivery, but support and analytics need the final delivery state.
Suppression rules
Suppress immediately for:
- Invalid mailbox hard bounces.
- Spam complaints.
- Manual unsubscribe or legal opt-out.
- Known abusive or role-based addresses if your policy forbids them.
Be careful with:
- Mailbox full.
- Temporary policy deferrals.
- Greylisting.
- DNS or routing failures.
- Provider throttling.
For those, retry and watch repeated failures before suppressing.
Migration checklist
Before moving providers:
- Export hard bounces.
- Export spam complaints.
- Export unsubscribes.
- Export manual suppressions.
- Preserve the reason and timestamp.
- Import suppressions before first production sends.
- Keep old webhooks active until delayed events drain.
This is one of the highest-value steps in a provider migration. Missing suppressions can recreate failures you already paid to learn about.
References
Frequently asked questions
- Does an API accepted response mean the email delivered?
- No. Accepted means the provider accepted the message. Delivery can still fail later and arrive as a bounce or defer event.
- Should password reset emails suppress on every bounce?
- Suppress on hard bounces and complaints. Treat temporary or ambiguous bounces more cautiously so a transient mailbox issue does not lock a real user out forever.
Related guides
Put the guide into production
Postscale brings sending, inbound processing, DMARC reporting, and masked addresses behind one API so the operational pieces stay connected.