실시간 이메일 검증 API: 개발자 가이드

실시간 이메일 검증은 사용자가 아직 양식에 머물러 있는 동안 주소를 확인합니다. “Submit”과 다음 화면 사이의 수백 밀리초 안에 실행되며, 한 가지 질문에 답합니다. 이 주소를 데이터베이스에 저장해야 할까요? 실시간 이메일 검증 API가 대신 판단해 줍니다. 구문, 도메인과 해당 MX 레코드, 일회용 및 역할 기반 신호, catch-all 동작, 그리고 요청하는 경우 메일박스 자체를 확인합니다. 그런 다음 코드가 처리할 수 있는 구조화된 결과를 반환합니다.

이 가이드는 가입, 결제 또는 리드 양식에 이러한 게이트를 추가하는 개발자를 위한 것입니다. 검증 항목의 기능, API 호출 방법, 각 상태를 제품 결정으로 전환하는 방법, 메일 서버가 느릴 때도 빠르게 유지하는 방법을 다룹니다. 예제에서는 BillionVerify 이메일 검증 API를 사용하지만, 설계 조언은 모든 제공업체에 적용됩니다.

실시간 이메일 검증이란?

실시간 이메일 검증은 주소를 입력하는 순간 실행되는 검사로, 캠페인이 발송된 후 며칠이 지나서 실행되는 검사가 아닙니다. 사용자가 주소를 입력하면 프런트엔드 또는 백엔드가 이메일 검사 API로 전송합니다. API는 valid, invalid 또는 catchall과 같은 상태와 이를 뒷받침하는 신호를 반환합니다. 그러면 애플리케이션은 가입을 허용하거나 차단하거나, 사용자에게 오타를 수정하도록 요청합니다.

핵심은 타이밍입니다. gmial.com과 같은 오타는 사용자가 아직 양식에 머물러 있을 때 수정하면 비용이 들지 않습니다. 환영 이메일이 반송된 후에는 같은 오타로 인해 고객을 잃게 됩니다. 잘못된 주소는 발신자 평판에도 악영향을 줍니다. 모든 하드 바운스는 메일박스 제공업체에 확인되지 않은 주소로 이메일을 보낸다는 신호를 보내기 때문입니다. 실시간 이메일 검증은 이러한 주소를 입구에서 차단합니다.

또한 사기 방지에도 도움이 됩니다. 실시간 검사를 통해 계정이 생성되기 전에 일회용 받은편지함을 감지할 수 있습니다.

실시간 이메일 검증과 대량 이메일 검증 비교

두 방식 모두 동일한 검사를 사용합니다. 차이는 검사가 실행되는 시점과 검증에 허용되는 시간입니다.

실시간 검증과 대량 검증의 차이를 즉시 단일 주소 검사와 목록 검증으로 비교

실시간 검증은 사용자 요청이 처리되는 동안 한 번에 하나의 주소에 대해 실행됩니다. 느린 양식은 가입을 잃게 만들 수 있으므로, 보통 1초도 안 되는 엄격한 시간 제한이 있습니다. 이를 통해 잘못된 데이터가 유입되는 것을 방지합니다.
대량 검증은 백그라운드에서 전체 목록을 대상으로 실행됩니다. 몇 분 또는 몇 시간이 걸릴 수 있지만, 화면 앞에서 기다리는 사람은 없습니다. 대규모 캠페인 전이나 CRM 가져오기 후처럼 이미 시스템에 있는 데이터를 정리합니다.

대부분의 팀에는 두 방식이 모두 필요합니다. 실시간 검사는 새 데이터를 깨끗하게 유지하고, 정기적인 대량 검증은 시간이 지나며 문제가 생긴 주소(예: 회사를 떠난 직원의 주소)를 찾아냅니다. 더 자세한 비교는 실시간 이메일 검증과 대량 이메일 검증 비교를 참조하세요.

실시간 검사는 실제로 무엇을 테스트하는가

이메일 검증 API는 저렴한 검사부터 비용이 많이 드는 검사까지 일련의 검사를 실행합니다. 각 검사는 서로 다른 유형의 잘못된 주소를 걸러냅니다.

