IvyMail automatically processes bounces and complaints to protect your sender reputation. When an email bounces or a recipient complains, IvyMail updates your logs, adds the address to your suppression list, and blocks future sends to that address.
How it works
- You send an email via
POST /v1/send. - SES attempts delivery.
- If the email bounces or the recipient complains, SES fires an event notification.
- IvyMail's webhook processor:
- Creates a bounce/complaint log entry
- Updates the original send log status to
bouncedorcomplained - Adds the recipient to your workspace's suppression list
Suppression list
The suppression list is per-workspace. When you call POST /v1/send, IvyMail checks each recipient against the list before sending. Suppressed addresses are logged with status: suppressed and never reach SES.
This protects your sender reputation and prevents wasted API calls.
Bounce types
| Type | Description | Action |
|---|---|---|
| Permanent (hard bounce) | Address doesn't exist or is permanently undeliverable | Added to suppression list immediately |
| Transient (soft bounce) | Mailbox full, server temporarily unavailable | Not suppressed. Retry is allowed |
Complaint types
| Type | Description |
|---|---|
| Abuse | Recipient clicked "Report Spam" in their email client |
| Fraud | Recipient reported the email as fraudulent |
All complaint types result in immediate suppression.
Viewing suppressed addresses
Check your suppression list in Dashboard → Logs by filtering for type: bounce or type: complaint.
Removing addresses from suppression
If an address was suppressed in error (e.g. a temporary issue resolved), you can remove it from the suppression list in the dashboard. Be cautious; sending to previously bounced addresses can harm your sender reputation.
Best practices
- Clean your lists: Remove invalid addresses proactively rather than waiting for bounces.
- Use double opt-in: Verify email addresses before adding them to your sending lists.
- Monitor bounce rates: A bounce rate above 5% triggers throttling (10 emails/hour) and above 10% pauses all sending. See Sending Limits & Safety for full reputation thresholds.
- Include unsubscribe links: Make it easy for recipients to opt out instead of marking your email as spam.
- Always send a text fallback: Some spam filters flag HTML-only emails.
For AI agents & LLMs
If you're an AI agent, check for suppressed recipients before retrying failed sends:
# Check recent bounces
curl "https://api.ivymail.io/v1/send/logs?type=bounce&limit=20" \
-H "x-api-key: $IVYMAIL_API_KEY"
# Check send stats for bounce rate
curl "https://api.ivymail.io/v1/send/stats" \
-H "x-api-key: $IVYMAIL_API_KEY"If a send returns "status": "suppressed", the recipient is on the suppression list. Do not retry. Inform the user that the address previously bounced or complained.