所需权限: subscribers
退信类型
| Type | Description | Action |
|---|---|---|
hard |
永久性投递失败（不存在的邮箱地址） | 立即取消订阅 |
soft |
临时性投递失败（邮箱已满等） | 连续3次后取消 |
complaint |
垃圾邮件举报 | 立即退订 |
GET
/api/v1/bounces
查询退信列表。
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit |
integer | 结果数量（默认: 20，最大: 100） |
offset |
integer | 分页偏移量 |
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
手动登记退信。
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
}
}邮件提供商Webhook
可以自动接收来自AWS SES、Mailgun、SendGrid等邮件提供商的退信通知。
Webhook URL
| 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设置
- 在AWS SNS中创建新的Topic。
- 为Topic添加HTTPS订阅:
https://dev.mailpass.im/api/v1/webhooks/ses - 在AWS SES中创建Configuration Set。
- 在Configuration Set中添加Event Destination并选择SNS Topic。
- 选择Bounce和Complaint事件。
退信处理策略
- • 发生Hard Bounce时，该订阅者将立即更改为'bounced'状态。
- • Soft Bounce连续发生3次后，将按Hard Bounce处理。
- • 发生垃圾邮件举报时，该订阅者将更改为'unsubscribed'状态。
- • 退信的邮箱地址将不再发送邮件。
最佳实践
- • 将退信率保持在5%以下。过高的退信率会对发信信誉造成负面影响。
- • 定期检查退信列表并清理无效的邮箱地址。
- • 使用Double Opt-in仅收集有效的邮箱地址。
- • 在收集邮箱地址时考虑进行实时验证。