구문

첫 번째 검사는 형식입니다. @가 정확히 하나 있는가? 로컬 부분이 허용된 문자로 구성되어 있는가? 도메인이 도메인처럼 보이는가? 구문 검사는 john@@example 또는 jane.example.com 같은 명백한 잘못된 입력을 거부합니다. 빠르고 네트워크 호출이 필요하지 않습니다. 하지만 구문이 완벽하다고 해서 해당 메일함이 존재한다는 의미는 아닙니다.

도메인 및 MX 레코드

다음으로 API는 DNS에서 도메인을 조회합니다. MX 레코드가 없는 도메인은 이메일을 받을 수 없으므로, 아무리 깔끔해 보여도 해당 주소는 쓸모가 없습니다. 이 검사는 철자가 틀린 도메인과 폐쇄된 회사 도메인을 찾아냅니다. BillionVerify는 찾은 MX 호스트를 mx_records에 반환하며, 도메인이 흔한 도메인의 오타처럼 보일 때 domain_suggestion에 가능성 높은 수정안을 담을 수 있습니다.

일회용, 역할 및 무료 제공업체 신호

일부 주소는 존재하지만 여전히 제품에 적합하지 않을 수 있습니다.

일회용 주소는 임시 받은편지함 서비스에서 제공되며 대개 몇 시간 내에 작동을 멈춥니다. 일회용 이메일 감지가 작동하는 방식을 참조하세요.
역할 주소인 info@ 또는 support@ 등은 개인이 아니라 팀으로 연결됩니다. 대개 전달 가능하지만 참여율은 낮은 편입니다.
Gmail과 같은 무료 제공업체 주소는 소비자에게는 일반적이지만, B2B 양식에서는 기록해 둘 가치가 있습니다.

API는 이를 플래그(is_disposable, is_role, is_free)로 보고하므로 제품별로 결정할 수 있습니다.

Catch-all 도메인

일부 메일 서버는 실제 주소인지 아닌지와 관계없이 해당 도메인의 모든 주소로 이메일을 수락합니다. 이러한 catch-all 도메인에서는 메일함 검사가 특정 받은편지함의 존재를 입증할 수 없습니다. catch-all 결과가 나쁜 결과라는 뜻은 아닙니다. 확실성이 낮다는 의미이므로 레이블보다 점수가 더 중요해집니다. Catch-all 이메일 감지에서 작동 방식과 중요한 이유를 설명합니다.

SMTP 메일함 검사

가장 심층적인 검사는 수신자의 메일 서버에 SMTP를 통해 메시지를 보내지 않고 메일함이 메시지를 수락할지 묻는 것입니다. 퇴사한 직원의 받은편지함처럼 실제 도메인에 존재하지만 더 이상 사용되지 않는 주소를 찾아냅니다. 또한 다른 사람의 서버에 의존하므로 가장 느린 단계이기도 합니다. BillionVerify에서는 check_smtp 매개변수로 제어합니다. 이 매개변수를 생략하면 API가 SMTP 검사를 실행하며, 검사를 건너뛰려면 check_smtp: false를 전송하세요.

도메인 평판

BillionVerify는 도메인 메일 서버 IP의 블랙리스트 결과가 포함된 domain_reputation 객체도 반환할 수 있습니다. 이는 정보 제공용일 뿐이며 상태, 점수 또는 비용을 변경하지 않습니다.

실시간 Email 검증 API 호출 방법

BillionVerify를 사용하면 단일 실시간 검사는 한 번의 HTTPS 요청으로 처리됩니다. 기본 URL은 https://api.billionverify.com/v1이며, API 키는 BV-API-KEY 헤더에 넣습니다. 해당 키는 서버에 보관하세요. 브라우저 코드에 절대 포함하지 마세요.

다음은 API 레퍼런스를 기반으로 한 최소 요청 예시입니다:

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BV-API-KEY: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","check_smtp":true}'

요청에는 세 개의 매개변수가 사용됩니다:

