API Reference

Complete email checker API reference. Endpoints, parameters, response codes for email verification and validation.

EmailVerify API는 강력한 이메일 인증 기능을 제공하는 RESTful 서비스입니다. 모든 API 요청은 HTTPS를 통해 이루어져야 합니다.

기본 URL

https://api.emailverify.ai/v1

인증

모든 API 요청은 Authorization 헤더에 Bearer 토큰을 사용한 인증이 필요합니다:

Authorization: Bearer YOUR_API_KEY

EmailVerify 대시보드에서 API 키를 발급받으세요.

예제

curl -X POST https://api.emailverify.ai/v1/verify \
  -H "Authorization: Bearer bv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

요청 제한

플랜	시간당 요청	일일 요청
Free	100	1,000
Starter	1,000	10,000
Professional	10,000	100,000
Enterprise	맞춤	맞춤

요청 제한 정보는 응답 헤더에 포함됩니다:

헤더	설명
`X-RateLimit-Limit`	허용된 최대 요청 수
`X-RateLimit-Remaining`	윈도우 내 남은 요청 수
`X-RateLimit-Reset`	제한이 재설정되는 Unix 타임스탬프

요청 제한을 초과하면 429 Too Many Requests 응답을 받게 됩니다:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

엔드포인트

단일 이메일 인증

상세 결과와 함께 단일 이메일 주소를 인증합니다.

POST /verify

요청

{
  "email": "user@example.com",
  "smtp_check": true,
  "timeout": 5000
}

파라미터

파라미터	타입	필수	기본값	설명
`email`	string	예	-	인증할 이메일 주소
`smtp_check`	boolean	아니오	`true`	SMTP 메일박스 인증 수행
`timeout`	integer	아니오	`5000`	요청 타임아웃(밀리초, 최대: 30000)

응답

{
  "email": "user@example.com",
  "status": "valid",
  "result": {
    "deliverable": true,
    "valid_format": true,
    "valid_domain": true,
    "valid_mx": true,
    "disposable": false,
    "role": false,
    "catchall": false,
    "free": false,
    "smtp_valid": true
  },
  "score": 0.95,
  "reason": null,
  "credits_used": 1
}

응답 필드

필드	타입	설명
`email`	string	인증된 이메일 주소
`status`	string	인증 상태: `valid`, `invalid`, `unknown`, `accept_all`
`result`	object	상세 인증 결과
`score`	number	신뢰도 점수 (0.0 - 1.0)
`reason`	string	invalid/unknown 상태의 이유 (nullable)
`credits_used`	integer	소비된 크레딧 수

Result 객체 필드

필드	타입	설명
`deliverable`	boolean	이메일이 메시지를 받을 수 있는지 여부
`valid_format`	boolean	이메일이 유효한 구문인지 여부
`valid_domain`	boolean	도메인이 존재하는지 여부
`valid_mx`	boolean	도메인에 MX 레코드가 있는지 여부
`disposable`	boolean	일회용 서비스의 이메일인지 여부
`role`	boolean	역할 기반 이메일인지 여부 (info@, support@)
`catchall`	boolean	도메인이 모든 이메일을 수락하는지 여부
`free`	boolean	무료 제공업체의 이메일인지 여부
`smtp_valid`	boolean	SMTP 인증 통과 여부

대량 이메일 인증

여러 이메일 주소를 인증에 제출합니다. 진행 상황 추적을 위한 작업 ID를 반환합니다.

POST /verify/bulk

요청

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "smtp_check": true,
  "webhook_url": "https://your-app.com/webhooks/emailverify"
}

파라미터

파라미터	타입	필수	기본값	설명
`emails`	array	예	-	이메일 주소 배열 (최대: 10,000)
`smtp_check`	boolean	아니오	`true`	SMTP 인증 수행
`webhook_url`	string	아니오	-	완료 알림을 받을 URL

응답

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 3,
  "processed": 0,
  "valid": 0,
  "invalid": 0,
  "unknown": 0,
  "credits_used": 3,
  "created_at": "2025-01-15T10:30:00Z"
}

대량 작업 상태 확인

대량 인증 작업의 상태를 확인합니다.

GET /verify/bulk/{job_id}

응답 (진행 중)

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 1000,
  "processed": 450,
  "valid": 380,
  "invalid": 50,
  "unknown": 20,
  "progress_percent": 45,
  "created_at": "2025-01-15T10:30:00Z"
}

응답 (완료)

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "total": 1000,
  "processed": 1000,
  "valid": 850,
  "invalid": 100,
  "unknown": 50,
  "progress_percent": 100,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:35:00Z"
}

작업 상태 값

