必要な権限: 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を使用して有効なメールアドレスのみを収集してください。
- • メールアドレス収集時にリアルタイム検証を検討してください。