API Documentation

Everything you need to integrate EmailProbe into your application.

Base URL

All API requests are made to the following base URL:

https://api.emailprobe.dev

Open API (no auth required): https://api.emailprobe.dev/open/v1/disposable/:domain

Authentication

All authenticated endpoints require an API key passed via the Authorization header. You receive your API key when you create an account.

# Include this header in every authenticated request Authorization: Bearer ep_live_your_key

The open disposable-check endpoint (https://api.emailprobe.dev/open/v1/disposable/:domain) does not require authentication.

Endpoints

POST https://api.emailprobe.dev/v1/validate Single email validation

Validates a single email address and returns a comprehensive risk assessment including score, verdict, and detailed checks.

Request
# Full URL curl -X POST https://api.emailprobe.dev/v1/validate \ -H "Authorization: Bearer ep_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]" }'
Response (200)
{ "safe": true, "score": 92, "verdict": "safe", "is_disposable": false, "is_free_provider": true, "is_role_account": false, "is_privacy_relay": false, "syntax_valid": true, "has_mx_record": true, "mx_records": ["mail.example.com"], "has_spf": true, "has_dkim": true, "has_dmarc": true, "suggestion": null, "alias": false, "normalized_email": "[email protected]" }
API Key
Email
GET https://api.emailprobe.dev/v1/domain/:domain Domain-only check

Checks domain-level signals without requiring a full email address. Useful for pre-filtering at the domain level.

Request
curl https://api.emailprobe.dev/v1/domain/tempmail.com \ -H "Authorization: Bearer ep_live_your_key"
Response (200)
{ "domain": "tempmail.com", "is_disposable": true, "has_mx_record": true, "mx_records": ["mx.tempmail.com"], "has_spf": false, "has_dkim": false, "has_dmarc": false, "score": 12 }
API Key
Domain
GET https://api.emailprobe.dev/v1/usage Usage statistics

Returns your current usage statistics for the billing period, including breakdown by result type.

Request
curl https://api.emailprobe.dev/v1/usage \ -H "Authorization: Bearer ep_live_your_key"
Response (200)
{ "plan": "free", "used": 847, "limit": 2500, "remaining": 1653, "breakdown": { "safe": 612, "disposable": 98, "risky": 87, "suspicious": 50 }, "resets_at": "2026-05-01T00:00:00Z" }
API Key
GET https://api.emailprobe.dev/open/v1/disposable/:domain Free open API (no auth)

Free, unauthenticated endpoint that checks if a domain is a known disposable email provider. Rate limited to 10 requests per day per IP — sign up for a free API key to get 2,500 full validations per month.

Request
# No authentication required curl https://api.emailprobe.dev/open/v1/disposable/tempmail.com
Response (200)
{ "domain": "tempmail.com", "is_disposable": true }
Domain
POST https://api.emailprobe.dev/auth/signup Create account

Creates a new account and returns the API key. A verification email is sent to the provided address.

Request Body
{ "name": "Jane Doe", "email": "[email protected]", "password": "securePassword123", "confirm_password": "securePassword123", "company_name": "Acme Inc." }
Response (201)
{ "user_id": "usr_abc123", "email": "[email protected]", "api_key": "ep_live_sk_...", "message": "Verification email sent" }
POST https://api.emailprobe.dev/auth/login Sign in

Authenticates a user and returns session information.

Request Body
{ "email": "[email protected]", "password": "securePassword123" }
Response (200)
{ "user_id": "usr_abc123", "email": "[email protected]", "role": "user", "plan": "free" }

SDKs

Official SDKs for TypeScript/JavaScript and Python. Zero dependencies, full type support.

// Install: npm install emailprobe-sdk import { EmailProbeClient } from 'emailprobe-sdk'; const client = new EmailProbeClient({ apiKey: 'ep_live_your_key', }); // Validate an email const result = await client.validate('[email protected]'); console.log(result.is_disposable); // true console.log(result.verdict); // "disposable" console.log(result.score); // 95 // Check a domain only const domain = await client.checkDomain('mailinator.com'); console.log(domain.is_disposable); // true // Free open API (no auth needed) const check = await client.isDisposable('guerrillamail.com'); console.log(check.disposable); // true // Get usage stats const usage = await client.usage(); console.log(`${usage.used}/${usage.monthly_limit} used`);

Rate Limits

Rate limits are enforced per API key. When exceeded, the API returns 429 Too Many Requests.

Plan Requests / Minute Monthly Limit Price
Free 60 2,500 $0
Starter 300 10,000 $19/mo
Growth 1,000 50,000 $49/mo
Scale 5,000 250,000 $149/mo

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with details.

Status Code Description
400 Bad Request Invalid request body or missing required fields.
401 Unauthorized Missing or invalid API key.
403 Forbidden API key does not have permission for this action.
422 Unprocessable Entity Request body is valid JSON but contains invalid values (e.g., malformed email).
429 Too Many Requests Rate limit exceeded. Retry after the time indicated in the Retry-After header.
500 Internal Server Error Unexpected server error. If persistent, contact support.
Error Response Format
{ "error": "Invalid email format", "code": "VALIDATION_ERROR", "status": 422 }