상태	설명
`pending`	작업이 대기열에 있음
`processing`	작업이 처리 중임
`completed`	작업이 성공적으로 완료됨
`failed`	작업이 실패함 (error 필드 참조)

대량 작업 결과 가져오기

완료된 대량 작업의 인증 결과를 가져옵니다.

GET /verify/bulk/{job_id}/results

쿼리 파라미터

파라미터	타입	기본값	설명
`limit`	integer	100	페이지당 결과 수 (최대: 1000)
`offset`	integer	0	시작 위치
`status`	string	-	상태별 필터: `valid`, `invalid`, `unknown`

응답

{
  "job_id": "job_abc123xyz",
  "total": 1000,
  "limit": 100,
  "offset": 0,
  "results": [
    {
      "email": "user1@example.com",
      "status": "valid",
      "result": {
        "deliverable": true,
        "disposable": false,
        "role": false
      },
      "score": 0.95
    },
    {
      "email": "user2@example.com",
      "status": "invalid",
      "result": {
        "deliverable": false,
        "reason": "mailbox_not_found"
      },
      "score": 0.10
    }
  ]
}

크레딧 확인

현재 크레딧 잔액 및 사용 정보를 가져옵니다.

GET /credits

응답

{
  "available": 9500,
  "used": 500,
  "total": 10000,
  "plan": "Professional",
  "resets_at": "2025-02-01T00:00:00Z",
  "rate_limit": {
    "requests_per_hour": 10000,
    "remaining": 9850
  }
}

웹훅

웹훅 생성

POST /webhooks

{
  "url": "https://your-app.com/webhooks/emailverify",
  "events": ["verification.completed", "bulk.completed"],
  "secret": "your-webhook-secret"
}

웹훅 목록

GET /webhooks

웹훅 삭제

DELETE /webhooks/{webhook_id}

웹훅 이벤트

이벤트	설명
`verification.completed`	단일 이메일 인증 완료
`bulk.completed`	대량 작업 완료
`bulk.failed`	대량 작업 실패
`credits.low`	크레딧이 임계값 미만

웹훅 페이로드

{
  "event": "bulk.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "data": {
    "job_id": "job_abc123xyz",
    "status": "completed",
    "total": 1000,
    "valid": 850,
    "invalid": 100,
    "unknown": 50
  },
  "signature": "sha256=..."
}

인증 상태

상태	의미	권장 조치
`valid`	이메일이 존재하며 메시지를 받을 수 있음	발송 안전
`invalid`	이메일이 존재하지 않거나 받을 수 없음	목록에서 제거
`unknown`	유효성을 확인할 수 없음	나중에 재시도하거나 주의해서 사용
`accept_all`	도메인이 모든 이메일을 수락 (캐치올)	반송 여부 모니터링

오류 응답

모든 오류는 일관된 형식을 따릅니다:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

HTTP 상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청 - 유효하지 않은 파라미터
`401`	인증 실패 - 유효하지 않거나 누락된 API 키
`403`	금지됨 - 권한 부족
`404`	찾을 수 없음 - 리소스가 존재하지 않음
`429`	너무 많은 요청 - 요청 제한 초과
`500`	내부 서버 오류
`503`	서비스 사용 불가

오류 코드

코드	HTTP 상태	설명
`INVALID_API_KEY`	401	API 키가 유효하지 않거나 누락됨
`RATE_LIMIT_EXCEEDED`	429	너무 많은 요청
`INSUFFICIENT_CREDITS`	403	크레딧 부족
`INVALID_EMAIL`	400	이메일 형식이 유효하지 않음
`INVALID_REQUEST`	400	요청 본문 형식이 잘못됨
`JOB_NOT_FOUND`	404	대량 작업 ID를 찾을 수 없음
`TIMEOUT`	504	인증 시간 초과

모범 사례

1. 환경 변수 사용

API 키를 하드코딩하지 마세요:

// Good
const apiKey = process.env.EMAILVERIFY_API_KEY;

// Bad - don't do this
const apiKey = 'bv_live_xxx';

2. 요청 제한 처리

지수 백오프를 구현하세요:

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await verify(email);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

3. 여러 이메일에는 대량 처리 사용

10개 이상의 이메일을 인증할 때는 대량 엔드포인트를 사용하세요:

// Good - single API call
const job = await client.verifyBulk(emails);

// Bad - many individual calls
for (const email of emails) {
  await client.verify(email);
}

4. 대량 작업에 웹훅 구현

계속 폴링하지 말고 웹훅을 사용하세요:

// Submit with webhook
const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-app.com/webhook',
});

API Reference

Node.js

Python

Go

PHP

Java

TypeScript

빠른 시작 가이드

인증 유형

통합 가이드

On this page