이메일 유효성 검사 API 문서

API 상태

시작하기

모든 API 요청에는 API 키를 사용한 인증이 필요합니다. 대시보드에서 API 키를 찾을 수 있습니다.

헤더: "X-API-키: YOUR-API-키"

단일 인증

단일 이메일 주소 또는 도메인의 유효성, 일회용 상태, 개인정보 보호 서비스 및 전달 가능성을 확인합니다.

엔드포인트

GET /v1/verify

매개변수

이름	유형	필수	설명
input	string	예	인증할 이메일 주소 또는 도메인(예: [email protected] 또는 example.com)

응답 필드

필드	설명
valid	이메일 형식이 올바른지 여부를 나타냅니다.
block	이메일을 차단할지 여부를 나타냅니다(일회용, 개인 정보 보호, applePrivateEmail, 전달 가능 또는 catch_all이 참이면 참).
disposable	이메일 주소가 임시 이메일 주소인지 일회용 이메일 주소인지 확인합니다.
privacy	메일 서버가 이메일 별칭 또는 전달자를 사용하고 있는지 확인합니다.
applePrivateEmail	이메일이 Apple 비공개 이메일 주소인지 여부를 나타냅니다.
deliverable	사서함이 존재하고 이메일을 받을 수 있는지 확인합니다.
domain	이메일 주소의 도메인 부분
email_address	이메일 주소
catch_all	도메인에 수신자 주소에 관계없이 모든 수신 이메일을 허용하는 포괄적 이메일 구성이 있는지 여부를 나타냅니다.
mx_found	도메인에 유효한 메일 서버(MX 레코드)가 있는지 여부를 나타냅니다.
remaining_credits	계정에 남아 있는 API 크레딧 수

블랙리스트 / 화이트리스트: 차단 필드만 리스트 멤버십을 반영합니다. 블랙리스트 → 차단: 참, 화이트리스트 → 차단: 거짓, 화이트리스트에 없음(활성화된 경우) → 차단: 참. 유효를 사용하여 리스트에 따라 차단 여부를 결정하지 마세요.

응답 예시

{
  "valid": true,
  "block": false,
  "disposable": false,
  "privacy": false,
  "applePrivateEmail": false,
  "deliverable": true,
  "domain": "example.com",
  "email_address": "[email protected]",
  "catch_all": false,
  "mx_found": true,
  "error": null,
  "remaining_credits": 99
}

코드 예제

curl "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

사용해 보기

API 키

엔드포인트를 테스트하려면 API 키가 필요합니다.

이메일 주소 또는 도메인

함께 사용해 보세요:

배치 확인

한 번의 요청으로 여러 이메일 주소 또는 도메인을 확인합니다(최대 100개 항목).

엔드포인트

POST /v1/verify/batch

매개변수

이름	유형	필수	설명
inputs	array of strings	예	확인할 이메일 주소 또는 도메인의 배열

코드 예제

curl -X POST "https://api.verify-email.app/v1/verify/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "inputs": [
      "[email protected]",
      "[email protected]"
    ]
  }'

사용해 보기

API 키

엔드포인트를 테스트하려면 API 키가 필요합니다.

이메일 주소 또는 도메인

다른 도메인으로 시도해 보세요:

결과물 전용 확인

외부 API 호출 없이 MX 및 SMTP 확인을 사용하여 빠른 이메일 전달 가능성 확인. 응답 시간을 단축하기 위해 배달 가능성 관련 필드만 반환합니다.

엔드포인트

GET /v1/verify/deliverable

매개변수

이름	유형	필수	설명
input	string	예	배달 여부를 확인할 이메일 주소(예: [email protected]). 이 엔드포인트에는 도메인 전용 입력이 지원되지 않습니다.

응답 필드

필드	설명
valid	이메일 형식이 올바른지 여부를 나타냅니다.
deliverable	사서함이 존재하고 이메일을 받을 수 있는지 확인합니다.
mx_found	도메인에 유효한 메일 서버(MX 레코드)가 있는지 여부를 나타냅니다.
catch_all	도메인에 수신자 주소에 관계없이 모든 수신 이메일을 허용하는 포괄적 이메일 구성이 있는지 여부를 나타냅니다.
email_address	이메일 주소
remaining_credits	계정에 남아 있는 API 크레딧 수

응답 예시

