API Documentation

Complete reference for the Mailvalid Email Verification API. Verify email addresses in real-time with syntax, domain, MX, and SMTP checks.

🚀

Fast & Reliable

Average response time under 500ms

🎯

95%+ Accuracy

Provider-optimized verification

📦

Bulk Support

Up to 10,000 emails per request

Base URL 
https://mailvalid.io/api/v1

Authentication

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

Get your API key

Create a free account at mailvalid.io/register and generate an API key from your dashboard.

Step-by-Step Setup

  1. 1

    Create an account

    Sign up at mailvalid.io/register — 100 free credits included.

  2. 2

    Generate an API key

    Go to Dashboard → API Keys and click "Create New Key".

  3. 3

    Add the header to your requests

    Include X-API-Key: mv_live_your_key_here in all API requests.

Example Request 
curl -X POST https://mailvalid.io/api/v1/verify/single \
  -H "X-API-Key: mv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Quickstart

Get started verifying emails in under 2 minutes. Choose your preferred language:

cURL 
# Verify a single email
curl -X POST https://mailvalid.io/api/v1/verify/single \
  -H "X-API-Key: mv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@company.com"}'
Python 
import requests

API_KEY = "mv_live_your_key_here"

response = requests.post(
    "https://mailvalid.io/api/v1/verify/single",
    headers={"X-API-Key": API_KEY},
    json={"email": "john@company.com"}
)

result = response.json()
print(f"Valid: {result['result']['is_valid']}")
JavaScript (Node.js) 
const API_KEY = "mv_live_your_key_here";

const response = await fetch(
  "https://mailvalid.io/api/v1/verify/single",
  {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ email: "john@company.com" })
  }
);

const result = await response.json();
console.log(`Valid: ${result.result.is_valid}`);
PHP 
<?php
$apiKey = "mv_live_your_key_here";

$ch = curl_init("https://mailvalid.io/api/v1/verify/single");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: " . $apiKey,
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode(["email" => "john@company.com"])
]);

$result = json_decode(curl_exec($ch), true);
echo "Valid: " . ($result['result']['is_valid'] ? 'Yes' : 'No');
?>

Single Email Verification

Verify a single email address in real-time. Returns comprehensive verification results including syntax, domain, MX records, and SMTP checks.

POST /api/v1/verify/single

Request Body

Parameter Type Required Description
email string Required The email address to verify

Example Request

cURL 
curl -X POST https://mailvalid.io/api/v1/verify/single \
  -H "X-API-Key: mv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@company.com"}'

Example Response

JSON 
{
  "success": true,
  "credits_used": 1,
  "result": {
    "email": "john@company.com",
    "status": "valid",
    "is_valid": true,
    "syntax_valid": true,
    "domain": "company.com",
    "domain_valid": true,
    "has_mx": true,
    "mx_records": [
      {"priority": 10, "host": "mx1.company.com"}
    ],
    "smtp_checked": true,
    "smtp_response_code": 250,
    "is_disposable": false,
    "is_role_based": false,
    "is_catch_all": false,
    "verification_time_ms": 234
  }
}

Bulk Email Verification

Verify up to 10,000 emails in a single request. Jobs are processed asynchronously. You can poll for status or receive a webhook notification when complete.

POST /api/v1/verify/bulk

Request Body

Parameter Type Required Description
emails array Required Array of email addresses (max 10,000)
webhook_url string Optional URL to receive completion webhook

Submit Bulk Job

cURL 
curl -X POST https://mailvalid.io/api/v1/verify/bulk \
  -H "X-API-Key: mv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "john@company.com",
      "jane@example.org",
      "info@business.net"
    ],
    "webhook_url": "https://yourapp.com/webhooks/mailvalid"
  }'

Response (Job Created)

JSON 
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "total_emails": 3,
  "credits_reserved": 3,
  "webhook_url": "https://yourapp.com/webhooks/mailvalid"
}

Check Job Status

cURL 
curl https://mailvalid.io/api/v1/verify/bulk/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: mv_live_your_key_here"

Completed Job Response

