필요 권한: 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
}
}이메일 제공자 웹훅
AWS SES, Mailgun, SendGrid 등의 이메일 제공자에서 바운스 알림을 자동으로 수신할 수 있습니다.
웹훅 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을 사용하여 유효한 이메일만 수집하세요.
- • 이메일 주소 수집 시 실시간 검증을 고려하세요.