API Documentation

Authorization: Bearer sk_live_your_api_key_here

Get your API key from the API Keys page. Keep it secret — treat it like a password.

Verify a single email address. Returns validation results including syntax, disposable detection, and DNS/MX checks.

Request Body

{
  "email": "user@example.com"
}

Response (200)

{
  "email": "user@example.com",
  "valid": true,
  "score": 90,
  "reason": "deliverable",
  "checks": {
    "syntax": { "valid": true },
    "disposable": { "is_disposable": false },
    "dns": { "has_mx": true, "has_a": true, "mx_records": ["mx1.example.com"] }
  },
  "cached": false,
  "verified_at": "2026-02-14T18:00:00.000Z"
}

cURL

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

Node.js

const res = await fetch('https://api.mailcheck.dev/v1/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'test@example.com' }),
});
const data = await res.json();
console.log(data.valid); // true

Python

import requests

resp = requests.post(
    'https://api.mailcheck.dev/v1/verify',
    headers={'Authorization': 'Bearer sk_live_your_key'},
    json={'email': 'test@example.com'},
)
data = resp.json()
print(data['valid'])  # True

Returns your account details, plan, and current month's usage.

Response (200)

{
  "email": "you@example.com",
  "plan": "free",
  "monthly_limit": 100,
  "usage": {
    "current_month": 42,
    "remaining": 58
  },
  "api_key": {
    "prefix": "sk_live_abc",
    "created_at": "2026-02-01T00:00:00.000Z",
    "last_used_at": "2026-02-14T12:00:00.000Z"
  }
}

cURL

curl https://api.mailcheck.dev/v1/account \
  -H "Authorization: Bearer sk_live_your_key"

Revokes your current API key and generates a new one. Save the new key immediately — your old key stops working.

Response (200)

{
  "message": "API key rotated successfully",
  "api_key": "sk_live_new_key_here",
  "warning": "Your old key is now revoked. Save this new key."
}

cURL

curl -X POST https://api.mailcheck.dev/v1/account/rotate-key \
  -H "Authorization: Bearer sk_live_your_old_key"

Create a new account and receive an API key. No authentication required. Rate limited to 3 requests per hour per IP.

Request Body

{
  "email": "you@example.com",
  "password": "min8characters",
  "name": "Optional Name"
}

Response (201)

{
  "message": "Account created successfully",
  "customer_id": "uuid-here",
  "api_key": "sk_live_your_new_key",
  "plan": "free",
  "monthly_limit": 100
}

All errors return JSON: { "error": "...", "message": "..." }

When rate limited, you'll receive a 429 response with a Retry-After header.

Cached verification results don't count against your monthly quota.