Email Validation API Documentation

Introduction

EmailCheck.dev provides a fast, accurate email validation API. Our service checks email syntax, MX records, disposable email providers, role-based accounts, and detects common typos.

🚀 Quick Facts

Sub-400ms response time • 99.9% uptime • Generous rate limits on all plans

Base URL

https://api.emailcheck.dev

What Gets Checked

Syntax Validation - RFC 5322 compliant email format
MX Records - Domain has mail servers configured
Disposable Detection - Temporary/throwaway email services
Role-Based Detection - Generic addresses (admin@, info@, support@)
Free Provider Detection - Gmail, Yahoo, Outlook, etc.
Typo Detection - Common misspellings (gmial.com → gmail.com)

Authentication

All API requests require an API key. Include your API key in the X-API-Key header.

Authentication Header

X-API-Key: your_api_key_here

🔑 Get Your API Key

Sign up for free at emailcheck.dev/signup to get your API key instantly.

API Key Format

API keys follow this format: mc_live_[40_characters]

⚠️ Keep Your API Key Secret

Never expose your API key in client-side code, public repositories, or anywhere users can see it.

Quick Start

Get started in less than 2 minutes. Here's your first API call:

Quick Start

curl -X POST https://api.emailcheck.dev/v1/validate \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

You'll get back:

Response 200 OK

{
  "email": "[email protected]",
  "normalizedEmail": "[email protected]",
  "suggestedEmail": null,
  "valid": true,
  "confidenceScore": 95,
  "deliverabilityLikelihood": "high",
  "syntaxValid": true,
  "mxRecordsFound": true,
  "disposable": false,
  "roleBased": false,
  "freeProvider": false,
  "provider": "example",
  "catchAll": false,
  "warnings": []
}

Validate Email Endpoint

Endpoint

POST /v1/validate

Request Parameters

Parameter	Type	Required	Description
`email`	string	✅ Yes	The email address to validate

Request Example

curl -X POST https://api.emailcheck.dev/v1/validate \
  -H "X-API-Key: mc_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

{
  "email": "[email protected]"
}

Response Format

Success Response 200 OK

Field	Type	Description
`email`	string	The email address that was validated
`normalizedEmail`	string	Cleaned/standardized version of email
`suggestedEmail`	string\|null	Corrected email if typo detected (e.g., gmial → gmail)
`valid`	boolean	Overall validity - true if email can receive messages
`confidenceScore`	integer	Confidence level (0-100) that email is deliverable
`deliverabilityLikelihood`	string	Rating: "high", "medium", "low", or "unknown"
`syntaxValid`	boolean	Email format is correct (RFC 5322)
`mxRecordsFound`	boolean	Domain has mail server records
`disposable`	boolean	Temporary/throwaway email service
`roleBased`	boolean	Generic address (info@, admin@, support@)
`freeProvider`	boolean	Free email provider (Gmail, Yahoo, etc.)
`provider`	string	Email provider name (gmail, outlook, custom)
`catchAll`	boolean	Domain accepts mail for any address
`warnings`	array	List of warnings or issues detected

Example Responses

Valid Email:

{
  "email": "[email protected]",
  "normalizedEmail": "[email protected]",
  "suggestedEmail": null,
  "valid": true,
  "confidenceScore": 95,
  "deliverabilityLikelihood": "high",
  "syntaxValid": true,
  "mxRecordsFound": true,
  "disposable": false,
  "roleBased": false,
  "freeProvider": true,
  "provider": "gmail",
  "catchAll": false,
  "warnings": []
}

Invalid Email with Typo:

{
  "email": "[email protected]",
  "normalizedEmail": "[email protected]",
  "suggestedEmail": "[email protected]",
  "valid": false,
  "confidenceScore": 20,
  "deliverabilityLikelihood": "low",
  "syntaxValid": true,
  "mxRecordsFound": false,
  "disposable": false,
  "roleBased": false,
  "freeProvider": false,
  "provider": "unknown",
  "catchAll": false,
  "warnings": ["Possible typo detected", "No MX records found"]
}

Disposable Email:

{
  "email": "[email protected]",
  "normalizedEmail": "[email protected]",
  "suggestedEmail": null,
  "valid": false,
  "confidenceScore": 5,
  "deliverabilityLikelihood": "low",
  "syntaxValid": true,
  "mxRecordsFound": true,
  "disposable": true,
  "roleBased": false,
  "freeProvider": false,
  "provider": "tempmail",
  "catchAll": false,
  "warnings": ["Disposable email address"]
}

Error Responses

The API uses standard HTTP status codes and returns JSON error responses.

400 Bad Request 400

Missing or invalid request parameters.

{
  "error": "Invalid request",
  "message": "Email parameter is required"
}

401 Unauthorized 401

Invalid or missing API key.

{
  "error": "Invalid or missing API key",
  "message": "Please provide a valid API key in X-API-Key header"
}

429 Too Many Requests 429

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit",
  "retry_after": 60
}

500 Internal Server Error 500

Unexpected server error.

{
  "error": "Internal server error",
  "message": "An unexpected error occurred. Please try again later"
}

Batch Validate Emails

Validate multiple emails in a single request. Maximum 100 emails per batch.

Endpoint

POST

POST /v1/validate/batch

Request Body

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

Example Request

cURL

curl -X POST https://api.emailcheck.dev/v1/validate/batch \
  -H "X-API-Key: mc_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ]
  }'

Success Response 200 OK

{
  "results": [
    {
      "email": "[email protected]",
      "normalizedEmail": "[email protected]",
      "suggestedEmail": null,
      "valid": true,
      "confidenceScore": 95,
      "deliverabilityLikelihood": "high",
      "syntaxValid": true,
      "mxRecordsFound": true,
      "disposable": false,
      "roleBased": false,
      "freeProvider": false,
      "provider": "custom",
      "catchAll": false,
      "warnings": []
    },
    {
      "email": "[email protected]",
      "normalizedEmail": "[email protected]",
      "suggestedEmail": null,
      "valid": true,
      "confidenceScore": 95,
      "deliverabilityLikelihood": "high",
      "syntaxValid": true,
      "mxRecordsFound": true,
      "disposable": false,
      "roleBased": false,
      "freeProvider": false,
      "provider": "custom",
      "catchAll": false,
      "warnings": []
    },
    {
      "email": "[email protected]",
      "normalizedEmail": "[email protected]",
      "suggestedEmail": "[email protected]",
      "valid": false,
      "confidenceScore": 20,
      "deliverabilityLikelihood": "low",
      "syntaxValid": true,
      "mxRecordsFound": false,
      "disposable": false,
      "roleBased": false,
      "freeProvider": false,
      "provider": "unknown",
      "catchAll": false,
      "warnings": ["Possible typo detected", "No MX records found"]
    }
  ],
  "total": 3,
  "valid_count": 2,
  "invalid_count": 1
}

⚠️ Batch Limits

Maximum 100 emails per batch request. Each email in the batch counts toward your monthly limit.

Error Codes

Code	Description
`400`	Bad Request - Invalid email format or missing parameters
`401`	Unauthorized - Invalid or missing API key
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end
`503`	Service Unavailable - Temporary maintenance

Error Response Format

Error Response 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "status": 401
}

Code Examples

cURL

curl -X POST https://api.emailcheck.dev/v1/validate \
  -H "X-API-Key: mc_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Node.js

const response = await fetch('https://api.emailcheck.dev/v1/validate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'mc_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]'
  })
});

const data = await response.json();
console.log(data);

const axios = require('axios');

const response = await axios.post('https://api.emailcheck.dev/v1/validate', {
  email: '[email protected]'
}, {
  headers: {
    'X-API-Key': 'mc_live_your_api_key_here'
  }
});

console.log(response.data);

Python

import requests

url = 'https://api.emailcheck.dev/v1/validate'
headers = {
    'X-API-Key': 'mc_live_your_api_key_here',
    'Content-Type': 'application/json'
}
payload = {
    'email': '[email protected]'
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

import urllib.request
import json

url = 'https://api.emailcheck.dev/v1/validate'
headers = {
    'X-API-Key': 'mc_live_your_api_key_here',
    'Content-Type': 'application/json'
}
payload = json.dumps({'email': '[email protected]'}).encode('utf-8')

req = urllib.request.Request(url, data=payload, headers=headers)
response = urllib.request.urlopen(req)
data = json.loads(response.read().decode('utf-8'))
print(data)

PHP


$ch = curl_init('https://api.emailcheck.dev/v1/validate');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: mc_live_your_api_key_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'email' => '[email protected]'
]));

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