매개변수	기본값	기능
`email`	필수	검증할 주소
`check_smtp`	켜짐	실시간 SMTP 메일함 검사를 건너뛰려면 `false`로 설정
`force_refresh`	`false`	캐시된 결과를 건너뜁니다. 새 결과에는 새 검사와 동일하게 요금이 부과됩니다

성공적인 응답은 표준 봉투 형식으로 결과를 감쌉니다. 다음은 전달 가능한 주소에 대한 간략한 예시입니다:

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "score": 0.95,
    "is_deliverable": true,
    "is_disposable": false,
    "is_catchall": false,
    "is_role": false,
    "is_free": false,
    "domain": "example.com",
    "mx_records": ["mail.example.com"],
    "check_smtp": true,
    "reason": "smtp_deliverable",
    "domain_suggestion": "",
    "response_time": 250,
    "credits_used": 1
  }
}

SDK를 선호한다면 BillionVerify는 Node.js, Python, TypeScript, Go, PHP 및 Java용 공식 SDK를 제공합니다. Node.js에서는 npm install billionverify-sdk를 실행하면 verify 메서드가 포함된 클라이언트를 사용할 수 있으며, Python에서는 패키지 이름이 billionverify입니다.

응답 읽기: 상태, 점수 및 이유

status 필드는 대부분의 코드 분기가 기준으로 삼는 값입니다. 가입 양식에서 각 상태가 의미하는 바와 합리적인 기본값은 다음과 같습니다.

상태	의미	가입 양식 기본값
`valid`	사서함이 존재하며 메일을 받을 수 있음	허용
`invalid`	주소가 존재하지 않거나 메일을 받을 수 없음	차단하고 다른 주소 요청
`disposable`	임시 받은편지함	차단하거나 제한적으로 허용
`catchall`	도메인이 모든 주소를 허용함	허용하고 모니터링
`role`	`info@`와 같은 공유 받은편지함	허용하되 영업용으로 표시할 수 있음
`unknown`	전달 가능성을 확인할 수 없음	허용하고 나중에 재확인

score는 0에서 1 사이의 더 세밀한 신호를 제공합니다. 대략적으로 valid 결과의 점수는 0.85~1.0, catchall은 약 0.55~0.75, unknown은 0.3~0.6, disposable은 0.1, invalid는 0입니다. role 결과는 기본 확인 결과의 점수를 유지합니다. 점수를 사용해 경계 사례에 대한 자체 기준을 설정할 수 있습니다. 예를 들어 가치가 높은 양식에서는 특정 점수 이상인 catch-all 주소만 허용할 수 있습니다.

reason 필드는 판정 이유를 설명합니다. invalid 결과에는 invalid_syntax, no_mx_records 또는 mailbox_not_found가 포함될 수 있으며, 각각 사용자에게 다른 메시지를 표시해야 합니다. 구문 문제가 있으면 "형식을 확인하세요"라는 의미입니다. 받은편지함이 없다는 것은 "이 받은편지함은 존재하지 않습니다"라는 의미입니다. verification reasons 페이지에는 모든 이유가 나와 있으며, 어떤 unknown 이유에 대해 재시도할 가치가 있는지도 설명합니다.

두 필드는 사용자에게 직접 도움을 줍니다. domain_suggestion은 "gmail.com을 의미하셨나요?"와 같은 힌트를 표시하는 데 사용할 수 있고, is_disposable은 일회용 주소가 거부된 이유를 설명합니다.

지연 시간 예산을 중심으로 가입 흐름 설계하기

가장 어려운 부분은 양식을 느려지게 하지 않으면서 검사를 추가하는 것입니다. 먼저 예산을 정하세요. 예를 들어 제출 시 사용자를 300~500밀리초 동안 기다리게 할 수 있는지 결정합니다. 나머지는 모두 이 숫자에 따라 정해집니다.

BillionVerify의 제품 설명에 따르면 캐시된 결과는 200ms 이내에 반환되고, 전체 SMTP 검사는 평균 1~3초가 걸립니다. 이 차이로 다음 두 가지 설계가 가능합니다.

