VerifyMail API

Introduction

VerifyMail identifies throwaway, disposable, catch-all, and abusive email addresses at signup. Instead of a boolean “valid/invalid” flag, every call to /v1/check returns a 5-block response — meta, verdict, score, signals, and checks — so you can make nuanced policy decisions from a single request.

The entire API is intentionally small. One endpoint handles 99% of traffic. Supporting endpoints let you report false positives, monitor usage, and subscribe to async webhooks.

Quickstart

Install the SDK for your language and make your first check in under 60 seconds.

1. Install

# Node
npm install verifymail

# Python
pip install verifymail

2. Make your first check

from verifymail import VerifyMail

client = VerifyMail(api_key="vm_live_...")
result = client.check("user@mailinator.com")

print(result.verdict.recommendation)  # -> "block"
print(result.score.value)             # -> 100
print(result.score.confidence)        # -> 1.0

3. Switch on the recommendation

switch (result.verdict.recommendation) {
  case 'block':           throw new Error(result.verdict.summary);
  case 'verify_manually': queueForReview(email, result); break;
  case 'allow_with_flag': logSuspicious(email, result.signals.fired); break;
  case 'allow':           break;
}

Authentication

Every request requires an API key, sent as the X-API-Key header. Keys are environment-scoped: vm_live_* for production, vm_test_* for staging and tests.

export VERIFYMAIL_KEY="vm_live_..."

curl -H "X-API-Key: $VERIFYMAIL_KEY" \
  https://api.verifymailapi.com/v1/check?email=test@example.com

Rotate keys freely from the dashboard — previous keys remain valid for 24 hours to give you a grace window.

Rate limits

Default limit is 100 requests / second per API key, bursting to 500 with token-bucket smoothing. Requests over the limit return 429 with a Retry-After header. For higher volume, contact support.

POST /v1/check

The single core endpoint. Accepts an email, returns a full 5-block scored response.

Request

POST https://api.verifymailapi.com/v1/check
X-API-Key: vm_live_...
X-Risk-Profile: balanced   # optional — strict | balanced | permissive
Content-Type: application/json

{ "email": "user@myagency-solutions.com" }

Response — catch-all fraud example

{
  "meta": {
    "request_id": "req_8d4b3e2f1a6c",
    "email": "user@myagency-solutions.com",
    "domain": "myagency-solutions.com",
    "checked_at": "2026-04-21T10:24:12.391Z",
    "latency_ms": 94,
    "api_version": "2026-04",
    "path_taken": "standard",
    "cached": false
  },
  "verdict": {
    "recommendation": "block",
    "risk_level": "critical",
    "disposable": false,
    "catch_all": true,
    "safe_to_send": false,
    "summary": "Domain is 14 days old, configured as catch-all, and matches known fraud infrastructure."
  },
  "score": {
    "value": 94,
    "confidence": 0.91,
    "confidence_level": "high",
    "thresholds": {
      "block_at": 70,
      "flag_at": 45,
      "your_profile": "balanced"
    },
    "catch_all_detail": {
      "detected": true,
      "probability": 0.97,
      "confidence": 0.94,
      "type": "confirmed"
    }
  },
  "signals": {
    "fired": [
      { "name": "catch_all_confirmed",  "direction": "risk", "weight": 55 },
      { "name": "domain_age_14_days",   "direction": "risk", "weight": 42 },
      { "name": "mx_shared_with_9_domains", "direction": "risk", "weight": 35 }
    ]
  }
}

POST /v1/report

Report a false positive or false negative to tune VerifyMail against your workload. Reports feed the network-effect model and are shared (de-identified) across customers.

POST /v1/report
{ "request_id": "req_8d4b3e2f1a6c",
  "correct_verdict": "allow",
  "notes": "Customer converted and paid." }

GET /v1/usage

Returns your current-period usage, credit balance, and next billing window. Useful for dashboards and budget guards.

The 5-block structure

Every response has the same top-level shape. Each block has a single purpose:

The 4 recommendation values

The verdict.recommendation field is always one of exactly four strings — switch on it directly without parsing thresholds.

Risk profiles

Three built-in profiles control the block/flag thresholds applied to the raw 0–100 score. Send X-Risk-Profile: strict | balanced | permissive per request, or set an account default.

Catch-all detection

Catch-all domains accept mail for any address, which defeats naive SMTP probes. VerifyMail combines four evidence sources into a single Bayesian probability:

1. SMTP probe result — response to a random-UUID recipient.
2. Infrastructure signals — MX configuration, WHOIS age, ASN reputation.
3. Behavioral history — delivery/bounce patterns from past traffic.
4. Cross-customer network data — correlation with confirmed fraud on shared infrastructure.

Worked example A — fraud catch-all

Domain registered 14 days ago, MX shared with 9 other domains (7 confirmed disposable), SMTP accepts UUID addresses:

catch_all.probability       =  0.97
catch_all.confidence        =  0.94
catch_all.type              =  "confirmed"
verdict.recommendation      =  "block"

Worked example B — legitimate catch-all

Domain registered 6 years ago, SPF/DMARC aligned, healthy delivery history, SMTP accepts UUID addresses:

catch_all.probability            =  0.88
catch_all.legitimate_use_likely  =  true
catch_all.type                   =  "legitimate"
verdict.recommendation           =  "allow_with_flag"

Signals reference

A representative slice of what VerifyMail evaluates, with balanced-profile weights. Risk signals add to the score, trust signals subtract.

Above: 22 representative signals. The full reference includes 80+ signals across all categories.

SDKs

Official clients for four languages, with full types for every response field.

Python

Install via pip install verifymail. The client is sync by default; import AsyncVerifyMail for asyncio support.

Node.js

Install via npm install verifymail. Ships with full TypeScript types for every field in the response.

PHP

Install via composer require verifymail/verifymail. PHP 8.1+; uses readonly properties for the response object.

Go

Install via go get github.com/verifymail/verifymail-go. Context-aware, zero external dependencies beyond the stdlib.

Webhooks

Deep checks run async when latency budget would exceed 300ms. Subscribe to check.completed events to receive the full response when the background job finishes. Preliminary response is returned synchronously.

Errors

All errors return a consistent shape:

{
  "error": {
    "code": "invalid_email",
    "message": "Email failed syntax validation.",
    "request_id": "req_..."
  }
}