이메일 검사 API 레퍼런스

인증

POST /v1/email/validate는 X-Api-Key 헤더로 오리진에 고정된 공개 가능 키를 받습니다 — GET /v1/geo와 동일한 키 유형 및 허용 오리진 모델입니다. 이 페이지의 다른 모든 엔드포인트(일괄 검사, 목록 작업, 가입 검사)는 여러 주소나 임의의 IP를 받으므로 Authorization: Bearer로 시크릿 키가 필요하며 반드시 백엔드에서만 호출해야 합니다. 공개 가능 키를 사용하면 403을 받습니다.

예시

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

판정 및 사유 코드

각 조건은 최소 판정을 정하며 가장 심각한 것이 적용되고, reasons에는 해당된 모든 조건이 심각한 순으로 나열됩니다. 무료 제공자 주소를 허용할지는 사용자가 결정하며, 판정을 바꾸지 않습니다.

일괄 검사

POST/v1/email/batch

요청 한 번으로 1–100개 주소를 POST /v1/email/validate와 동일한 검사 및 결과 형식으로 검사하며, 입력 순서대로 주소마다 결과 하나를 반환합니다. { "emails": [...] }를 전송하세요. 같은 도메인의 주소는 DNS 조회 한 번을 공유합니다. 주소당 요청 1건으로 월간 요금제 한도에 계산되며, 한도를 초과하게 될 일괄 검사는 429 monthly_limit_exceeded로 전체가 거부됩니다. 분당 속도 제한에서는 호출 전체가 1건의 요청으로 계산됩니다. 시크릿 키 전용.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

이메일 목록 작업

POST/v1/email/jobs

최대 100,000개 주소를 백그라운드에서 검사합니다. JSON { "emails": [...], "filename": "..." } 또는 최대 10 MB의 text/csv 본문을 전송하세요. 머리글이 email(e-mail, email address, email_address, mail도 가능, 대소문자 구분 없음)인 열이 사용되며, 이를 지정하는 머리글이 없으면 첫 번째 열이 사용됩니다. 쉼표, 세미콜론, 탭 구분자는 자동으로 감지됩니다. 작업은 생성 시점에 과금됩니다 — 고유 주소(완전 일치)당 요청 1건이므로 중복 주소도 검사되지만 한 번만 과금됩니다 — 월간 한도를 초과하게 될 목록은 전체가 거부됩니다. 재시도 후에도 작업의 일부를 처리할 수 없으면 작업이 failed로 표시되고 처리되지 않은 부분의 크레딧이 반환됩니다. 작업 객체와 함께 202를 반환합니다. 시크릿 키 전용이며, 같은 작업을 대시보드의 Email lists 페이지에서 업로드하고 다운로드할 수도 있습니다.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

작업 상태

GET/v1/email/jobs/{id}

같은 작업 객체를 반환합니다. status가 completed가 될 때까지 폴링하세요. 폴링은 과금되지 않습니다.

작업 결과

GET/v1/email/jobs/{id}/results

제출된 행마다 한 행씩, 제출 순서대로(중복 포함) CSV를 다운로드합니다. 열: email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons는 세미콜론으로 구분되고, 빈 셀은 null을 뜻하며, 구문상 유효하지 않은 주소는 조회를 하지 않았으므로 mx_status가 비어 있습니다. =, +, - 또는 @로 시작하는 유효하지 않은 주소에는 스프레드시트 앱이 수식으로 실행하지 않도록 앞에 아포스트로피가 붙습니다. 작업이 완료될 때까지는 409, 만료된 후에는 410. 다운로드는 과금되지 않습니다.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

가입 검사

POST/v1/signup/check

가입 양식이 제출될 때 백엔드에서 한 번의 호출로 이메일 주소와 IP를 기반으로 가입을 점수화합니다(브라우저에서 계산한 판정은 위조될 수 있습니다). { "email": "...", "ip": "...", "userAgent": "..." }를 전송하세요 — userAgent는 선택 사항입니다. 응답에는 전체 이메일 검사 결과(email), IP의 국가와 ASN 및 — 보안 데이터가 포함된 요금제에서는 — VPN/Tor/데이터센터/위협 지표(ip), 공개 등록(RDAP) 데이터 기준 이메일 도메인의 경과 일수(emailDomainAgeDays, 알 수 없거나 잘 알려진 소비자용 제공자인 경우 null), 0–100 점수(아래 사유 가중치의 합, 최대 100), 판정(60 이상 reject, 25 이상 review, 그 외 accept)이 포함됩니다. 보안 데이터가 없는 요금제에서는 ip.security가 null이고, 점수는 이메일 신호만 사용하며, reasons에 ip_security_unavailable이 포함됩니다. 요청 1건으로 계산됩니다. 시크릿 키 전용.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

제한 사항

검사한 모든 주소는 요금제의 공유 월간 한도에서 요청 1건으로 계산됩니다 — 단일 검사, 일괄 검사의 각 주소, 목록 작업의 각 고유 주소 — 가입 검사는 요청 1건입니다. 일괄 검사와 목록 작업은 전체가 승인되거나 거부되며, 부분적으로 처리되지 않습니다. 분당 속도 제한은 항목 수가 아니라 HTTP 호출 수를 셉니다. 최대 100개의 IP 또는 이메일 주소를 담은 배치는 1건의 요청으로 계산되며, 각 항목은 여전히 월간 요청 한도에 개별적으로 계산됩니다. 목록 작업의 업로드와 결과는 작업 생성 7일 후 삭제됩니다. DNS 조회에는 짧은 시간 예산이 있어, 실패하거나 시간 초과되면 오류 대신 mx.status unknown과 사유 dns_unavailable로 저하됩니다. 일회용 도메인 데이터는 커뮤니티가 관리하는 세 가지 오픈 소스 목록을 병합한 것으로, 몇 시간마다 갱신되며 목록에 있는 도메인을 처리하는 것으로 관찰된 메일 서버로 확장됩니다 — 데이터 소스를 참고하세요. 아주 새로운 일회용 제공자는 아직 표시되지 않을 수 있습니다. 모든 검사는 도메인 및 주소 수준에서 이루어집니다. 어떤 메일함에도 접속하지 않으므로, 어떤 결과도 메일함이 존재하는지, 누가 소유하는지, 메일이 도착할지를 입증하지 않습니다.