JSON 
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "total_emails": 3,
  "processed_emails": 3,
  "valid_count": 2,
  "invalid_count": 1,
  "credits_used": 3,
  "results": [
    {
      "email": "john@company.com",
      "status": "valid",
      "is_valid": true,
      // ... full result for each email
    }
  ]
}

Webhooks

Get notified when your bulk verification jobs complete instead of polling. Provide a webhook_url when submitting a bulk job.

Verify webhook signatures

Always verify the X-Mailvalid-Signature header to ensure webhooks are from Mailvalid.

Webhook Payload

JSON 
{
  "event": "job.completed",
  "timestamp": "2026-01-30T10:30:00Z",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "total_emails": 100,
    "valid_count": 85,
    "invalid_count": 15,
    "credits_used": 100,
    "results_summary": {
      "total": 100,
      "results_url": "/api/v1/verify/bulk/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Webhook Headers

Header Description
X-Mailvalid-Signature HMAC-SHA256 signature of the payload
X-Mailvalid-Event Event type (job.completed, job.failed)
Content-Type application/json

Job Management

List, download results from, and cancel your bulk verification jobs.

GET /api/v1/verify/bulk

List Your Jobs

Get a paginated list of all your bulk verification jobs.

Parameter Type Default Description
page int 1 Page number
page_size int 20 Items per page (max 100)
status string all Filter by status
cURL 
curl "https://mailvalid.io/api/v1/verify/bulk?page=1&status=completed" \
  -H "X-API-Key: mv_live_your_key_here"
GET /api/v1/verify/bulk/{job_id}/download

Download Results

Download verification results as JSON or CSV.

cURL 
# Download as CSV
curl "https://mailvalid.io/api/v1/verify/bulk/{job_id}/download?format=csv" \
  -H "X-API-Key: mv_live_your_key_here" \
  -o results.csv

# Download as JSON
curl "https://mailvalid.io/api/v1/verify/bulk/{job_id}/download?format=json" \
  -H "X-API-Key: mv_live_your_key_here" \
  -o results.json
DELETE /api/v1/verify/bulk/{job_id}

Cancel a Job

Cancel a pending or processing job. Reserved credits will be refunded.

cURL 
curl -X DELETE https://mailvalid.io/api/v1/verify/bulk/{job_id} \
  -H "X-API-Key: mv_live_your_key_here"

HTTP Response Codes

Code Status Description
200 OK Request successful
201 Created Resource created (bulk job submitted)
400 Bad Request Invalid request format or parameters
401 Unauthorized Missing or invalid API key
402 Payment Required Insufficient credits
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Email Status Values

The status field indicates the verification result for each email.

Status is_valid Description
valid true Email is valid and deliverable
invalid_syntax false Email format is invalid
invalid_domain false Domain doesn't exist or has no MX records
mailbox_not_found false SMTP server rejected the email address
catch_all true Domain accepts all emails (risky)
disposable false Temporary/disposable email provider
role_based true Role-based email (info@, support@, etc.)
unknown false Could not determine validity

Rate Limits

API requests are rate limited to ensure fair usage and platform stability.

Limit Type Value Scope
Per API Key (minute) 60 requests Per minute
Per API Key (daily) 10,000 requests Per 24 hours
Per IP (minute) 100 requests Per minute

Rate Limit Headers

All responses include rate limit information:

Header Description
X-RateLimit-Limit Maximum requests allowed in the current window
X-RateLimit-Remaining Remaining requests in the current window
Retry-After Seconds until rate limit resets (when limited)

Error Responses

When an error occurs, the API returns a consistent error format:

Error Response Format 
{
  "detail": "Error message describing what went wrong"
}

Common Errors

Error Code Solution
Invalid API key 401 Check your API key is correct and active
Insufficient credits 402 Purchase more credits from your dashboard
Rate limit exceeded 429 Wait for the Retry-After period
Invalid email format 422 Check the email address format
Bulk job too large 400 Maximum 10,000 emails per request

Need Help?

Can't find what you're looking for? Try our interactive API docs or get in touch.

Interactive API Docs Contact Support