Bounce and Complaint Handling
Relay processes bounces and complaints in real-time via SES webhooks. Understanding how these events work is critical to maintaining a healthy sender reputation and staying within SES compliance thresholds.
How Bounces Work
When an email can't be delivered, the receiving mail server sends a bounce notification back to SES, which forwards it to Relay via SNS webhook.
Bounce Types
| Type | Severity | Auto-Suppress | Examples |
|---|---|---|---|
| Permanent (Hard) | High | Yes | Invalid address, domain doesn't exist, address rejected |
| Transient (Soft) | Low | No | Mailbox full, server temporarily unavailable, message too large |
Hard bounces immediately suppress the recipient address. Soft bounces are retried by SES automatically (up to 3 attempts over several hours).
Bounce Sub-Types
Hard bounces include a sub-type with more detail:
General— Address is invalidNoEmail— Recipient address doesn't accept emailSuppressed— SES account-level suppression (address previously bounced across your SES account)OnAccountSuppressionList— Address is on the SES global suppression list
How Complaints Work
A complaint occurs when a recipient marks your email as spam in their email client. The ISP sends a feedback report to SES via feedback loops, which Relay processes.
Complaints are serious. They indicate the recipient didn't want the email. Relay automatically:
- Adds the address to your suppression list with reason
complaint - Updates the email log status to
complained - Emits a
relay.email.complainedBus event
SES Compliance Thresholds
Amazon SES enforces strict sending reputation requirements:
| Metric | Threshold | Consequence |
|---|---|---|
| Bounce rate | Below 5% | Above 5% triggers a review; above 10% risks suspension |
| Complaint rate | Below 0.1% | Above 0.1% triggers a review; above 0.5% risks suspension |
Relay helps you stay within these thresholds through automatic suppression, bounce rate alerts, and analytics monitoring.
Bounce Rate Alerts
Relay checks your bounce rate every hour. If your 24-hour bounce rate exceeds the configured threshold (default: 5%), Relay:
- Emits a
relay.alert.bounce_rateBus event - Sends an alert to your configured notification email (if set in Settings)
Configuring the Threshold
- Go to Settings (gear icon)
- Set the Bounce Rate Threshold (default: 5%)
- Enter an Alert Email address for notifications
- Optionally enable Daily Digest for a summary of all bounces and complaints
What Happens When an Email Bounces
- SES sends a bounce notification to the SNS topic
- Relay's webhook handler receives the event
- The email log is updated: status →
bounced, bounce type and sub-type recorded - If it's a hard bounce, the recipient is added to the suppression list
- Daily stats are updated (bounce count incremented)
- If the 24-hour bounce rate exceeds the threshold, an alert fires
Reducing Bounces
Clean your lists. Remove addresses that haven't engaged in 6+ months. Old addresses frequently become invalid.
Verify addresses before sending. If a client provides a new contact list, send a small test batch first to gauge bounce rates.
Monitor the dashboard. Check the bounce rate trend in Analytics weekly. A rising trend indicates a list quality problem.
Use double opt-in. For any subscription-based emails, require recipients to confirm their address.
Check suppression list exports. Review the reasons column. If you see a pattern (many bounces from one domain), the client's mail server may be blocking you.
Reducing Complaints
Include an unsubscribe link. Even for transactional email, an unsubscribe option reduces complaints.
Set clear expectations. Only send what recipients expect to receive. A ticket update notification is expected; a marketing upsell is not.
Identify your sender clearly. Use a recognizable From name and address so recipients know who the email is from.
Don't send to cold lists. Addresses that haven't received email from you in months are more likely to mark unexpected emails as spam.