검증 이유 코드

BillionVerify API가 반환하는 모든 reason 코드의 완전한 참조 가이드 — 각 코드의 의미와 처리 방법.

모든 검증 결과에는 이메일이 해당 상태를 받은 이유를 설명하는 reason 필드가 포함됩니다. 이 참조 가이드를 사용하여 정확한 필터링 로직을 구축하고, 예상치 못한 결과를 진단하며, 발송 전략을 최적화하세요.

reason의 작동 방식

reason 필드는 모든 검증 응답에서 status 필드와 함께 나타납니다:

{
  "email": "user@example.com",
  "status": "valid",
  "reason": "smtp_deliverable"
}

reason은 안정적인 문자열 식별자입니다 — 필터링 규칙이나 다운스트림 조건부 로직에서 직접 사용할 수 있습니다.

Valid（유효）

status: "valid" 이메일은 전달 가능이 확인되었습니다.

reason	설명
`smtp_deliverable`	SMTP RCPT가 250 OK를 반환함 — 메일박스 전달 가능 확인. Microsoft 365 DBEB 모드가 전달을 확인하거나 catch-all 도메인이 특정 주소를 추가로 확인할 때도 사용됩니다.

Invalid（무효）

status: "invalid" 이메일은 목록에서 제거해야 합니다 — 전달이 불가능합니다.

reason	설명
`invalid_syntax`	이메일 주소가 구문 분석에 실패 — 잘못된 로컬 파트, 도메인 또는 `@` 누락.
`no_mx_records`	도메인에 MX 레코드가 없음（NXDOMAIN 또는 빈 MX 조회 결과）.
`spf_reject_all`	도메인에 MX 레코드가 없고 `-all`이 포함된 SPF 레코드가 있음 — 도메인이 모든 수신 메일을 명시적으로 거부.
`mailbox_not_found`	SMTP 550/5xx가 원격 서버에 메일박스가 존재하지 않음을 확인.
`host_not_found`	MX 호스트명이 응답하지 않음 — 호스트에 도달할 수 없거나 존재하지 않음.

Unknown（알 수 없음）

status: "unknown" 이메일은 결정적으로 검증할 수 없었습니다. 일부는 일시적이며（재시도 가능）, 다른 것들은 구조적 한계를 나타냅니다.

reason	재시도 가능	설명
`smtp_unverifiable`	아니오	제공업체가 자동화된 SMTP 검증을 차단함（Apple iCloud, Microsoft 소비자, Proton, Tuta）. 결과는 도메인 수준 휴리스틱에 기반.
`smtp_blocked`	아니오	원격 SMTP 서버가 연결을 명시적으로 차단하거나 블랙리스트에 등록.
`smtp_eof_blocked`	예	MX가 배너를 보내기 전에 연결을 종료함 — 일반적으로 IP 속도 제한기 또는 fail2ban 규칙.
`smtp_timeout`	예	SMTP 작업이 시간 초과됨（컨텍스트 데드라인 또는 취소）.
`smtp_connection_failed`	아니오	일반 SMTP 연결 실패 — 더 구체적인 클래스가 일치하지 않음.
`smtp_rate_limited`	예	원격 SMTP 서버가 속도 제한 응답을 반환（421, 450, 451 또는 메시지 제한 초과）.
`smtp_greylisted`	예	일반 그레이리스팅 응답 감지 — 지연 후 재시도.
`mimecast_greylist`	예	Mimecast 특정 그레이리스팅 / 451 임시 실패.
`proofpoint_ad_lookup`	예	Proofpoint AD 비동기 조회 진행 중（수신자 검증 중 421 4.1.1 임시 실패）.
`policy_temp_fail`	예	원격 정책 적용으로 인한 일반 4xx 임시 실패.
`google_rate_limit`	예	Google MX가 속도 제한 또는 임시 거부 응답을 반환.
`google_dmarc_misalignment`	아니오	도메인 DMARC 구성이 정렬되지 않음 — Google이 DMARC 정책에 따라 거부.
`m365_ip_rep_block`	예	Microsoft 365가 IP 평판으로 인해 연결을 거부（4.7.650 / 4.7.651 코드）.
`mailbox_full`	아니오	메일박스는 존재하지만 할당량 초과（SMTP 452 또는 받은편지함 가득 참 응답）.
`mailbox_disabled`	아니오	메일박스는 존재하지만 비활성화 또는 비활성화됨.
`dns_timeout`	예	DNS 또는 MX 조회 시간 초과 — 일시적인 리졸버 문제.
`dns_lookup_error`	예	DNS 조회가 NXDOMAIN 이외의 오류로 실패（SERVFAIL, UDP 시간 초과 또는 리졸버 오류）.
`yahoo_api_verified`	아니오	Yahoo 등록 API가 주소의 전달 가능성을 확인（배치 경로）.
`yahoo_api_not_deliverable`	아니오	Yahoo 등록 API가 주소의 전달 불가능을 확인（배치 경로）.
`yahoo_api_error`	예	Yahoo 등록 API 호출 실패 — 일반 오류.
`yahoo_api_unavailable`	예	Yahoo 등록 API를 사용할 수 없음（배치 수준 상태 실패）.
`yahoo_api_eof`	예	Yahoo API가 조기 EOF를 반환 — 일시적인 TCP/TLS 끊김.
`yahoo_api_unavailable_after_fallback`	예	Yahoo API가 실패하고 SMTP 폴백도 실패.
`carrier_blocked`	아니오	일본 통신사 도메인（docomo.ne.jp, au.com 등）— 통신사 정책으로 SMTP가 차단됨.
`internal_verifier_error`	예	미분류 내부 검증기 오류 — 일시적 실패.
`rate_limited`	예	배치 처리 중 속도 제한됨（파일 작업에서 `smtp_rate_limited`의 별칭）.
`bucket_default_skip_smtp_unknown`	아니오	계정 수준 검증 모드가 SMTP를 건너뛰도록 설정됨 — 결과는 도메인 검사에만 기반.