{
  "valid": true,
  "deliverable": true,
  "mx_found": true,
  "catch_all": false,
  "email_address": "[email protected]",
  "remaining_credits": 99
}

코드 예제

curl "https://api.verify-email.app/v1/verify/[email protected]" \
  -H "X-API-Key: your-api-key"

사용해 보기

API 키

엔드포인트를 테스트하려면 API 키가 필요합니다.

이메일 주소 또는 도메인

함께 사용해 보세요:

화이트리스트 및 블랙리스트

사용자별 블랙리스트·화이트리스트 규칙으로 차단할 이메일과 도메인을 제어합니다. 이 목록이 검증 응답의 block 필드를 직접 설정합니다.

{}

block 필드

모든 검증 응답에는 block 필드가 있습니다. 목록에 따라 이메일/도메인을 차단할지 이 필드로 판단하세요:

true이메일 또는 해당 도메인이 블랙리스트에 있음 → block: true. 도메인을 추가하면 해당 도메인의 모든 이메일이 차단됩니다.

true화이트리스트가 활성화되었지만 이메일/도메인이 목록에 없음 → block: true.

false화이트리스트가 활성화되었고 이메일 또는 해당 도메인이 목록에 있음 → block: false.

—어떤 목록에도 해당하지 않음 → block은 일반 검증 결과를 따릅니다.

개요

✘

블랙리스트

특정 이메일 또는 도메인 전체를 항상 차단합니다. 예: example.com을 블랙리스트에 추가하면 @example.com 이메일은 검증 결과와 관계없이 block: true를 반환합니다.

✔

화이트리스트

특정 이메일 또는 도메인만 허용합니다. 화이트리스트가 활성화되면 목록에 있는 항목만 block: false, 나머지는 block: true입니다. 예: gmail.com을 추가하면 @gmail.com은 허용되고 [email protected]은 차단됩니다. 비활성화 시 화이트리스트는 적용되지 않습니다.

전체 이메일([email protected]) 또는 도메인(example.com)을 추가할 수 있습니다. 도메인을 추가하면 해당 도메인의 모든 이메일에 적용됩니다. 대소문자는 구분하지 않습니다.

작동 방식

평가 순서

먼저 블랙리스트 — 이메일 주소 또는 해당 도메인이 블랙리스트에 있으면 결과는 block: true입니다. 추가 목록 로직은 적용되지 않습니다.

화이트리스트(활성화 시) — 이메일/도메인이 화이트리스트에 있으면 → block: false. 없으면 → block: true.

화이트리스트 비활성화 — 블랙리스트와 일반 검증만 적용됩니다.

블랙리스트가 항상 우선합니다. 블랙리스트에 있는 주소는 화이트리스트에도 있어도 차단된 상태로 유지됩니다.

매칭 대상

이메일 검증 — API는 전체 이메일 주소와 도메인을 두 목록과 모두 대조합니다. 어느 쪽이든 일치하면 목록 규칙이 적용됩니다.

도메인 검증 — 블랙리스트 및 (활성화 시) 화이트리스트와 대조되는 것은 도메인뿐입니다.

빠른 참조

화이트리스트 활성화	블랙리스트에 있음	화이트리스트에 있음	block 값
아니요	예	—	`true`
아니요	아니요	—	일반
예	예	임의	`true`
예	아니요	예	`false`
예	아니요	아니요	`true`

목록 API 엔드포인트

모든 목록 엔드포인트에는 헤더가 필요합니다: X-API-Key: your-api-key

블랙리스트

GET/v1/blacklist

블랙리스트 항목 목록

POST/v1/blacklist

이메일 또는 도메인 추가 · { "value": "..." }

DELETE/v1/blacklist

항목 제거 · value=...

화이트리스트

GET/v1/whitelist

화이트리스트 항목 목록

POST/v1/whitelist

이메일 또는 도메인 추가 · { "value": "..." }

DELETE/v1/whitelist

항목 제거 · value=...

GET/v1/whitelist/enabled

화이트리스트 상태 조회 · { "enabled": boolean }

PUT/v1/whitelist/enabled

화이트리스트 활성화/비활성화 · { "enabled": true | false }

코드 예제 (cURL)

✘

블랙리스트

GET/v1/blacklist

블랙리스트 항목 목록

curl "https://api.verify-email.app/v1/blacklist" \
  -H "X-API-Key: your-api-key"

POST/v1/blacklist

이메일 또는 도메인 추가