print_r($data);
?>

post('https://api.emailcheck.dev/v1/validate', [
    'headers' => [
        'X-API-Key' => 'mc_live_your_api_key_here',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'email' => '[email protected]'
    ]
]);

$data = json_decode($response->getBody(), true);
print_r($data);
?>

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.emailcheck.dev/v1/validate')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['X-API-Key'] = 'mc_live_your_api_key_here'
request['Content-Type'] = 'application/json'
request.body = { email: '[email protected]' }.to_json

response = http.request(request)
data = JSON.parse(response.body)
puts data

Rate Limits

Plan	Monthly Limit	Rate Limit
Free	100 validations/month	10 requests/minute
Starter	5,000 validations/month	100 requests/minute
Pro	50,000 validations/month	300 requests/minute
Growth	150,000 validations/month	600 requests/minute
Business	500,000 validations/month	1,000 requests/minute

ℹ️ Rate Limit Headers

Every response includes headers showing your current rate limit status:

X-RateLimit-Limit - Your requests per minute limit
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - When the limit resets (Unix timestamp)

Best Practices

1. Validate on Signup

Check emails during user registration to prevent fake accounts and improve deliverability.

2. Handle Suggestions

When suggestedEmail is present, show it to users to help them correct typos.

if (data.suggestedEmail && data.suggestedEmail !== data.email) {
  alert(`Did you mean: ${data.suggestedEmail}?`);
}

3. Use Confidence Scores

Don't just check valid - use the confidence score for better decisions:

90-100: High confidence - accept
60-89: Medium - consider accepting with warning
0-59: Low - reject or flag for review

4. Check Disposable Emails

Block disposable emails if you need real user contact information.

if (data.disposable) {
  return "Please use a permanent email address";
}

5. Handle Rate Limits

Implement exponential backoff if you hit rate limits:

async function validateWithRetry(email, retries = 3) {
  try {
    return await validateEmail(email);
  } catch (error) {
    if (error.status === 429 && retries > 0) {
      await new Promise(r => setTimeout(r, 1000 * (4 - retries)));
      return validateWithRetry(email, retries - 1);
    }
    throw error;
  }
}

6. Cache Results

Cache validation results to reduce API calls for frequently checked emails.

7. Monitor Usage

Check your dashboard regularly to monitor usage and avoid hitting limits.

Support

Need Help?

We're here to help you get the most out of EmailCheck.dev.

📧 Email Support

For technical questions, bug reports, or feature requests:

support@emailcheck.dev

Average response time: 24 hours

Common Questions

How do I get my API key?

Sign up for a free account at emailcheck.dev/signup and your API key will be generated immediately. You'll find it in your dashboard.

What happens if I exceed my rate limit?

You'll receive a 429 (Too Many Requests) response. The response includes a Retry-After header indicating when you can retry. Implement exponential backoff to handle this gracefully.

Can I upgrade or downgrade my plan?

Yes! You can change your plan anytime from your dashboard. Upgrades take effect immediately. Downgrades take effect at the start of your next billing cycle.

Do you offer refunds?

We offer a 14-day money-back guarantee on all paid plans. Contact support for assistance.

Is there a free trial?

Yes! Every account includes 100 free email validations per month, forever. No credit card required to start.

Status & Uptime

Our API maintains 99.9% uptime. For any service issues or maintenance updates, check our homepage or contact support.

Report a Bug

Found a bug? We want to know! Please email support@emailcheck.dev with:

Description of the issue
Steps to reproduce
Expected vs actual behavior
Your API key (if relevant)

Feature Requests

Have an idea for a new feature? We'd love to hear it! Email us at support@emailcheck.dev with your suggestion.

💡 Tip

Join our beta program to get early access to new features and help shape the future of EmailCheck.dev!