검증 이유 코드
BillionVerify API가 반환하는 모든 검증 reason 코드의 전체 참조 문서입니다. 각 코드의 의미와 대응 방법을 설명합니다.
작동 방식 보기
이메일 검증은 어떻게 작동할까? 계층별 설명
구문에서 SMTP까지 이메일 검증이 작동하는 방식: 결과를 정하는 아홉 계층을 따라 주소 하나를 따라가 보세요. 주소가 일찍 멈추는 지점, 메일 서버의 응답을 해석하는 방법, Catch-all을 테스트하는 방법, 각 결과의 비용을 알아봅니다.
모든 검증 결과에는 이메일이 해당 상태를 받은 이유를 설명하는 reason 필드가 포함됩니다. 이 문서를 참고해 정밀한 필터링 로직을 만들고, 예상과 다른 결과의 원인을 진단하며, 발송 전략을 조정하세요.
reason의 작동 방식
reason 필드는 모든 검증 응답에서 status 필드와 함께 나타납니다.
{
"email": "user@example.com",
"status": "valid",
"reason": "smtp_deliverable"
}reason은 변하지 않는 문자열 식별자입니다. 필터링 규칙이나 후속 조건 로직에서 그대로 사용할 수 있습니다.
메일박스 유형별 검증 방식
받는 사람의 제공업체를 어떤 방식으로 확인할 수 있는지에 따라 반환되는 reason이 달라집니다.
- 비즈니스 도메인(Google Workspace, Microsoft 365, 자체 운영 메일 서버)은 해당 메일박스에 대해 실시간 SMTP RCPT 검사를 수행합니다. 먼저 같은 도메인의 임의 주소를 조회하므로, catch-all 도메인, Microsoft 365 내부 릴레이, 모든 수신자를 수락하는 보안 게이트웨이는
valid가 아닌catchall로 보고됩니다. - Gmail은 실시간 SMTP RCPT 검사를 수행합니다.
- Yahoo, AOL, Outlook.com, Hotmail, Live, MSN은 SMTP 검증을 차단하므로 제공업체별 계정 조회로 확인합니다. 이 경우
yahoo_api_*또는microsoft_api_*reason이 반환되며, 계정이 존재하는지 확인합니다. - GMX, web.de, Mail.ru, Yandex 등 지역 제공업체는 제공업체별 속도 규칙에 맞춰 검증합니다. 요청 한도, 그레이리스팅, 검사 거부로 인해
unknown결과가 더 많아집니다. - Apple iCloud, Proton, Tuta는 신뢰할 만한 검사를 허용하지 않으므로 해당 주소는 항상
smtp_unverifiable과 함께unknown을 반환합니다.
unknown 결과는 reason과 관계없이 차감되지 않습니다.
Valid (유효)
status: "valid" 이메일은 전달 가능으로 확인된 주소입니다.
| Reason | 설명 |
|---|---|
smtp_deliverable | SMTP RCPT가 250 OK를 반환했습니다. 메일박스의 전달 가능 여부가 확인되었습니다. Microsoft 365 DBEB 모드가 전달을 확인한 경우에도 반환됩니다. |
yahoo_api_verified | Yahoo 또는 AOL 계정 조회로 계정이 존재함을 확인했습니다. |
microsoft_api_verified | Microsoft 개인 계정 조회(Outlook.com, Hotmail, Live, MSN)로 계정이 존재함을 확인했습니다. |
unitedinternet_api_verified | GMX.com / mail.com 계정 조회로 계정이 존재함을 확인했습니다. |
Invalid (무효)
status: "invalid" 이메일은 전달이 불가능하므로 목록에서 제거해야 합니다.
| Reason | 설명 |
|---|---|
invalid_syntax | 이메일 주소의 구문 분석에 실패했습니다. 로컬 파트나 도메인의 형식이 잘못되었거나 @가 없습니다. 크레딧이 차감되지 않습니다. |
no_mx_records | 도메인에 MX 레코드가 없습니다(NXDOMAIN 또는 빈 MX 조회 결과). |
null_mx | 도메인이 null MX 레코드(RFC 7505)를 게시했습니다. 어떤 메일도 받지 않겠다고 명시한 것입니다. |
spf_reject_all | 도메인에 MX 레코드가 없고 -all이 포함된 SPF 레코드가 있습니다. 도메인이 모든 수신 메일을 명시적으로 거부합니다. |
mailbox_not_found | SMTP 550/5xx 응답으로 원격 서버에 해당 메일박스가 없음을 확인했습니다. |
mailbox_disabled | 메일박스는 있지만 비활성화되었거나 해지되었습니다. |
host_not_found | MX 호스트명이 응답하지 않습니다. 호스트에 연결할 수 없거나 존재하지 않습니다. |
yahoo_api_not_deliverable | Yahoo 또는 AOL 계정 조회로 계정이 존재하지 않음을 확인했습니다. |
microsoft_api_not_deliverable | Microsoft 개인 계정 조회로 계정이 존재하지 않음을 확인했습니다. |
unitedinternet_api_not_deliverable | GMX.com / mail.com 계정 조회로 계정이 존재하지 않음을 확인했습니다. |
Unknown (알 수 없음)
status: "unknown" 이메일은 최종적으로 검증하지 못한 주소입니다. unknown 결과는 크레딧이 차감되지 않습니다. 일부는 일시적이어서 재시도할 수 있고, 나머지는 구조적인 한계 때문입니다.
| Reason | 재시도 가능 | 설명 |
|---|---|---|
smtp_unverifiable | 아니요 | 제공업체가 신뢰할 만한 SMTP 검증을 허용하지 않습니다(Apple iCloud, 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 | 예 | 일반적인 그레이리스팅 응답이 감지되었습니다. 잠시 후 다시 시도하세요. |
smtp_550_unclassified | 예 | 서버가 "사용자 없음"을 명확히 뜻하지 않는 550을 반환했으므로 invalid로 처리하지 않습니다. |
smtp_egress_unavailable | 예 | 검사 시점에 이 제공업체에 사용할 수 있는 검증 송신 경로가 없었습니다. |
smtp_egress_unselectable | 아니요 | 이 제공업체에 접근할 수 있는 검증 송신 경로가 허용되어 있지 않습니다. |
mimecast_greylist | 예 | Mimecast 전용 그레이리스트 / 451 일시적 실패입니다. |
proofpoint_ad_lookup | 예 | Proofpoint AD 비동기 조회가 진행 중입니다(수신자 확인 중 421 4.1.1 일시적 실패). |
proofpoint_egress_listed | 아니요 | Proofpoint가 보호하는 도메인으로, 현재 당사의 검사에 응답하지 않습니다. |
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 코드). |
tonline_egress_not_whitelisted | 아니요 | T-Online은 허용 목록에 등록된 발신자의 검사만 받으므로 메일박스를 검증할 수 없습니다. |
mailbox_full | 아니요 | 메일박스는 있지만 용량을 초과했습니다(SMTP 452 또는 편지함 가득 참 응답). |
dns_timeout | 예 | DNS 또는 MX 조회가 시간 초과되었습니다. 일시적인 리졸버 문제입니다. |
dns_lookup_error | 예 | NXDOMAIN이 아닌 오류로 DNS 조회에 실패했습니다(SERVFAIL, UDP 시간 초과 또는 리졸버 오류). |
dns_resolution_failed | 예 | 일시적인 사유로 DNS 해석에 실패했습니다. |
yahoo_api_error | 예 | Yahoo / AOL 계정 조회에 실패했습니다. 일반 오류입니다. |
yahoo_api_unavailable | 예 | Yahoo / AOL 계정 조회를 사용할 수 없었습니다(배치 단위 상태 점검 실패). |
yahoo_api_eof | 예 | Yahoo / AOL 계정 조회에서 EOF가 조기에 반환되었습니다. 일시적인 TCP/TLS 끊김입니다. |
yahoo_api_rate_limited | 예 | Yahoo / AOL 계정 조회가 요청 한도에 걸렸습니다. |
microsoft_api_error | 예 | Microsoft 개인 계정 조회에 실패했거나 제한되었습니다. |
microsoft_api_unavailable | 예 | Microsoft 개인 계정 조회를 사용할 수 없었습니다. |
unitedinternet_api_error | 예 | GMX.com / mail.com 계정 조회에 실패했습니다. |
unitedinternet_api_unavailable | 아니요 | 이번 실행에서 GMX.com / mail.com 계정 조회를 사용할 수 없었습니다. |
capacity_deferred | 예 | 제공업체의 검증 처리 용량이 가득 차 검사가 연기되었습니다. |
provider_capacity_exhausted | 아니요 | 제공업체의 처리 용량이 재시도 기간(약 2시간) 내내 가득 차 있어, 이 주소들은 결론 없이 작업이 끝났습니다. |
carrier_blocked | 아니요 | 일본 통신사 도메인(docomo.ne.jp, au.com 등)입니다. 통신사 정책에 따라 SMTP가 차단됩니다. |
internal_verifier_error | 예 | 분류되지 않은 내부 검증기 오류입니다. 일시적인 실패입니다. |
rate_limited | 예 | 배치 처리 중 이메일이 요청 한도에 걸렸습니다(파일 작업에서의 smtp_rate_limited 별칭). |
bucket_default_skip_smtp_unknown | 아니요 | 계정 단위 검증 모드가 SMTP를 건너뛰도록 설정되어 있습니다. 결과는 도메인 검사만을 바탕으로 합니다. |
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). |
yahoo_isp_accept_all | Yahoo 메일 인프라에서 운영되는 ISP 도메인입니다(예: att.net, sbcglobal.net, verizon.net). 제공업체가 모든 수신자를 수락하므로 메일박스 단위 검사가 불가능합니다. |
region_consumer_accept_all | 모든 수신 메일을 수락하는 것으로 알려진 지역 개인용 도메인입니다(이전 결과). |
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 | 도메인이 알려진 일회용 / 임시 이메일 제공업체로 등록되어 있습니다. |
Risky (이전 결과에만 해당)
새 검증에서는 더 이상 status: "risky"가 반환되지 않습니다. 유일한 발생 경로였던 Spamhaus Domain Blocklist 검사가 2026-09-11에 제거되었습니다. 그 날짜 이전에 만들어진 결과에서는 여전히 risky가 보일 수 있습니다.
이전 결과에서 risky는 주소가 전달될 가능성이 높지만, 수신자 도메인이 스팸, 피싱, 악성코드 또는 봇넷 C&C 활동으로 Spamhaus에 등재되어 있다는 뜻이었습니다. risk_reasons 배열이 그 이유를 설명합니다.
risk_reasons 값 | 설명 |
|---|---|
spamhaus_dbl_spam | 도메인이 스팸 발송원으로 등재되어 있습니다. |
spamhaus_dbl_phish | 도메인이 피싱 도메인으로 등재되어 있습니다. |
spamhaus_dbl_malware | 도메인이 악성코드 배포 도메인으로 등재되어 있습니다. |
spamhaus_dbl_botnet_cc | 도메인이 봇넷 명령·제어 인프라로 등재되어 있습니다. |
필터링에서 reason 활용하기
status와 reason을 함께 사용하면 목록을 정밀하게 나눌 수 있습니다. 예를 들어 일시적인 문제 때문에 unknown이 된 이메일만 남기려면 다음과 같이 합니다.
function isRetryableUnknown(result) {
const retryableReasons = new Set([
'capacity_deferred', 'context_cancelled', 'dns_lookup_error',
'dns_resolution_failed', 'dns_timeout', 'google_rate_limit',
'internal_verifier_error', 'm365_ip_rep_block', 'microsoft_api_error',
'microsoft_api_unavailable', 'mimecast_greylist',
'mx_only_verification_semaphore_timeout', 'policy_temp_fail',
'proofpoint_ad_lookup', 'rate_limited', 'smtp_550_unclassified',
'smtp_connection_failed', 'smtp_egress_unavailable', 'smtp_eof_blocked',
'smtp_greylisted', 'smtp_rate_check_failed', 'smtp_rate_limited',
'smtp_rate_wait_failed', 'smtp_timeout', 'unitedinternet_api_error',
'yahoo_api_eof', 'yahoo_api_error', 'yahoo_api_rate_limited',
'yahoo_api_unavailable',
]);
return result.status === 'unknown' && retryableReasons.has(result.reason);
}