이메일 검증 API 참조

시작하기

API 키에서 테스트 키를 생성하여 서버에 보관하고 FAIRVALID_API_KEY 및 FAIRVALID_BASE_URL을(를) 설정하세요. 테스트 키는 예약된 @example.com 주소에서 작동합니다. 제공업체 호출을 하지 않으며 크레딧도 사용하지 않습니다.

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

프로덕션에서는 submit 범위의 Live 키를 생성하고 /api/v1/jobs 또는 /api/v1/verifications을(를) 사용하세요. 작업 상태와 결과를 읽으려면 read 범위를 추가하세요.

새 작업은 HTTP 202와 UUID job_id을(를) 반환합니다. 동일한 재시도 요청은 같은 작업과 함께 HTTP 200을 반환합니다. 응답에는 version: v1, brand: FairValid 및 no-store 헤더가 포함됩니다.

키 및 지출 한도

서버에서 Authorization: Bearer fv_live_… 또는 Bearer fv_test_…을(를) 전달하세요. 전체 시크릿은 한 번만 표시됩니다. 라이브 키에는 submit, read, balance 범위를 지정할 수 있습니다. 폐기된 키로는 새 요청을 할 수 없습니다. 테스트 키는 자체 시뮬레이션 작업에만 접근합니다.

라이브 키의 전체 기간 한도는 이미 차감된 크레딧과 접수된 고유 ID에 대해 예약된 크레딧을 합산합니다. 이 한도로 워크스페이스에 크레딧이 추가되지는 않습니다. 한도를 초과하는 새 요청은 작업이나 보류를 생성하지 않고 HTTP 402 key_cap_reached을(를) 반환합니다. 한도를 낮추면 새 작업이 차단되며, 이미 접수된 작업은 계속 진행됩니다.

라이브 작업은 워크스페이스의 검증 대기열과 크레딧 잔액을 사용합니다. 키 권한 범위, 키 한도, 워크스페이스 액세스 및 처리 한도가 계속 적용됩니다. 검사가 처리 대상으로 접수되면 워크스페이스 크레딧이 예약되며, 결과에는 대시보드와 동일한 차감 및 반환 규정이 적용됩니다.

운영상 일시 중지 중에는 새 실시간 제출에 대해 크레딧을 보류하지 않고 HTTP 503 live_verification_unavailable이(가) 반환될 수 있습니다. 나중에 동일한 Idempotency-Key(으)로 다시 시도하세요.

작업 및 결과

방법	경로	목적
`POST`	`/api/v1/jobs`	최대 2 MiB 크기의 JSON으로 주소를 1~5,000개 제출하세요.
`POST`	`/api/v1/verifications`	실제 주소 하나를 제출하거나 기존 단일 주소 시뮬레이터를 사용하세요.
`GET`	`/api/v1/jobs/{id}`	현재 작업 상태와 요약을 읽습니다.
`GET`	`/api/v1/jobs/{id}/results`	최대 50개의 결과와 서명된 다음 커서를 읽습니다.
`POST`	`/api/v1/jobs/{id}/cancel`	취소를 요청합니다. 이미 진행 중인 작업은 완료될 수 있습니다.
`GET`	`/api/v1/balance`	워크스페이스의 실시간 사용 가능 크레딧과 보류 크레딧을 읽습니다.

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

next_cursor을(를) cursor 쿼리 매개변수로 전달하세요. 이 값에는 원래 필터와 검색어가 포함됩니다. 필터는 all, valid, invalid, catch_all, unknown, still_checking, not_checked입니다. 라이브 결과 및 크레딧 상태는 대시보드 스냅샷과 일치합니다. 작업 상태는 queued, running, paused, canceling, canceled 또는 completed일 수 있습니다. 테스트 작업은 결정적인 completed, pending, failed 또는 cancelled 상태를 반환합니다.

오류 및 안전한 재시도

