개발자용

이메일 검증 API.

양식에는 단일 주소 검사를, 고객 리스트에는 비동기 작업을 사용하세요. 기존 이메일 제공업체는 그대로 사용할 수 있습니다.

주소 하나로 시작하기

첫 번째 요청.

키 없이 무료 데모 엔드포인트를 사용하세요. 요청 횟수가 제한되며 서비스 체험용입니다.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

유료 검사를 하려면 패키지를 구매한 뒤 다음 엔드포인트를 사용하세요: /v1/fast-verify 키는 다음 헤더에 넣습니다: X-API-Key. 키가 URL, 소스 관리, 분석 도구에 노출되지 않도록 하세요.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Python 예제

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Node.js 예제

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

리스트를 넣으면 결과가 나옵니다

더 큰 리스트를 검증하세요.

POST /v1/tasks

작업당 최대 10,000개 주소를 제출할 수 있습니다. 반환된 작업 ID를 보관하고 다음 값을 확인하세요. accepted, skipped 및 invalids: 모든 입력이 반드시 대기열에 추가되는 것은 아닙니다. 중복, 형식 오류, 수신 차단된 주소는 제외될 수 있으며, 잔액이 부족하면 일부만 접수될 수 있습니다.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

상태를 폴링한 다음 각 결과 페이지를 가져오세요. 잘못된 입력만 포함된 응답은 작업 ID가 비어 있을 수 있으니 폴링하지 마세요.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

완료된 작업 결과는 JSON입니다. 접수된 리스트 전체를 받을 때까지 페이지를 계속 가져오세요. 완료 시 자동으로 알림을 받으려면 작업을 생성할 때 다음 값과 함께 웹훅을 전달하세요: mode: "completed" (작업 생성 시).

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

프로덕션에서 활성화하기 전에 스키마에서 웹훅 설정과 서명 검증 방법을 확인하세요.

응답 이해하기

형식이 맞다고 존재하는 것은 아닙니다.

각각 별개의 신호입니다. 형식이 올바른 주소도 존재하지 않거나, 일회용이거나, 확인할 수 없을 수 있습니다.

필드	의미
`valid`	주소가 구문 검사를 통과했습니다. 이것만으로는 메일함이 확인되지 않습니다.
`exists`	메일함 확인 결과입니다. 오류 및 catch-all 신호와 함께 해석하세요.
`disposable`	도메인이 임시 이메일 제공업체로 확인되었습니다.
`accept_all`	서버가 임의의 주소를 수락하므로 해당 메일함을 확실히 확인할 수 없습니다.
`error_category`	no_mx, risky 또는 일시적인 서버 문제 등 실패나 위험의 원인을 설명합니다.
`permanent_error`	검사 중 영구 실패가 반환되었습니다. 일시적 실패를 영구 거부로 취급해서는 안 됩니다.
`ttl`	반환되는 경우 재시도/캐시 시간 힌트(초)입니다.

검증으로 전달을 보장하거나, 스팸 신고를 없애거나, 메일함 소유권을 증명할 수는 없습니다.

잔액을 확인하세요.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

응답에는 남은 크레딧, 예약된 크레딧, 사용한 크레딧, 키 유형, 만료일이 포함됩니다. 일반 검증 1건에 크레딧 1개가 사용되며, 실제 필터링과 과금은 경로와 작업 접수 결과에 따라 달라집니다. 업로드한 리스트 전체가 처리되었다고 판단하기 전에 응답을 확인하세요.

429 응답은 요청이 제한되고 있다는 뜻입니다. 잠시 기다린 후 다시 시도하세요. 현재 API에서는 다른 오류가 JSON 또는 텍스트로 반환될 수 있습니다. HTTP 오류를 검증 결과로 해석하지 마세요.

검증 API 명세.

OpenAPI JSON 다운로드

공개 명세는 데모, 빠른 검증, 작업, 작업 상태, 결과, 계정 잔액을 다룹니다. 발송 및 관리자 엔드포인트는 이 검증 레퍼런스에 포함되지 않습니다.

플랫폼 연결에 도움이 필요하신가요? support@zbounce.net