이메일 검증 API 문서
이메일 주소 1개 검증, 대량 검증, 캐치올 도메인 주소와 SEG로 보호되는 주소의 정밀 검사를 할 수 있습니다. 모든 엔드포인트는 JSON을 쓰고 API 키로 인증하며, 성공한 검증에만 요금이 부과됩니다.
소개
Giggal.ai API로 이메일 주소 1개 검증, 작업 1건당 최대 50,000개의 대량 검증, 캐치올 도메인 주소와 SEG로 보호되는 주소의 정밀 검사를 할 수 있습니다. JSON을 쓰는 간단한 REST API입니다. 검증이 성공할 때마다 계정의 크레딧이 차감됩니다.
https://api.giggal.ai/v1API 키는 Giggal.ai 대시보드에서 만듭니다. 사이드바에서 “Developer API” 탭을 열고 “Create API Key”를 클릭하십시오. 각 키는 계정에 연결되고, 키별로 사용량이 기록되며, 언제든지 폐기할 수 있습니다.
“Developer API” 탭 열기모든 응답은 같은 JSON 구조를 따릅니다.
// Success
{ "success": true, "data": { ... }, "meta": { ... } }
// Error
{ "success": false, "error": "Human-readable error message" }curl -X POST https://api.giggal.ai/v1/verify \
-H "Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email":"info@giggal.ai"}'인증
모든 요청에 다음 두 헤더 중 하나로 API 키를 보내십시오. 둘 다 작동합니다.
Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxX-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx키가 없거나, 잘못되었거나, 폐기된 경우 HTTP 401 오류가 반환됩니다. API 키를 클라이언트 측 코드에 노출하지 마십시오. 대신 자체 백엔드를 거쳐 API를 호출하십시오.
POST /v1/verify-batch 요청과 POST /v1/catchall 요청에는 Idempotency-Key 헤더를 보내십시오. 같은 키로 다시 요청하면 처음 응답이 그대로 반환됩니다. 작업이 중복으로 만들어지지 않고, 크레딧이 두 번 차감되지도 않습니다.
Idempotency-Key: 2026-07-24-list-batch-42단일 검증
이 그룹에는 엔드포인트가 1개 있습니다.
/v1/verify이메일 주소 1개 검증
이메일 주소 1개를 동기 방식으로 검증합니다. 크레딧 1개가 차감됩니다. 도메인이 캐치올 도메인이면 같은 요청 안에서 정밀 검사가 실행되고, 응답에 catch_all_score 필드와 catch_all_verdict 필드가 포함됩니다.
대량 검증
이 그룹에는 엔드포인트가 3개 있습니다.
/v1/verify-batch대량 검증 작업 제출
작업 1건당 이메일 주소를 최대 50,000개까지 보낼 수 있습니다. 처리는 비동기로 진행되므로, GET /v1/jobs/:jobId 엔드포인트로 진행 상황을 확인하십시오. Idempotency-Key 헤더를 보내면 이중 과금 없이 작업 생성을 안전하게 다시 시도할 수 있습니다.
/v1/jobs/:jobId대량 검증 작업 상태 조회
진행 상황을 확인할 때 호출합니다. 상태는 processing에서 completed(또는 failed)로 바뀝니다. 권장 조회 간격은 10~15초입니다. 작은 작업(이메일 50개 미만)은 보통 30초 안에 끝납니다.
/v1/jobs/:jobId/results대량 검증 작업 결과 조회
상태가 "completed"가 되면 이메일 주소별 결과를 가져옵니다. 결과는 페이지로 나뉘어 있으므로 page 및 limit 쿼리 매개변수를 보내십시오. 결과는 48시간 동안 보관됩니다(작업의 resultsExpiresAt 필드 참고).
캐치올 검증
이 그룹에는 엔드포인트가 4개 있습니다.
/v1/catchall캐치올 검증 작업 시작
완료된 대량 검증 작업에 대해 캐치올 도메인 정밀 검사를 시작합니다. 원래 작업에서 캐치올 도메인으로 표시된 주소만 다시 검사합니다. 주소 1개당 크레딧 1개가 부과됩니다(응답의 creditsRequired 필드 참고).
/v1/catchall/:taskId캐치올 검증 작업 상태 조회
진행 상황과 실시간 verdictCounts 값을 확인할 때 호출합니다. 캐치올 검증 작업은 주소 수에 따라 보통 몇 초에서 몇 분 안에 끝납니다.
/v1/catchall/:taskId/results캐치올 검증 작업 결과 조회
이메일 주소별 결과를 페이지로 나누어 가져옵니다. 점수의 세부 내역(도메인 분류 신호와 도메인 연령)도 포함됩니다.
/v1/catchall/:taskId/download캐치올 검증 결과 CSV 다운로드
완료된 캐치올 검증 작업의 전체 결과를 Email, Score, Verdict 열이 있는 CSV 파일로 내려받습니다. Content-Type 값은 text/csv입니다.
계정
이 그룹에는 엔드포인트가 1개 있습니다.
/v1/credits현재 크레딧 잔액 조회
계정 잔액을 반환합니다. 사용 가능한 크레딧, 예약된 크레딧(진행 중인 작업을 위해 확보한 크레딧), 계정 개설 이후 누적 합계가 포함됩니다. 결과가 "unknown"인 검증의 크레딧은 자동으로 환불되며 여기에도 반영됩니다.
오류와 요청 한도
| 상태 | 의미 |
|---|---|
| 200 OK | 요청이 성공했습니다(동기 검증, 또는 상태나 결과 조회). |
| 202 Accepted | 비동기 작업이 만들어져 대기열에 들어갔습니다. |
| 400 Bad Request | 매개변수가 없거나 잘못되었습니다(잘못된 이메일 형식, 비어 있는 emails 배열, jobId 누락). |
| 401 Unauthorized | API 키가 없거나, 잘못되었거나, 폐기되었습니다. |
| 402 Payment Required | 요청한 작업에 필요한 크레딧이 부족합니다. |
| 404 Not Found | 해당 작업 ID가 계정에 존재하지 않습니다. |
| 409 Conflict | 작업이 필요한 상태가 아닙니다(예: 작업이 끝나기 전에 결과를 요청한 경우). |
| 410 Gone | 작업 결과의 48시간 보관 기간이 지났습니다. |
| 429 Too Many Requests | 요청 한도를 넘었습니다. 잠시 기다린 후 다시 시도하십시오. |
| 500 / 502 / 503 | 서버 또는 그 뒤의 검증 서비스를 일시적으로 사용할 수 없습니다. |
요청 한도
모든 응답에는 RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset 헤더(RFC 표기)가 들어 있어 요청 간격을 조절할 수 있습니다. RateLimit-Reset 값은 현재 시간 창이 초기화될 때까지 남은 초입니다.
| 구분 | 한도 |
|---|---|
| 모든 엔드포인트(기본값) | 15분당 요청 300회 |
| 작업 생성(POST /v1/verify-batch, POST /v1/catchall) | 15분당 요청 30회 |
| 작업 상태 조회(GET /v1/jobs/:id, GET /v1/jobs/:id/results) | 15분당 요청 600회 |
| 대량 검증 작업 1건당 최대 이메일 수 | 50,000 |
| 작업 결과 보관 기간 | 48시간 |
한도를 세 구간으로 나눈 이유는 상태 조회가 작업 생성보다 자연스럽게 더 자주 일어나기 때문입니다. 작업이 실행되는 동안 몇 초마다 상태를 조회할 수도 있습니다. 600 / 15 min 한도(1분에 약 40회)라면 서버에 부담을 주지 않고 충분히 조회할 수 있습니다.
더 높은 한도가 필요하십니까?
확인된 연동 파트너에게는 평소에도 한도를 높여 드리고 있습니다.
429 응답 형식
요청 한도에 도달하면 API는 다음 본문과 함께 HTTP 429 오류를 반환합니다.
{
"success": false,
"message": "Developer API rate limit exceeded"
}다시 시도하기 전에 RateLimit-Reset 헤더 값(시간 창이 초기화될 때까지 남은 초)만큼 기다리십시오.
API를 연동할 준비가 되셨습니까?
API 키는 몇 초 만에 만들 수 있습니다. 무료 체험 크레딧이 포함되어 있어, 비용을 쓰기 전에 처음부터 끝까지 연동을 시험할 수 있습니다.