타임아웃을 적용한 전체 검사. SMTP를 켜고 타임아웃을 2~3초로 설정하여 API를 호출합니다. 대부분의 응답은 제때 도착하며 명확한 valid 또는 invalid 결과를 제공합니다. 타임아웃이 발생하면 일단 허용하고 나중에 다시 검사합니다.
지금은 빠르게 검사하고, 나중에 심층 검사. check_smtp: false로 API를 호출합니다. 이 방식은 잘못된 구문, MX 레코드가 없는 도메인, 일회용 주소와 역할 기반 주소처럼 명확한 경우만 판별합니다. 정상적으로 작동하는 도메인의 주소는 smtp_unverifiable 사유와 함께 unknown으로 반환되며, 이는 예상된 결과입니다. 해당 주소를 허용한 다음 백그라운드 작업에서 SMTP를 켜고 두 번째 호출을 실행합니다. 메일박스가 존재하지 않으면 계정을 표시하고 사용자에게 주소 확인을 요청합니다.

몇 가지 프론트엔드 습관도 도움이 됩니다.

모든 키 입력마다 검사하지 말고, 포커스를 잃거나 제출할 때 검사하세요. j, jo, joh를 검사하면 호출과 크레딧이 낭비됩니다.
먼저 로컬 구문 검사를 실행하여 명백한 실수에 대한 왕복 요청을 줄이세요.
백엔드에서 API를 호출하세요. 서버가 API 키를 보관하고 결과를 기록하며, 브라우저에는 결과만 표시합니다.

문구, 오류 표시 위치, 힌트를 표시할 시점과 같은 UX 세부 사항은 가입 중 이메일 확인을 참조하세요.

Fail Open 또는 Fail Closed? 타임아웃과 불확실한 결과 처리

대부분의 제품에서 효과적인 방식은 다음과 같습니다. 명확한 오류에는 fail closed를 적용하고, 불확실한 경우에는 fail open을 적용합니다.

Fail closed는 가입을 차단한다는 뜻입니다. API가 해당 주소가 명백히 잘못되었다고 알릴 때 적용하세요. 예를 들어 invalid 상태에 invalid_syntax 또는 no_mx_records가 포함된 경우, 또는 일회용 계정이 문제를 일으키는 양식에서 disposable 주소인 경우입니다.
Fail open은 사용자를 통과시킨 후 나중에 후속 처리한다는 뜻입니다. unknown 상태, catch-all 도메인, 또는 API가 응답하기 전에 자체 타임아웃이 발생한 경우처럼 결과가 불확실할 때 적용하세요.

불확실한 주소도 차단하면 안 되는 이유는 무엇일까요? 실제 사용자가 그 주소를 사용하는 경우가 많기 때문입니다. 기업 메일 서버는 SMTP 검사를 greylist 처리하거나 속도 제한하는 경우가 많으므로, 이를 차단하면 실제 가입을 놓치게 됩니다. 수락하고, 레코드에 태그를 지정한 다음, 나중에 다시 확인하세요.

지연 시간 예산에 맞춰 API 호출에 클라이언트 측 타임아웃을 설정하세요. 타임아웃이 발생하면 결과를 unknown으로 처리합니다. 즉, 수락하고 플래그를 저장한 다음 백그라운드 재확인 작업을 대기열에 추가하세요. unknown 결과는 요청 처리 중이 아니라 나중에 재시도하세요.

예시: Node.js에서 가입 시 이메일 검증

아래 예시는 가입 핸들러에서 빠른 확인(설계 2)을 수행하는 방식을 보여줍니다. 문서화된 REST 엔드포인트와 응답 필드, 타임아웃, 위의 fail open 또는 closed 규칙을 사용합니다. 사용하는 프레임워크에 맞게 이름을 조정하세요.

const BLOCK = new Set(['invalid', 'disposable']);

async function checkEmail(email) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 400);

  try {
    const response = await fetch('https://api.billionverify.com/v1/verify/single', {
      method: 'POST',
      headers: {
        'BV-API-KEY': process.env.BV_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, check_smtp: false }),
      signal: controller.signal,
    });
    const body = await response.json();
    if (!body.success) return { allow: true, recheck: true };

    const { status, reason, domain_suggestion } = body.data;
    if (BLOCK.has(status)) {
      return { allow: false, reason, suggestion: domain_suggestion };
    }
    return { allow: true, recheck: status === 'unknown' || status === 'catchall' };
  } catch {
    // Timeout or network error: fail open and re-check in the background.
    return { allow: true, recheck: true };
  } finally {
    clearTimeout(timer);
  }
}

