Email Verification API Documentation

Single Email Verification

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

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"}'

{
  "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,
    "is_free_provider": false,
    "confidence_score": 95,
    "status_reason": "mailbox_confirmed",
    "provider": "corporate",
    "verification_time_ms": 234,
    "cached": false
  }
}

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.

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"
  }'

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

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

{
  "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.

Webhook Payload

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

Webhook Headers

Verifying the signature

Compute an HMAC-SHA256 of the raw request body using your webhook_secret and compare it to the X-Mailvalid-Signature header. Sign the bytes exactly as received — don't parse and re-serialize the JSON.

import hmac, hashlib
from flask import request, abort

WEBHOOK_SECRET = "your_webhook_secret"  # from GET /api/auth/stats

def handle_webhook():
    raw = request.get_data()  # raw bytes — do NOT use request.json
    expected = hmac.new(WEBHOOK_SECRET.encode(), raw, hashlib.sha256).hexdigest()
    sig = request.headers.get("X-Mailvalid-Signature", "")
    if not hmac.compare_digest(expected, sig):
        abort(401)  # signature mismatch — reject
    event = request.json
    # ... trust event and process ...
    return "", 200

Bounce Webhook

Feed delivery and bounce data back to MailValid to improve verification accuracy over time. This is especially valuable for providers that block SMTP verification (Microsoft, Apple) where we can't confirm mailboxes directly.

{
  "events": [
    {
      "email": "user@example.com",
      "event_type": "hard_bounce",
      "bounce_code": "550",
      "bounce_message": "User unknown",
      "timestamp": "2026-03-14T10:30:00Z"
    },
    {
      "email": "valid@example.com",
      "event_type": "delivered"
    }
  ]
}

curl -X POST https://mailvalid.io/api/v1/webhooks/bounce \
  -H "X-API-Key: mv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"email": "bounced@example.com", "event_type": "hard_bounce", "bounce_code": "550"},
      {"email": "good@example.com", "event_type": "delivered"}
    ]
  }'

{
  "success": true,
  "processed": 2,
  "errors": 0,
  "message": "Processed 2/2 events"
}

Job Management

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

curl "https://mailvalid.io/api/v1/verify/bulk?page=1&status=completed" \
  -H "X-API-Key: mv_live_your_key_here"

# 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

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

MCP Server (Model Context Protocol)

Connect AI agents and assistants — Claude, Cursor, and any MCP-compatible client — directly to MailValid. The MCP server is a hosted remote endpoint over the Streamable HTTP transport. Its tools run through the same verification engine and credit system as the REST API, so billing is identical.

Two tools — verify_email_demo and get_api_discovery — work without a key. Every other tool requires the X-API-Key header and bills your account.

Option 1 — the @mailvalid/mcp launcher (easiest, works in any client)

Works everywhere, including stdio-only clients like Claude Desktop. Add this to your client's MCP config — it reads your key from MAILVALID_API_KEY and bridges to this server, so there's no URL or header to manage:

{
  "mcpServers": {
    "mailvalid": {
      "command": "npx",
      "args": ["-y", "@mailvalid/mcp"],
      "env": { "MAILVALID_API_KEY": "mv_live_your_key_here" }
    }
  }
}

Option 2 — connect directly over HTTP (Claude Code, Cursor, …)

Clients with native remote-MCP support can point straight at the endpoint. With Claude Code:

claude mcp add --transport http mailvalid https://mailvalid.io/mcp/ \
  --header "X-API-Key: mv_live_your_key_here"

Or with an mcp.json config:

{
  "mcpServers": {
    "mailvalid": {
      "url": "https://mailvalid.io/mcp/",
      "headers": { "X-API-Key": "mv_live_your_key_here" }
    }
  }
}

Field names vary slightly between clients (some use servers instead of mcpServers) — check your client's MCP docs.

Available tools

* verify_email is free for unknown results and recent cached repeats. Discovery documents live at /.well-known/mcp.json and /.well-known/mcp/server-card.json. Tip: include the trailing slash (/mcp/) to avoid an HTTP redirect.

HTTP Response Codes

Email Status Values

Industry-standard status codes (same as ZeroBounce, NeverBounce). The status field indicates the verification result. The status_reason field gives the specific machine-readable reason.

Status Codes

Sub-Status Reasons

The status_reason field gives the specific reason behind the status:

Confidence Score

Every result includes a confidence_score (0–100) indicating how confident we are in the result:

Rate Limits

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

Limits are per API key. Verification requests covers writes (POST /verify/single, POST /verify/bulk); read requests covers polling endpoints (GET /verify/bulk/{id}, GET /credits), so status polling never eats into your verification budget. The keyless demo endpoint (POST /api/demo/verify) is limited to 30 requests per minute per IP.

When rate limited, the API returns 429 Too Many Requests. Back off and retry after the time specified in the Retry-After header.

Need higher limits? Contact us at [email protected] for custom rate limits on higher volume plans.

Rate Limit Headers

All responses include rate limit information:

Error Responses

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

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

Common Errors