Email Verifier REST API 레퍼런스

Email Verifier API는 /api/v1에서 제공됩니다. 계정 로그인에 사용하는 TrekMail 호스트를 이용하세요. 아래 예시에서는 https://YOUR-TREKMAIL-HOST를 자리표시자로 사용합니다.

인증 및 범위

API 토큰을 Authorization 헤더로 전달합니다.

Authorization: Bearer YOUR_API_TOKEN

토큰을 만들 때 범위를 활성화하세요.

클라이언트가 작업을 제출한 뒤 결과를 읽거나 다운로드해야 한다면 두 범위를 모두 부여하세요.

호스트 및 요청 형식

모든 예시는 JSON 요청 본문과 Bearer 토큰을 사용합니다. 대시보드 파일 업로더는 API와 별개입니다. POST /verify/bulk는 multipart 파일이 아니라 JSON emails 배열을 받습니다. 계정과 토큰에 속한 정확한 호스트를 사용하세요. 한 브랜드 호스트의 토큰이나 잔액이 다른 호스트에서 작동한다고 가정하지 마세요.

POST /verify와 POST /verify/bulk 요청에는 Content-Type: application/json을 전송합니다. 토큰과 멱등성 값은 클라이언트측 코드 외부에 보관하세요.

멱등성

POST /api/v1/verify/bulk와 DELETE /api/v1/verify/bulk/{jobId}에는 Idempotency-Key 헤더가 필요합니다. 의도한 작업마다 새 값을 만들고 동일 작업을 재시도할 때만 재사용하세요.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

단일 검증과 작업 취소에는 이 헤더가 필요하지 않습니다. 동일하게 정규화된 목록과 모드를 24시간 안에 대량 요청하면 중복 목록 감지로도 보호되지만, 재시도에는 멱등성 키를 사용해야 합니다.

네트워크 결과가 불확실할 때

대량 요청의 응답을 잃었다면 새 키를 만들거나 목록을 다시 제출하지 마세요. 같은 키로 동일 요청을 반복하세요. TrekMail이 작업 ID를 반환할 때까지 원본 목록 식별자와 키를 함께 저장합니다. 이렇게 하면 재시도가 원래 작업과 연결되어 불필요한 이중 과금을 막습니다.

엔드포인트 요약

표의 모든 경로 앞에 /api/v1을 붙이세요.

크레딧 잔액 조회

GET /api/v1/verify/credits

표준 TrekMail 호스트에서는 플랜 할당량과 구매 잔액을 반환합니다.

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

White Label 호스트에서는 구매 크레딧만 브랜드 제품에 제공되므로 응답에는 purchased_balance와 total_available가 포함됩니다.

요청 예시:

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

큰 작업을 제출하기 직전에 잔액을 읽으세요. 잔액 응답은 그 시점의 값입니다. 여러 작업을 제출하는 앱은 오래된 잔액으로 나중에 계산하지 말고 각 대량 응답의 과금액을 기록해야 합니다.

잔액 필드

White Label은 구매 크레딧만 사용하므로 잔액 응답의 필드가 의도적으로 더 적습니다.

주소 1개 검증

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

응답에는 email, status, trust_score, checks, provider, risk_factors, credits_remaining이 포함됩니다. 표준 호스트의 credits_remaining에는 monthly와 purchased 값이 있습니다. 상세 checks 구조는 모드와 수신 제공자가 공개하는 정보에 따라 달라질 수 있습니다.

Quick은 1크레딧입니다. Deep은 보통 2크레딧이며 제공자별 예외는 1크레딧으로 계산됩니다. 과금 후 검증을 실행할 수 없으면 단일 주소 요청은 해당 크레딧을 환불하고 일시적 사용 불가 응답을 반환합니다.

요청 예시:

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"}'

일반적인 앱 계약에는 최상위 status, trust_score, provider, risk_factors를 사용하세요. checks는 유용한 보조 자료지만 외부 검사가 생략되거나 불가능하거나 Deep이 추가 정보를 얻으면 개별 키가 달라질 수 있습니다.

단일 결과 해석

수락된 원격 응답을 소유권이나 권한 확인으로 처리하지 마세요. 구독, 수신 거부, 연락처 선호 결정은 별도로 관리합니다.

대량 작업 생성

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

중복은 가격 계산 전에 정규화됩니다. 새 작업이 성공하면 201을 반환합니다.

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

probe와 skip은 Deep 가격 계산을 설명합니다. deep_savings는 모든 제출 주소를 전체 Deep 요율로 과금할 때와의 차이입니다. 중복 목록이면 새 작업 대신 기존 job_id와 상태를 반환합니다.

요청 예시:

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

API는 작업 수락 전에 이메일 구문을 검사합니다. 모두 거부되면 422를 반환하고 작업을 만들지 않습니다. 일부가 거부되면 rejected_count와 rejected_sample에 최대 5개 값을 반환합니다. 이 작은 샘플을 전체 정리 보고서로 사용하지 말고 가져오기 도구의 원본 검증 결과를 보관하세요.

대량 제출 체크리스트

1. 앱에서 원본을 읽고 정규화합니다.
2. 요청을 50,000개 이하로 제한합니다.
3. 요청 전에 멱등성 키를 생성하고 보관합니다.
4. 운영자가 나중에 알아볼 수 있는 이름을 지정합니다.
5. TrekMail이 반환한 job_id, credits_charged, 가격 내역을 저장합니다.
6. 저장한 job_id를 폴링하고 원래 HTTP 요청으로 완료를 추정하지 않습니다.

작업 조회

GET /api/v1/verify/bulk/{jobId}

