Email Verifier API 빠른 시작 안내서

검증을 자체 제품이나 가져오기 워크플로에 포함해야 할 때 API를 사용하세요. verify:read 및 verify:write 범위가 있는 토큰을 만들고 비밀로 보관한 다음, 로그인할 때 사용하는 동일한 호스트를 호출하세요. 예시에서는 https://YOUR-TREKMAIL-HOST와 YOUR_API_TOKEN을 바꾸세요.

1. 토큰 만들기

1. 대시보드 → AI Agents & API를 엽니다.
2. 토큰을 만듭니다.
3. verify:read와 verify:write를 활성화합니다.
4. 토큰을 안전하게 보관합니다. 토큰은 한 번만 표시됩니다.

모든 요청에 토큰을 보내세요.

Authorization: Bearer YOUR_API_TOKEN

토큰은 비밀 저장소나 환경 변수에 보관하세요. 브라우저 측 코드, 공개 저장소, 지원 요청 또는 내보낸 연락처 파일에 넣지 마세요. 노출되었다고 의심되면 토큰을 폐기하고 대시보드에서 대체 토큰을 만드세요.

2. 주소 하나 검증하기

단일 주소 결과를 즉시 받으려면 POST /api/v1/verify를 사용하세요. mode를 생략하면 Quick이 기본값입니다.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

응답에는 주소, 상태, 신뢰 점수, 제공업체, 위험 요소 및 남은 크레딧과 같은 안정적인 최상위 필드가 포함됩니다. checks 객체는 상세 근거를 기록하며, 검사를 사용할 수 없거나 Deep 모드에 추가 정보가 있을 때 달라질 수 있습니다.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

먼저 status와 trust_score를 읽으세요. 개별 검사 키는 보조 정보로 취급하고, 받은편지함 소유권이나 전송을 보장하는 것으로 보지 마세요.

단일 endpoint에는 분당 60개 요청의 경로 제한이 있습니다. 가입 중 사용자가 입력한 주소를 확인하는 경우 기본적인 클라이언트 측 검증 후 호출하세요. 서비스가 일시적으로 중단되면 사용자를 무기한 막지 말고 이해하기 쉬운 오류를 표시하세요.

3. 대량 작업 제출하기

대량 요청은 파일 업로드가 아니라 JSON emails 배열을 받습니다. 네트워크 재시도로 두 번째 작업이 생성되지 않도록 멱등성 키를 포함하세요.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"September contacts",
    "mode":"deep",
    "emails":["first@example.com","second@example.net"]
  }'

목록에는 최대 50,000개 항목을 포함할 수 있습니다. TrekMail은 중복 항목을 정규화하고 구문상 잘못된 항목은 작업에서 거부합니다. 응답은 작업 ID, 허용된 수, 거부된 항목의 작은 샘플, 청구된 크레딧 및 Deep 가격 내역을 보고합니다.

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe는 전체 Deep 요금으로 청구된 수입니다. skip은 제공업체가 유용한 사서함 수준 근거를 제공하지 않기 때문에 일반 요금으로 청구된 수입니다. 응답이 해당 제출에 대한 최종 비용을 제공합니다.

전체 목록을 제출하기 전에 자체 가져오기 도구에서 주소가 아닌 값을 제거하세요. API는 주소 중복을 제거하고 거부된 수를 보고하지만, 소스를 검증하면 더 명확한 감사 기록이 남습니다. 애플리케이션 관점에서 요청 시간이 초과되면 동일한 멱등성 키로 같은 대량 요청을 다시 시도하고, 새 제출을 만들기 전에 반환된 작업 ID를 확인하세요.

4. 폴링 및 다운로드

작업이 최종 상태에 도달할 때까지 GET /api/v1/verify/bulk/{jobId}로 폴링하세요.

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

응답에는 status, total, processed, progress, summary, 생성 시간 및 완료 시간이 포함됩니다. 완료 및 부분 완료 작업에는 페이지가 매겨진 results 배열이 포함됩니다.

합리적인 간격을 두고 대기 시간을 늘리며 폴링하세요. 작업 시작 전에 보류 상태로 남아 있을 수 있고, 수신 제공업체가 추가 근거를 제공하면 Deep 작업에 더 오래 걸릴 수 있습니다. 목록 크기만으로 고정된 완료 시간을 가정하지 마세요.

결과를 사용할 수 있게 된 후 더 작은 결과 페이지를 요청하거나 알려진 주소를 찾을 수 있습니다.

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

처리된 작업을 CSV로 다운로드하세요.

curl -o results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API 내보내기 필터는 all, safe, safe_risky(Safe + Valid + Risky)입니다.

보류 중이거나 실행 중인 작업을 중지하려면 취소 endpoint를 사용하세요. 처리되지 않은 작업의 크레딧은 환불되고 처리된 행은 유지됩니다.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Verifier 작업 기록과 결과를 모두 제거하려는 경우에만 작업을 삭제하세요. 아직 실행 중이면 먼저 취소한 다음 멱등성 키를 사용해 삭제 endpoint를 호출하세요. 전체 참조 문서에는 두 호출이 모두 나와 있습니다.

5. 일반적인 응답 처리하기

• 402: 계정에 크레딧이 더 필요합니다.
• 422: 요청 본문, 선택한 모드 또는 대량 요청에 필요한 멱등성 키를 확인하세요.
• 429: 요청 속도를 낮추고 대기 시간을 늘려 다시 시도하세요.
• 503: 검증을 일시적으로 사용할 수 없습니다. 나중에 다시 시도하세요. 실패한 단일 주소 검증에 대한 크레딧은 환불됩니다.

프로덕션 연동 체크리스트

1. 토큰을 서버 측에 보관하고 필요한 두 개의 Verifier 범위만 부여합니다.
2. 대량 API를 호출하기 전에 연락처 입력을 검증하고 정규화합니다.
3. 작업 ID, 제출한 목록 식별자, 멱등성 키 및 반환된 credits_charged 값을 저장합니다.
4. 빠듯한 루프 대신 대기 시간을 늘리며 폴링합니다.
5. 15일 보존 기간이 끝나기 전에 CSV를 저장하거나 처리합니다.
6. 동의, 수신 거부 및 제외 결정은 자체 애플리케이션에서 관리합니다. Verifier 결과가 이를 대신하지 않습니다.

모든 endpoints, 범위 및 응답 필드는 Email Verifier REST API 참조를 확인하세요.