curl -X POST "https://api.verify-email.app/v1/blacklist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "value": "[email protected]"
  }'

DELETE/v1/blacklist

항목 제거

curl -X DELETE "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

✔

화이트리스트

GET/v1/whitelist

화이트리스트 항목 목록

curl "https://api.verify-email.app/v1/whitelist" \
  -H "X-API-Key: your-api-key"

POST/v1/whitelist

이메일 또는 도메인 추가

curl -X POST "https://api.verify-email.app/v1/whitelist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "value": "[email protected]"
  }'

DELETE/v1/whitelist

항목 제거

curl -X DELETE "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

GET/v1/whitelist/enabled

화이트리스트 상태 조회

curl "https://api.verify-email.app/v1/whitelist/enabled" \
  -H "X-API-Key: your-api-key"

PUT/v1/whitelist/enabled

화이트리스트 활성화/비활성화

curl -X PUT "https://api.verify-email.app/v1/whitelist/enabled" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "enabled": true
  }'

값 형식

[email protected] — 이메일: 유효한 형식, 예 [email protected]
example.com — 도메인: 유효한 형식, 예 example.com

잘못된 값은 400으로 거부됩니다. 항목은 정규화되어 저장되며 중복은 하나로 합쳐집니다.

목록 적용 위치

목록 규칙은 검증 후 적용됩니다. 단일·일괄 이메일 검증 및 도메인 검증 응답의 block 필드에는 이미 사용자의 블랙리스트와 화이트리스트가 반영되어 있습니다.

MCP 서버(AI 에이전트 통합)

MCP(모델 컨텍스트 프로토콜)를 사용하여 이메일 확인을 Cursor 및 Claude Desktop과 같은 AI 에이전트에 직접 통합하세요. AI 어시스턴트는 편집기를 벗어나지 않고도 이메일을 확인하고, 도메인을 확인하고, 구문의 유효성을 검사할 수 있습니다.

Docs endpoint for AI agents

The API exposes a machine-readable docs endpoint (no API key required) so AI agents and MCP clients can discover the server, available tools, and auth requirements. Use this URL in your agent or MCP configuration.

GET /v1/mcp/docs

Returns JSON with server name, description, serverUrl, docsEndpoint, authentication details, and full tool definitions.

curl "https://api.verify-email.app/v1/mcp/docs"

AI agents can GET this URL to receive server metadata, tool schemas, and integration instructions in JSON. No authentication is required for the docs endpoint.

Open docs endpoint How to add in Cursor How to add in Claude

Integration details

Authentication

All MCP tool calls require your API key in the X-API-Key header. Get your key from the dashboard.

MCP server URL: https://api.verify-email.app/mcp

Docs endpoint (for agents): https://api.verify-email.app/v1/mcp/docs

Cursor

Add the server in Cursor Settings → Tools & MCP, or add the config to .cursor/mcp.json in your project or home directory.

Claude Desktop

Add the server to your Claude Desktop config (mcpServers in claude_desktop_config.json). Use the server URL and X-API-Key header as shown below.

Response format

Tool results match the REST API response shape (valid, block, deliverable, remaining_credits, etc.). Use the block field for blacklist/whitelist decisions.

This MCP server is production-ready and uses the same API as the REST endpoints. Credits are consumed per verification as with the REST API.

설정

.cursor/mcp.json 또는 Claude Desktop 구성 파일에 다음 구성을 추가합니다:

{
  "mcpServers": {
    "email-checker": {
      "url": "https://api.verify-email.app/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

사용 가능한 도구

도구	설명	입력	크레딧
verify_email	구문, MX, SMTP, 일회용, 개인정보 보호 및 전달 가능성 검사를 포함한 전체 이메일 검증	{ email: string }	1
verify_domain	MX 레코드, 일회용, 개인정보 보호 및 캐치올 감지를 포함한 전체 도메인 검증	{ domain: string }	1
check_deliverability	외부 API 호출 없이 MX 및 SMTP 확인을 사용하여 빠른 전송 가능성만 확인합니다.	{ email: string }	1
verify_batch	한 번의 요청으로 최대 100개의 이메일 또는 도메인에 대한 일괄 확인	{ inputs: string[] }	1 per item
validate_email_syntax	네트워크 호출 없이 RFC 5322에 대한 빠른 로컬 구문 유효성 검사	{ email: string }	0 (free)