기본 응답에는 job_id, name, status, total, processed, progress, summary, created_at, completed_at이 포함됩니다.

완료, 부분 완료 또는 실패한 작업에 결과가 있으면 다음도 포함됩니다.

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

선택적 쿼리 매개변수:

처리된 행이 있는 취소 작업은 다운로드할 수 있지만 내보내기에는 다운로드 엔드포인트를 사용하세요.

추측하지 않고 작업 상태 읽기

API 클라이언트는 백오프로 폴링해야 합니다. 기존 작업이 대기 중이거나 네트워크 요청이 로컬에서 만료됐다는 이유만으로 새 대량 제출을 하지 마세요.

상태 응답 예시

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

작업이 진행되며 summary가 늘어날 수 있습니다. 앱이 인식하는 범주만 합산하지 말고 processed와 total로 진행률을 표시하세요.

작업 다운로드

GET /api/v1/verify/bulk/{jobId}/download

처리된 행이 있는 완료, 부분, 취소 작업에서 다운로드할 수 있습니다. Email, Status, Trust Score, Provider, Risk Factors 열이 있는 CSV를 스트리밍합니다.

예시:

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

15일 결과 보존 기간 안에 다운로드 결과를 저장하세요. CSV는 자체 흐름을 위한 내보내기이며 다른 시스템의 동의, 구독, 연락처 레코드를 변경하지 않습니다.

처리된 내보내기가 없으면 다운로드 엔드포인트가 충돌을 반환합니다. 먼저 상태를 확인하세요. 성공 시 JSON 래퍼 대신 CSV가 스트리밍되므로 HTTP 클라이언트에서 파일 응답으로 처리합니다.

작업 목록

GET /api/v1/verify/bulk

page, per_page와 선택적 status를 사용합니다. per_page 기본값은 20이며 1에서 100까지 허용합니다. 상태 값은 pending, processing, completed, partial, cancelled, failed입니다.

응답에는 jobs 배열과 pagination 객체가 있습니다. 각 작업 레코드에는 ID, 이름, 상태, 합계, 처리 수, 진행률, 시간이 포함됩니다.

예시:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

워커 재시작 또는 작업 ID 조정 시 목록 엔드포인트를 사용하세요. 작업 이름을 고유 식별자로 보지 말고 반환된 숫자 job_id를 저장합니다.

작업 목록 응답 형식

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

운영 페이지에 활성 또는 완료 작업만 필요하면 status를 사용합니다. 많은 목록을 검증하는 계정에는 페이지네이션이 중요합니다. 한 응답이 전체 기록을 담는다고 가정하지 마세요.

작업 취소

POST /api/v1/verify/bulk/{jobId}/cancel

대기 또는 실행 중인 작업만 취소합니다. 성공 응답:

{"status":"cancelled","credits_refunded":40}

미처리 작업에 대해 환불됩니다. 취소가 도착하기 전에 종료 상태가 되면 API는 결과를 바꾸지 않고 충돌을 반환합니다.

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

취소는 작업을 삭제하지 않습니다. 필요하면 처리된 행을 다운로드하거나 완료 레코드를 나중에 삭제하세요.

작업 삭제

DELETE /api/v1/verify/bulk/{jobId}

실행 작업은 먼저 취소하세요. TrekMail이 준비된 원본 목록을 안전하게 제거한 뒤 작업과 결과를 영구 삭제합니다. 성공 응답:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

Verifier 레코드에 영구적인 작업입니다. 앱이 이미 다운로드한 CSV는 회수되지 않으므로 해당 사본에 자체 보존 절차를 적용하세요.

삭제 순서

1. 작업 상태를 읽습니다.
2. 대기 또는 처리 중이면 취소합니다.
3. 보존해야 하는 처리된 내보내기를 저장합니다.
4. 실행 중이 아닌 작업을 멱등성 키로 삭제합니다.
5. 자체 시스템의 사본을 개인정보 보호 및 보존 규칙에 따라 제거합니다.

오류 및 재시도

단일 검증의 제한은 분당 60건, 대량 제출은 분당 10건입니다. 백오프를 구현하고 대량 재시도에 같은 키를 유지하며 알 수 없는 네트워크 결과 후 맹목적으로 재시도하지 마세요.

안전한 재시도 방식

1. 대량 제출 전에 멱등성 키 하나를 생성하고 저장합니다.
2. 해당 키로 요청을 제출합니다.
3. 응답을 잃으면 같은 키로 동일 요청을 재시도합니다.
4. 반환된 job_id를 저장하고 해당 원본 목록의 새 제출을 중단합니다.
5. 종료 상태까지 폴링한 뒤 결과를 다운로드하거나 처리합니다.

단일 검증에서 일시적 503은 서비스가 검사를 완료하지 못했다는 뜻입니다. 정상적인 백오프로 나중에 재시도하고 자체 데이터베이스에서 Invalid 결과로 바꾸지 마세요.

연락처 데이터 보호

이메일 목록은 많은 경우 개인정보입니다. 검증에 필요한 데이터만 전송하고 토큰 접근을 작업 시스템으로 제한하며 전체 주소 배열을 앱 로그에 남기지 마세요. 필요하면 전체 목록 대신 작업 ID, 수, 시간, 상위 수준 결과를 기록합니다.

TrekMail은 결과를 15일 동안 보존합니다. 대용량 목록 통합 전에 자체적인 안전한 내보내기 저장 또는 삭제 경로를 계획하세요.

검증 신호는 소유권, 동의 또는 향후 전달을 증명하지 않습니다. 주소가 Safe여도 권한과 억제를 앱에서 계속 관리하세요.