대량 이메일 검증 API: 실용적인 배치 작업 워크플로

대량 이메일 검증 API: 실용적인 배치 작업 워크플로

질문: 자체 시스템에 대량의 주소 목록이 있습니다. 크레딧 현황을 놓치지 않으면서 이 목록을 FairValid API를 통해 배치로 보내고, 오류를 안전하게 처리하고, 결과를 다시 읽어 오려면 어떻게 해야 할까요?

짧은 답변: 먼저 Test 키로 샌드박스에서 시작하세요. 그런 다음 목록을 최대 5,000개 주소 단위의 작업으로 나누고 작업마다 고유한 멱등성 키를 부여하세요. 각 작업을 Live 키로 제출하고, 상태를 확인한 뒤, 결과별로 페이지를 넘기며 결과를 조회하세요. 대기 중인 검사, 기술적 실패, 알 수 없음 결과는 서로 다른 세 가지 상황으로 구분해 관리하세요.

2026년 11월 13일에 FairValid의 API 레퍼런스, 결과 가이드 및 크레딧 규칙을 기준으로 근거를 확인했습니다.

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

API 레퍼런스에 따르면 API 키 메뉴에서 Test 키를 생성하고, 서버에 보관하고, 기본 URL과 함께 환경에 설정해야 합니다. Test 키는 example.com 도메인의 예약된 주소에서 작동합니다. 제공업체 호출을 하지 않으며 크레딧도 사용하지 않습니다. Test 키는 자체 시뮬레이션 작업에만 접근합니다.

테스트 작업은 완료, 대기, 실패 또는 취소됨이라는 결정론적 상태를 반환합니다. 정확한 샌드박스 주소는 API 레퍼런스에서 확인하고, 이를 사용해 코드가 이러한 상태를 처리하는지 확인하세요. 이 사례들은 설계된 결과만 보여 줍니다. 통합의 모든 분기를 다루지는 않으므로 자체 오류 경로는 별도로 검토하세요.

2단계: 적절한 범위를 가진 Live 키로 전환하기

API 레퍼런스에 따르면 프로덕션에서 작업을 생성하려면 submit 범위가 있는 Live 키가 필요합니다. 작업 상태와 결과를 읽으려면 read 범위를 추가하세요. Live 키에는 balance 범위도 부여할 수 있습니다. 전체 키 시크릿은 한 번만 표시되므로 생성할 때 서버에 안전하게 저장하세요. 폐기된 키로는 새 요청을 할 수 없습니다.

Live 작업은 워크스페이스의 검증 대기열과 크레딧 잔액을 사용합니다. 키 범위, 키 한도, 워크스페이스 접근 권한, 처리 제한은 계속 적용됩니다. Live 키가 무제한 접근을 제공하는 것은 아닙니다.

3단계: 목록을 나누고 작업 제출하기

각 작업에는 JSON 형식으로 1~5,000개의 주소를 최대 2 MiB까지 담을 수 있습니다. 실용적인 방법을 하나 소개합니다.

1. 목록을 청크로 나누세요. 예를 들어 12,000개 주소는 5,000개, 5,000개, 2,000개의 세 작업이 됩니다.
2. 각 청크에 고정된 고유 Idempotency-Key를 부여하고, 어떤 행이 어떤 청크에 들어갔는지 기록하세요. 이 매핑을 자체적으로 보관하면 결과를 레코드에 다시 연결하기가 쉬워집니다.
3. 작업 엔드포인트에 제출하세요. 새 작업은 UUID job_id와 함께 HTTP 202를 반환합니다. 일치하는 재시도는 동일한 작업과 함께 HTTP 200을 반환합니다. 즉, 타임아웃 후 같은 키로 같은 요청을 다시 보내면 기존 작업을 돌려받을 수 있습니다.

4단계: 비슷해 보이는 두 오류 처리하기

두 응답 모두 제출을 막을 수 있지만 의미는 다릅니다.

• HTTP 503 live_verification_unavailable은 운영상 일시 중지 중에 반환될 수 있습니다. API 레퍼런스에 따르면 이 경우 크레딧은 보류되지 않습니다. 나중에 동일한 Idempotency-Key로 재시도하세요.
• HTTP 402 key_cap_reached는 새 요청이 키의 평생 지출 한도를 초과하게 됨을 의미합니다. 이 한도에는 이미 차감된 크레딧과 수락된 고유 식별 항목에 대해 예약된 크레딧이 포함됩니다. 작업이나 보류는 생성되지 않습니다. 평생 한도는 시간이 지나도 다시 채워지지 않으므로 기다려도 해결되지 않습니다. API 키 설정에서 키의 한도를 검토하거나, 해당 작업에 충분한 잔여 한도가 있는 키를 사용하세요. 또한 키 한도로 워크스페이스에 크레딧을 추가할 수는 없습니다. 키 한도는 해당 키가 지출할 수 있는 양만 제한합니다.