SMTP 없이 확인하면 대부분의 실제 주소는 unknown으로 반환되고 recheck 플래그가 설정됩니다. 계정이 저장된 후 백그라운드 작업이 recheck로 표시된 모든 레코드에 대해 SMTP를 켠 상태로 동일한 엔드포인트를 호출합니다. Node.js 튜토리얼에서는 공식 SDK를 포함한 보다 완전한 설정 과정을 안내합니다. HTTP 클라이언트를 지원하는 Python 또는 다른 언어에서도 동일한 요청을 사용할 수 있습니다.

속도 제한, 캐싱 및 비용

실시간 검사가 가입 경로에 포함되므로, 해당 제한이 곧 여러분의 제한이 됩니다. 이를 고려해 계획을 세우세요.

속도 제한. BillionVerify는 계정별 제한으로 용량을 보호합니다. 제한에 도달하면 API는 1003 코드와 Retry-After 헤더가 포함된 HTTP 429를 반환합니다. 잠시 대기한 후 재시도하고, 제한으로 인해 실제 사용자가 차단되지 않도록 자체 fail-open 규칙을 마련해 두세요.

캐싱. 결과가 캐시되므로 반복 검사가 빠르게 완료됩니다. 지난 24시간 동안 계정에서 확인한 주소를 다시 검사하는 것은 무료입니다. 새 결과가 꼭 필요한 경우에만 force_refresh: true를 사용하세요. 캐시를 건너뛰므로 새로운 검사와 동일하게 과금됩니다.

비용. 단일 검사는 일반적으로 크레딧 1개를 사용하며, credits_used에 표시됩니다. 모든 unknown 결과와 구문 오류는 무료입니다. 모든 키 입력마다 검사하지 말고 제출 시 검증하세요. 최근에 확인한 주소도 다시 검사하지 마세요. BillionVerify는 로그인할 때마다 매일 무료 크레딧 20개를 제공하며, 월 최대 600개까지 받을 수 있어 통합 기능을 구축하고 테스트하기에 충분합니다. 유료 크레딧 팩은 가격 페이지에 나와 있습니다.

폼을 넘어: 배치, 파일 및 Webhooks

실시간 검증은 새 주소를 하나씩 처리합니다. 그 외의 경우에도 동일한 API에는 다른 진입점이 있습니다.

소규모 배치. POST /verify/bulk는 한 번의 요청으로 최대 50개의 주소를 확인하므로 CRM 동기화나 가져오기 화면에 적합합니다.
대규모 목록. POST /verify/file은 CSV, TXT 또는 XLSX 파일을 받아 백그라운드에서 처리합니다.
Webhooks. 파일 작업을 폴링하는 대신 file.completed 및 file.failed 이벤트에 대한 webhook을 등록하세요. 서명 확인과 재시도에 대한 자세한 내용은 이메일 검증 Webhooks 가이드를 참조하세요.
일회용 주소만 확인. POST /verify/disposable은 일회용 주소인지 여부만 확인하며 크레딧을 사용하지 않습니다.

일반적인 구성은 모든 폼에서 실시간 확인을 수행하고, recheck로 표시된 레코드에는 매일 밤 배치를 실행하며, 대규모 캠페인 전에 파일 작업을 처리하는 방식입니다.

실시간 이메일 검증 체크리스트

출시하기 전에 다음 목록을 확인하세요.

검증 체크리스트에는 서버 측 검사, 타임아웃 처리 및 불확실한 결과가 표시됩니다