모든 작업 제출과 라이브 단일 주소 제출 시 허용된 영문자, 숫자, 마침표, 콜론, 밑줄 또는 하이픈으로 구성된 8~128자의 Idempotency-Key을(를) 보내세요. 응답이 불확실하면 동일한 API 키, 멱등성 키, 정규화된 본문으로 재시도하세요. 재전송(replay)은 API 키 단위로 적용되므로, 해당 자격 증명을 교체한 뒤 다시 제출하면 별도의 실행이 생성될 수 있습니다. 본문을 변경한 채 멱등성 키를 재사용하면 HTTP 409 idempotency_conflict이(가) 반환됩니다. 크레딧이 차감될 수 있는 새 실행을 의도할 때만 새 키를 사용하세요.

HTTP 401은 키가 없거나, 폐기되었거나, 권한 범위가 부족하다는 의미입니다. HTTP 422는 유효하지 않은 주소 또는 목록 한도 초과에 해당합니다. 테스트 대량 작업은 워크스페이스당 시간당 신규 작업 20건 또는 30일당 100건을 초과하면 HTTP 429를 반환하며, 동일한 재시도 요청은 여전히 기존 작업을 반환합니다. HTTP 503은 요청을 일시적으로 처리할 수 없다는 의미입니다. 제출 여부가 불확실한 상황에서 503이 반환되었다고 해서 작업이 생성되지 않았다고 단정할 수 없으므로, 동일한 멱등성 키로 다시 시도하세요. 오류에는 코드, 메시지, 요청 ID가 포함됩니다.

무료 샌드박스

테스트 키는 다음 주소만 허용합니다: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com, error@example.com. 각각 유효, 무효, 캐치올, 알 수 없음, 대기 중, 사용 불가 결과를 시뮬레이션합니다. 대량 테스트 작업은 실제 검증이나 크레딧 원장에 영향을 주지 않고 상태 조회, 결과 확인, 취소 및 재전송을 지원합니다.

대량 샌드박스 작업과 해당 재실행 기록은 30일 동안 보관됩니다. 이 기간이 지나면 새 테스트에는 새 멱등성 키를 사용하세요.

기존 /api/v1/verifications 테스트 키 시뮬레이터는 이전 2026-10-01 응답 버전과 camelCase 필드를 사용합니다. 버전이 지정된 대량 시뮬레이터는 /api/v1/jobs을(를) 사용하세요.

서명된 웹훅

소유자 및 관리자 역할은 job.completed 및 job.canceled에 대한 HTTPS 엔드포인트를 구성합니다. 테스트 핑은 test.ping을(를) 사용합니다. 작업 페이로드에는 고정 이벤트 ID, 작업 ID, 상태, 주소가 포함되지 않은 요약, 차감/반환 수, 결과 URL이 포함됩니다. 이메일 주소나 제공업체 데이터는 절대 포함되지 않습니다.

FairValid-Webhook-Id, FairValid-Webhook-Timestamp, FairValid-Webhook-Signature을(를) 읽으세요. 서명은 fv1= 뒤에 fv1\n{event ID}\n{Unix timestamp}\n의 원시 바이트와 바로 이어지는 원시 JSON 본문에 대한 소문자 HMAC-SHA256 16진수 값이 붙은 형식입니다. 상수 시간 비교를 사용하세요. 사용자 시계 기준으로 5분 이상 차이 나는 타임스탬프는 거부하고, 영구 저장소에서 이벤트 ID로 중복을 제거하세요.

10초 이내에 2xx 응답을 반환하세요. 실패했거나 불확실한 전송은 같은 이벤트 ID로 최대 8회 재시도됩니다. 30일간의 기록을 확인하거나 수동으로 다시 전송할 수 있습니다. 리디렉션 및 비공개 대상은 거부됩니다. 시크릿을 교체한 후의 새 시도에는 새 시크릿이 사용됩니다. 진행 중인 시도의 서명을 확인할 수 있도록 이전 시크릿을 24시간 동안 보관하세요.

실행 가능한 예제

저장소에는 packages/contracts/examples/job.mjs및 packages/contracts/examples/webhook-receiver.mjs이(가) 포함되어 있습니다. Node 22와 Test 키로 작업 예시를 실행하세요. 수신기는 정확한 원시 본문 바이트를 검증하며, 키 교체 중에는 현재 시크릿과 이전 시크릿을 모두 검증합니다. 프로덕션에서 사용하기 전에 HTTPS를 앞단에 두고, 메모리 내 이벤트 ID 집합을 내구성 있는 원자적 저장소로 교체하세요.

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs