제대로 작동하는 이메일 검증 API

인증

모든 요청에서 API 키를 Authorization 헤더의 Bearer 토큰으로 보내세요. 키는 서버에 보관하고, 브라우저 코드나 모바일 앱에는 절대 넣지 마세요.

Authorization: Bearer YOUR_API_KEY

모든 엔드포인트의 기본 URL은 https://bouncebell.com/api/v1입니다.

주소 하나 검증

GET https://bouncebell.com/api/v1/verify

예시

curl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth%40acme-foods.example" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "rini.elizabeth@acme-foods.example",
  "status": "valid",
  "reason": "mailbox_exists",
  "domain": "acme-foods.example",
  "mx_record": "mx1.acme-foods.example",
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "did_you_mean": null,
  "checked_at": "2026-10-30T09:30:12Z",
  "credits_used": 1
}

결과 필드

상태

배치

요청 한 번에 최대 100,000개의 주소를 보낼 수 있습니다. 배치는 백그라운드에서 실행됩니다. 상태를 폴링하거나 callback_url을 지정하면 배치가 완료될 때 해당 URL을 호출합니다.

배치 생성

POST https://bouncebell.com/api/v1/batches

curl -X POST "https://bouncebell.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October import", "emails": ["a@example.com", "b@example.com"],
       "callback_url": "https://yourapp.example/hooks/bouncebell"}'

{ "id": "bat_8f2k1q3m9x7w4p", "status": "queued", "total": 2, "done": 0 }

배치를 생성할 때 고유 주소마다 크레딧이 예약되고, 완료 시 알 수 없음 결과에 대한 크레딧은 환불됩니다. 콜백은 {"event": "batch.completed", "batch_id": "...", "status": "done", "counts": {...}}가 담긴 POST를 받습니다. 콜백 URL은 HTTPS를 사용해야 합니다.

진행 상황 확인

GET https://bouncebell.com/api/v1/batches/{id}

{ "id": "bat_8f2k1q3m9x7w4p", "status": "running", "total": 2, "done": 1 }

상태는 queued, running, done 중 하나입니다. done이면 응답에 상태별 counts도 포함됩니다.

결과 다운로드

GET https://bouncebell.com/api/v1/batches/{id}/results

기본적으로 JSON을 반환합니다. CSV 파일이 필요하면 ?format=csv를 추가하세요. 각 행에는 단건 검증과 같은 필드가 포함됩니다.

크레딧

GET https://bouncebell.com/api/v1/credits

{ "credits_remaining": 33420 }

오류 및 제한

오류가 발생하면 error 코드와 읽기 쉬운 message가 담긴 JSON 본문이 반환됩니다.

단건 검증은 키당 초당 20건으로 제한됩니다. 더 필요하면 문의하세요.