적절한 담당자가 적절한 알림을 받을 수 있도록 이 두 응답은 권한 오류 및 처리 제한과 구분해 기록하세요.

5단계: 작업 상태를 추적한 뒤 결과 페이지 조회하기

작업 엔드포인트는 작업의 현재 상태와 요약을 반환합니다. 작업 상태는 대기열에 있음, 실행 중, 일시 중지됨, 취소 중, 취소됨 또는 완료됨일 수 있습니다. 취소를 요청하더라도 이미 진행 중인 작업은 완료될 수 있습니다.

결과 엔드포인트는 서명된 next_cursor와 함께 한 번에 최대 50개의 결과를 반환합니다. 이 값을 cursor 쿼리 매개변수로 전달하세요. 원래의 필터와 검색 조건이 그대로 유지됩니다. 필터는 all, valid, invalid, catch_all, unknown, still_checking, not_checked입니다. 이를 사용해 unknown으로 표시된 항목처럼 결정이 필요한 행만 가져올 수 있습니다.

6단계: 결과를 결정으로 전환하기

결과 가이드는 결과를 전달 보장이 아닌 근거로 설명합니다.

• 유효는 사용할 수 있는 긍정적 검사 결과를 나타냅니다. 받은편지함 전달을 보장하지는 않습니다.
• 무효는 주소가 검사를 통과하지 못했음을 의미합니다.
• 캐치올은 도메인이 여러 주소를 수락할 수 있어 특정 메일함에 대한 결론의 확실성이 낮을 수 있음을 의미합니다. 주소를 사용하기 전에 세부 정보를 확인하세요.
• 알 수 없음은 검사가 신뢰할 수 있는 답을 반환하지 못했음을 의미합니다.
• 확인 중은 아직 최종 답이 없음을 의미합니다. 계속 폴링하고, 알 수 없음으로 취급하지 마세요.

기술적 실패와 처리되지 않은 항목은 별도의 범주입니다. FairValid의 크레딧 규칙에 따르면 이러한 항목은 알 수 없음으로 다시 분류되지 않습니다.

7단계: 크레딧 예약 이해하기

API 레퍼런스에 따르면 워크스페이스 크레딧은 검사가 처리 대상으로 승인될 때 예약됩니다. 결과에는 대시보드와 동일한 차감 및 반환 규칙이 적용됩니다. 크레딧 규칙에 따라 완료된 유효 또는 무효 결과마다 크레딧이 하나씩 차감됩니다. 알 수 없음 및 미해결 캐치올 결과는 보류된 크레딧이 해제되거나 반환되므로 최종적으로 차감되는 크레딧이 없습니다. 대기 중은 최종 결과가 아닙니다. 기술적 실패와 처리되지 않은 작업도 최종적으로 차감되는 크레딧이 없습니다. 반환된 크레딧은 원래의 묶음 및 만료 규칙을 그대로 유지합니다.

잔액 엔드포인트는 라이브 워크스페이스의 사용 가능 크레딧과 보류된 크레딧을 보고합니다. free_allowance_held 필드가 true이면 무료 제공량이 보류된 상태이며 available_credits 또는 free_available에 포함되지 않습니다. 유료 크레딧은 계속 사용할 수 있습니다. 최초 계정은 매월 가입일에 300개의 무료 크레딧을 받으며, 사용하지 않은 무료 크레딧은 이월되지 않습니다. 추가 워크스페이스에는 별도의 무료 제공량이 주어지지 않습니다. 무료 크레딧이 먼저 사용되며, 유료 크레딧은 계정이 유지되는 동안 만료되지 않습니다.

간단한 체크리스트

• Test 키와 문서화된 샌드박스 사례로 테스트하세요.
• submit 및 read 범위가 있고 계획한 작업에 맞는 한도가 설정된 Live 키를 사용하세요.
• 각 청크는 5,000개 주소 이하로 유지하고, 청크마다 고정된 멱등성 키를 하나씩 사용하세요.
• 503는 나중에 같은 키로 재시도하세요. 402는 기다리지 말고 한도 문제를 해결하세요.
• 결과별로 필터링하여 서명된 커서로 결과 페이지를 조회하세요.
• 데이터에서 대기 중, 기술적 실패, 알 수 없음을 구분해 관리하세요.

이 워크플로를 시도해 보고 싶다면 첫 라이브 제출 전에 Test 키를 생성해 크레딧을 사용하지 않고 샌드박스 작업을 실행할 수 있습니다. 전체 엔드포인트 세부 정보는 API 레퍼런스에서 확인하세요.