API 키는 브라우저가 아닌 서버에 보관됩니다.
API 호출 전에 구문을 로컬에서 확인합니다.
요청 경로는 check_smtp: false를 사용하며, 지연 시간 예산에 맞는 타임아웃을 설정합니다.
invalid 및 disposable에 명확하고 구체적인 오류 메시지가 표시됩니다.
unknown, catchall 및 타임아웃은 차단 없이 처리하고 재확인을 위해 대기열에 추가합니다.
domain_suggestion으로 오타 힌트를 제공합니다.
429 응답이 발생하면 사용자를 차단하지 않고 백오프합니다.
나중에 반송률을 측정할 수 있도록 결과를 사용자 레코드와 함께 저장합니다.

FAQ

실시간 이메일 검증 API란 무엇인가요?

실시간 이메일 검증 API는 사용자가 양식을 제출할 때 단일 이메일 주소를 확인하고 1초도 안 되는 시간 안에 결과를 반환합니다. 구문, 도메인, MX, 일회용, 역할 기반 및 캐치올 검사를 수행하며, 선택적으로 SMTP 사서함 검사도 실행하므로 주소가 데이터베이스에 저장되기 전에 앱에서 수락, 차단 또는 플래그 처리할 수 있습니다.

실시간 이메일 검증은 대량 검증과 어떻게 다른가요?

실시간 이메일 검증은 사용자 요청 안에서 한 번에 하나의 주소를 확인하며 빠르게 응답해야 합니다. 대량 검증은 백그라운드에서 전체 목록을 확인하므로 훨씬 오래 걸릴 수 있습니다. 새 데이터를 깨끗하게 유지하려면 실시간 검사를 사용하고, 이미 보유한 데이터를 정리하려면 대량 검증을 사용하세요.

모든 가입에 SMTP 검사를 실행해야 하나요?

지연 시간 예산에 따라 다릅니다. SMTP 검사는 사서함을 확인하는 절차이므로, 이를 실행하지 않으면 대부분의 실제 주소가 unknown으로 반환됩니다. 2~3초를 기다릴 수 있다면 제출 시 타임아웃과 함께 실행하세요. 그렇지 않다면 check_smtp: false로 빠른 검사를 실행하고 백그라운드 작업에서 SMTP 검사를 수행하세요.

캐치올 및 unknown 결과는 어떻게 처리해야 하나요?

수락한 후 나중에 다시 확인하세요. 캐치올 도메인은 모든 주소를 수락하므로 사서함 검사만으로는 받은편지함이 존재한다고 입증할 수 없으며, unknown 결과는 검사를 완료하지 못했다는 의미입니다. 이러한 사용자를 차단하면 실제 가입을 놓치게 됩니다. 대신 태그를 지정하고 다시 확인하면 전환율에 악영향을 주지 않으면서 데이터를 깨끗하게 유지할 수 있습니다.

브라우저에서 이메일 검사기 API를 호출할 수 있나요?

아니요. API 키가 노출됩니다. 백엔드에서 API를 호출하고 결정 결과만 반환하세요.

실시간 이메일 검증은 얼마나 빠른가요?

BillionVerify를 사용하면 캐시된 결과는 200ms 이내에 반환되며, 전체 SMTP 검사는 평균 1~3초가 걸립니다. 따라서 SMTP를 사용하지 않는 빠른 검사는 요청 경로에 배치하고 SMTP 검사는 백그라운드에서 실행해야 합니다.

이메일 검증 API 비용은 얼마인가요?

BillionVerify에서는 일반적으로 단일 검사에 1크레딧이 사용되며, 모든 unknown 결과는 무료입니다. 로그인할 때마다 매일 20개의 무료 크레딧을 받을 수 있고, 한 달 최대 600개까지 제공됩니다. 유료 크레딧 팩은 가격 페이지에서 확인할 수 있습니다. force_refresh는 캐시를 건너뛰며 새로운 검사와 동일하게 요금이 부과됩니다.

실시간으로 이메일 검증 시작하기

실시간 이메일 검증은 바운스, 가짜 계정, 오타로 인해 이탈하는 사용자를 줄여줍니다. 요청 경로에 빠른 검사를 추가하고, 느린 검사는 백그라운드로 이동한 다음, 명확한 실패는 차단하고 불확실한 결과는 통과시키세요. 무료 BillionVerify 계정을 만들고, API 키를 받은 후, 위 문서에서 첫 번째 이메일 검증 API 호출을 실행하세요.