Required permission: subscribers
Bounce Types
| Type | Description | Action |
|---|---|---|
hard |
Permanent delivery failure (non-existent email) | Immediately unsubscribe |
soft |
Temporary delivery failure (mailbox full, etc.) | Unsubscribe after 3 consecutive occurrences |
complaint |
Spam complaint | Immediately unsubscribe |
GET
/api/v1/bounces
Retrieves a list of bounces.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit |
integer | Number of results (default: 20, max: 100) |
offset |
integer | Pagination offset |
Response
{
"success": true,
"data": {
"bounces": [
{
"id": 1,
"email": "invalid@example.com",
"bounce_type": "hard",
"bounce_subtype": "NoEmail",
"source": "ses",
"campaign_name": "January Newsletter",
"subscriber_name": "John Doe",
"created_at": "2026-01-10T12:00:00Z"
}
],
"total": 50,
"limit": 20,
"offset": 0
}
}
POST
/api/v1/bounces
Manually reports a bounce.
Request Body
{
"email": "invalid@example.com",
"bounce_type": "hard", // hard, soft, complaint
"bounce_subtype": "NoEmail", // optional
"diagnostic_code": "550 5.1.1..." // optional
}Response
{
"success": true,
"data": {
"bounce_id": 123
}
}Email Provider Webhooks
You can automatically receive bounce notifications from email providers such as AWS SES, Mailgun, and SendGrid.
Webhook URLs
| Provider | Webhook URL |
|---|---|
| AWS SES (SNS) | https://dev.mailpass.im/api/v1/webhooks/ses |
| Mailgun | https://dev.mailpass.im/api/v1/webhooks/mailgun |
| SendGrid | https://dev.mailpass.im/api/v1/webhooks/sendgrid |
AWS SES Setup
- Create a new Topic in AWS SNS.
- Add an HTTPS subscription to the Topic:
https://dev.mailpass.im/api/v1/webhooks/ses - Create a Configuration Set in AWS SES.
- Add an Event Destination to the Configuration Set and select the SNS Topic.
- Select Bounce and Complaint events.
Bounce Handling Policy
- • When a Hard Bounce occurs, the subscriber is immediately changed to 'bounced' status.
- • If a Soft Bounce occurs 3 consecutive times, it is treated as a Hard Bounce.
- • When a spam complaint occurs, the subscriber is changed to 'unsubscribed' status.
- • Emails will not be sent to bounced email addresses.
Best Practices
- • Keep your bounce rate below 5%. A high bounce rate negatively impacts your sender reputation.
- • Regularly review the bounce list and clean up invalid emails.
- • Use Double Opt-in to collect only valid emails.
- • Consider real-time email address validation during collection.