Risky（위험）

status: "risky" 이메일은 중간 정도의 전달 가능성 위험이 있습니다.

reason	재시도 가능	설명
`mx_only_verification_semaphore_timeout`	예	SMTP 동시성 세마포어 시간 초과 — MX 전용 폴백이 유효한 MX 레코드를 확인했지만 메일박스를 개별적으로 검증할 수 없었음.

Catch-all（전체 수신）

status: "catchall" 이메일은 모든 주소에 대해 메일을 수신하는 도메인에 속합니다. 개별 전달 가능성을 확인할 수 없습니다.

reason	설명
`catch_all_domain`	도메인이 catch-all로 확인됨 — 무작위 RCPT 프로브가 메일 서버에 의해 수락됨.
`catch_all_deliverable`	Catch-all 도메인이며, 특정 주소의 RCPT도 250 OK를 반환.
`catch_all_inferred`	캐시된 증거에서 catch-all 상태를 추론（간접적, 실시간 프로브 아님）.
`m365_internal_relay`	Microsoft 365 도메인이 내부 릴레이로 구성됨 — 모든 RCPT가 수락되지만 개별적으로 검증되지 않음.
`gateway_accept_all`	보안 게이트웨이（Mimecast, Proofpoint 등）가 전체 수신 모드.
`forwarding_alias`	이메일 전달 별칭 서비스（SimpleLogin, Firefox Relay, Duck.com）.
`region_consumer_accept_all`	모든 수신 메일을 수락하는 것으로 알려진 지역 소비자 도메인（예: naver.com, daum.net）— SMTP 프로브 건너뜀.
`bucket_default_skip_smtp_catchall`	계정 수준 검증 모드가 SMTP catch-all 감지를 건너뛰도록 설정됨.

Role（역할 주소）

status: "role" 이메일은 공유 받은편지함에 속합니다（예: info@, support@, noreply@）. 이 주소들은 일반적으로 전달 가능하지만 참여율이 낮습니다.

역할 주소는 기본 SMTP 검사의 reason을 상속합니다 — 이 상태에 대한 전용 reason 코드는 없습니다. 예를 들어, SMTP를 통과한 역할 주소는 reason: "smtp_deliverable"을 표시합니다.

Disposable（일회용）

status: "disposable" 이메일은 임시 이메일 서비스에 속합니다. 이를 수락하면 일반적으로 저품질 가입으로 이어집니다.

reason	설명
`disposable_domain`	도메인이 알려진 일회용/임시 이메일 제공업체로 등록됨.

필터링에서 reason 사용하기

status와 reason을 결합하여 정확한 목록 세분화를 수행할 수 있습니다. 예를 들어, 일시적인 문제로만 unknown인 unknown 이메일을 유지하려면:

function isRetryableUnknown(result) {
  const retryableReasons = new Set([
    'smtp_eof_blocked', 'smtp_timeout', 'smtp_rate_limited',
    'smtp_greylisted', 'mimecast_greylist', 'proofpoint_ad_lookup',
    'policy_temp_fail', 'google_rate_limit', 'm365_ip_rep_block',
    'dns_timeout', 'dns_lookup_error', 'yahoo_api_error',
    'yahoo_api_unavailable', 'yahoo_api_eof',
    'yahoo_api_unavailable_after_fallback', 'internal_verifier_error',
    'rate_limited', 'mx_only_verification_semaphore_timeout',
  ]);
  return result.status === 'unknown' && retryableReasons.has(result.reason);
}

검증 이유 코드

On this page