이메일 검증 API 워크플로: FairValid로 샌드박스에서 프로덕션까지

이메일 검증 API 워크플로: 샌드박스 테스트에서 프로덕션 결과까지

질문: 자체 시스템에 이메일 검증을 추가하는 개발자라면, 첫 테스트 호출부터 신뢰할 수 있는 프로덕션 결과까지 어떤 단계를 거쳐야 할까요?

간단한 답변: 테스트 키와 무료 샌드박스로 시작하세요. 그런 다음 필요한 범위만 가진 라이브 키로 전환합니다. 모든 제출에 멱등성 키를 함께 보내세요. 작업 상태를 읽고 결과를 페이지 단위로 조회합니다. 각 결과와 각 오류 코드를 개별적으로 처리하세요. 아래 단계는 FairValid 고객용 API 레퍼런스를 따릅니다.

1단계: 먼저 샌드박스를 대상으로 구축하기

API 키 페이지에서 테스트 키를 만들고 서버에 보관하세요. 레퍼런스에서는 FAIRVALID_API_KEY과 FAIRVALID_BASE_URL, 두 개의 환경 변수를 사용합니다. 테스트 키는 제공업체를 호출하지 않으며 크레딧도 사용하지 않습니다.

테스트 키는 example.com 도메인의 소수의 예약 주소만 허용합니다. 이 주소들은 유효, 무효, 캐치올, 알 수 없음, 대기 중, 사용 불가 결과를 시뮬레이션합니다. 정확한 주소는 API 레퍼런스의 "무료 샌드박스" 섹션에서 확인할 수 있습니다. 테스트 작업은 완료, 대기 중, 실패, 취소됨 중 고정되고 반복 가능한 상태를 반환합니다. 대량 테스트 작업은 상태 조회, 결과 조회, 취소를 지원합니다.

샌드박스는 이러한 특정 결과를 보여 줍니다. 통합이 거칠 수 있는 모든 경로를 다루지는 않으므로, 7단계에서 설명하는 오류 코드에 대한 별도 처리를 계획하세요.

대량 테스트 작업은 워크스페이스당 시간당 새 작업 20개, 또는 30일당 100개로 제한됩니다. 어느 한도든 초과하면 HTTP 429이 반환됩니다. 동일한 재시도는 여전히 원래 작업을 반환합니다.

2단계: 필요한 범위를 가진 라이브 키로 전환하기

프로덕션용으로는 submit 범위를 가진 라이브 키를 만드세요. 일괄 처리에는 POST /api/v1/jobs를, 단일 주소에는 POST /api/v1/verifications를 사용합니다. 키가 작업 상태와 결과도 읽어야 한다면 read 범위를 추가하세요. 라이브 키에는 balance 범위도 부여할 수 있습니다. 이와 별도로 GET /api/v1/balance는 워크스페이스의 사용 가능 크레딧과 보류 크레딧을 조회합니다. 전체 시크릿은 한 번만 표시되므로 키를 만들 때 안전하게 저장하세요.

라이브 작업은 워크스페이스의 검증 대기열과 크레딧 잔액을 사용합니다. 키 범위, 키 한도, 워크스페이스 접근 권한, 처리 한도는 모두 그대로 적용됩니다.

3단계: 멱등성 키와 함께 작업 제출하기

작업 하나는 JSON 형식으로 1~5,000개의 주소를 최대 2MiB까지 받습니다. 모든 작업 제출과 모든 라이브 단일 주소 제출에 Idempotency-Key 헤더를 함께 보내세요. 키 길이는 8~128자여야 하며 문자, 숫자, 마침표, 콜론, 밑줄, 하이픈을 사용할 수 있습니다.

• 새 작업은 UUID job_id와 함께 HTTP 202을 반환합니다.
• 일치하는 재시도는 동일한 작업과 함께 HTTP 200을 반환합니다.
• 본문을 변경한 채 멱등성 키를 재사용하면 HTTP 409 idempotency_conflict가 반환됩니다.

요청이 처리되었는지 확실하지 않다면 동일한 API 키, 동일한 멱등성 키, 동일한 정규화된 본문으로 재시도하세요. 재실행은 API 키 범위 내에서만 적용되므로, 해당 자격 증명을 교체한 뒤 다시 제출하면 두 번째 실행이 생성될 수 있습니다. 새 실행을 실제로 원할 때만 새 멱등성 키를 사용하세요. 이 경우 요금이 부과될 수 있습니다.

4단계: 작업을 읽고 결과를 페이지 단위로 조회하기

GET /api/v1/jobs/{id}로 작업을 읽습니다. 상태는 대기열에 있음, 실행 중, 일시 중지됨, 취소 중, 취소됨, 완료됨 중 하나입니다. 결과는 GET /api/v1/jobs/{id}/results로 읽습니다. 각 페이지는 최대 50개의 결과와 서명된 next_cursor를 반환합니다. 이 값을 cursor 쿼리 매개변수로 전달하세요. 원래의 필터와 검색 조건이 유지됩니다.

필터는 all, valid, invalid, catch_all, unknown, still_checking, not_checked입니다. 작업을 중지하려면 POST /api/v1/jobs/{id}/cancel로 취소를 요청하지만, 이미 진행 중인 작업은 완료될 수도 있습니다.

레퍼런스에는 서명된 완료 이벤트에 대한 설명과 웹훅 관리 링크도 있습니다.

5단계: 각 결과를 별개의 상태로 취급하기

결과 가이드에서 각 결과의 의미를 설명합니다:

• 유효: 사용 가능한 긍정적 확인 결과입니다. 받은편지함 전달을 보장하지는 않습니다.
• 무효: 주소가 확인을 통과하지 못했습니다.
• 캐치올: 도메인이 많은 주소를 수락할 수 있어 메일함 수준의 결론은 덜 확실할 수 있습니다. 사용하기 전에 세부 정보를 확인하세요.
• 알 수 없음: 확인 과정에서 신뢰할 수 있는 답을 얻지 못했습니다.
• 아직 확인 중: 아직 최종 답이 없습니다.

가이드는 기술적 실패와 처리되지 않은 항목을 알 수 없음과 구분하여 설명하며, API는 unknown, still_checking, not_checked를 별도의 필터로 제공합니다. 자체 데이터에서도 이 상태들을 알 수 없음으로 합치지 말고 별도의 필드나 상태로 관리하세요.

6단계: 대조 전에 크레딧 보류 이해하기

API 레퍼런스에 따르면 확인 항목이 처리 대상으로 승인될 때 워크스페이스 크레딧이 예약됩니다. 이후 결과에는 대시보드와 동일한 차감 및 반환 규칙이 적용됩니다. FairValid 요금 안내에 따르면 크레딧 보류는 진행 중인 확인을 위한 여유분을 확보해 두는 것이며, 최종 결과에 따라 차감 여부가 결정됩니다:

• 유효 또는 무효: 완료된 결과당 크레딧 1개.
• 알 수 없음 또는 캐치올: 최종적으로 차감되는 검증 크레딧이 없습니다. 보류된 크레딧은 해제되거나 반환됩니다.
• 아직 확인 중: 아직 최종 차감이 없습니다. 보류는 완료된 차감이 아닙니다.
• 기술적 실패 및 처리되지 않은 작업: 최종적으로 차감되는 검증 크레딧이 없습니다. 예약된 크레딧은 해제되거나 반환됩니다.

작업 도중에 잔액을 확인한다면, 보류된 크레딧은 아직 최종 차감이 아니라는 점을 기억하세요. 결과가 확정된 후에 대조하세요. 모든 계정에는 매월 무료 크레딧 300개가 포함됩니다. 무료 크레딧이 먼저 사용되며 다음 달로 이월되지 않습니다. 유료 크레딧은 계정이 유지되는 동안 사용하지 않은 만큼 계속 이월됩니다.

7단계: 하나의 재시도 규칙이 아니라 원인별로 오류 처리하기

• 401: 키가 없거나, 폐기되었거나, 필요한 범위가 없습니다. 자격 증명이나 범위를 수정하세요.
• 402 key_cap_reached: 새 요청이 키의 평생 한도를 초과하게 되어 작업이나 보류가 생성되지 않았습니다. 이 한도에는 이미 차감된 크레딧과 승인된 고유 식별 항목을 위해 예약된 크레딧이 합산됩니다. 평생 한도이므로 시간이 지나도 다시 채워지지 않으며 기다린다고 해소되지 않습니다. 권한이 있는 사람에게 해당 키의 한도 설정을 검토하도록 요청하세요. 한도 설정으로 워크스페이스에 크레딧을 추가할 수는 없습니다.
• 422: 잘못된 주소이거나 목록 한도를 초과했습니다. 입력을 수정하세요.
• 503 live_verification_unavailable: 운영상 일시 중지 기간에는 새 라이브 제출이 크레딧을 보류하지 않고 이 오류를 반환할 수 있습니다. 나중에 동일한 멱등성 키로 재시도하세요. 처리 여부가 불확실한 제출 후의 503은 작업이 생성되지 않았다는 증거가 아니므로, 원래 키를 재사용하세요.

모든 오류에는 코드, 메시지, 요청 ID가 포함됩니다. 지원팀에 문의할 때를 대비해 세 가지를 모두 기록해 두세요.

합리적인 작업 순서

1. 샌드박스를 대상으로 통합을 구축하고, 시뮬레이션된 각 결과가 예상한 위치에 반영되는지 확인하세요.
2. 위의 오류 코드에 대한 명시적인 처리를 추가하세요.
3. 필요한 최소 범위와 예산에 맞는 한도를 가진 라이브 키를 만드세요.
4. 작은 라이브 작업으로 시작하세요. 결과와 크레딧 상태를 대시보드와 비교한 다음 규모를 늘리세요.

이 워크플로를 사용해 보고 싶다면, 무료 샌드박스에서 크레딧을 전혀 사용하지 않고 시뮬레이션된 결과를 테스트할 수 있습니다. 정확한 요청 세부 정보는 API 레퍼런스에서 확인하세요.