API Documentation

Everything you need to integrate email verification into your application.

Overview

The verify-email.net API lets you verify email addresses in real-time. Each verification runs syntax validation, MX record lookup, SMTP mailbox check, catch-all detection, disposable domain detection, and role-based address detection.

Base URL:

https://verify-email.net

All API responses are JSON. Dates are ISO 8601 strings (UTC).

Authentication

Authenticated endpoints accept two methods:

API Key (recommended for server-side)

# Pass as X-API-Key header curl -H "X-API-Key: ve_live_abc123..." \ https://verify-email.net/api/[email protected]

Bearer Token (for browser/dashboard)

# Pass as Authorization header curl -H "Authorization: Bearer eyJhbG..." \ https://verify-email.net/api/[email protected]

Create API keys in your dashboard. Keys start with ve_live_ and are shown once at creation. Store them securely.

Important: Never expose API keys in client-side code. Use them only from your backend server.

Rate Limits

Tier	Limit	Scope
Free demo	3 verifications / day	Per IP address
Pro (API)	100 requests / minute	Per account
Bulk jobs	10,000 emails / job, 3 concurrent jobs	Per account

When rate limited, the API returns 429 Too Many Requests.

Errors

Errors return a JSON object with an error field:

{
  "error": "Invalid API key"
}

Status	Meaning
400	Bad request (missing or invalid parameters)
401	Authentication required or invalid credentials
403	Paid subscription required
404	Resource not found
409	Conflict (e.g. email already registered)
429	Rate limit exceeded
500	Server error

Demo Verify

Free verification for trying the service. Limited to 3 per day per IP address. No authentication required.

GET /api/demo/verify?email={email}

Parameter	Type	Description
`email`	string	Email address to verify REQUIRED

Example:

curl "https://verify-email.net/api/demo/[email protected]"

Response:

{
  "email": "[email protected]",
  "score": 10,
  "verdict": "undeliverable",
  "checks": {
    "syntax": { "valid": true },
    "disposable": { "is_disposable": false },
    "role_based": { "is_role": false },
    "mx": { "has_mx": true, "records": [...] },
    "smtp": { "connectable": true, "code": 550 },
    "catch_all": { "is_catch_all": false }
  },
  "duration": 2847,
  "remaining": 2
}

Single Verify

Verify a single email address. Requires authentication and a paid subscription.

GET /api/verify?email={email}

Parameter	Type	Description
`email`	string	Email address to verify REQUIRED

Headers:

X-API-Key: ve_live_abc123...
# or
Authorization: Bearer eyJhbG...

Example:

curl -H "X-API-Key: ve_live_abc123..." \ "https://verify-email.net/api/[email protected]"

Response:

{
  "id": "a1b2c3d4-...",
  "email": "[email protected]",
  "score": 95,
  "verdict": "deliverable",
  "checks": {
    "syntax": { "valid": true },
    "disposable": { "is_disposable": false },
    "role_based": { "is_role": false },
    "mx": { "has_mx": true, "records": ["10 mx1.company.com"] },
    "smtp": { "connectable": true, "code": 250, "message": "OK" },
    "catch_all": { "is_catch_all": false }
  },
  "duration": 3102
}

Each successful verification is counted toward your monthly usage and billed at $0.003.

Bulk Verify

Submit up to 10,000 emails for background verification. Results are processed asynchronously.

POST /api/verify/bulk

Request body (JSON array):

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

Or CSV text:

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

Example:

curl -X POST \ -H "X-API-Key: ve_live_abc123..." \ -H "Content-Type: application/json" \ -d '{"emails":["[email protected]","[email protected]"]}' \ https://verify-email.net/api/verify/bulk

Response:

{
  "id": "b5c6d7e8-...",
  "status": "processing",
  "total": 2,
  "message": "Bulk verification started. Poll GET /api/verify/bulk/b5c6d7e8-... for progress."
}

Bulk Job Status

Check the progress of a bulk verification job. Once completed, results are included in the response.

GET /api/verify/bulk/{id}

Response (in progress):

{
  "id": "b5c6d7e8-...",
  "status": "processing",
  "total": 500,
  "processed": 147,
  "deliverable": 102,
  "undeliverable": 38,
  "other": 7,
  "createdAt": "2026-02-08T12:00:00.000Z",
  "completedAt": null
}

Response (completed): includes results array with all individual verification results.

Download Results (CSV)

GET /api/verify/bulk/{id}/download

Returns a CSV file with columns: email, score, verdict, status.

curl -H "X-API-Key: ve_live_abc123..." \
  "https://verify-email.net/api/verify/bulk/b5c6d7e8-.../download" \
  -o results.csv

API Keys

GET /api/keys

List all API keys for the authenticated user.

{
  "keys": [
    {
      "id": "key-uuid",
      "name": "Production",
      "prefix": "ve_live_abc12345...",
      "createdAt": "2026-02-08T12:00:00.000Z",
      "lastUsedAt": "2026-02-08T15:30:00.000Z",
      "active": true
    }
  ]
}

POST /api/keys

Create a new API key. Requires paid subscription.

Body Parameter	Type	Description
`name`	string	Display name for the key (optional, defaults to "Default")

// Response — save the key, it won't be shown again
{
  "id": "key-uuid",
  "key": "ve_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
  "name": "Production",
  "message": "Save this key now. It will not be shown again."
}

DELETE /api/keys/{id}

Revoke an API key. It will immediately stop working.

Usage

GET /api/usage

Current month usage with daily breakdown.

{
  "month": "2026-02",
  "total": 1234,
  "daily": [
    { "date": "2026-02-01", "count": 156 },
    { "date": "2026-02-02", "count": 203 }
  ]
}

GET /api/usage/history

Monthly usage history (up to 24 months).

{
  "history": [
    { "month": "2026-01", "count": 4521 },
    { "month": "2026-02", "count": 1234 }
  ]
}

Billing

Billing is managed through Stripe. The Pro plan costs $3/month base fee plus $0.003 per verification.

GET /api/billing/status

Get current billing status and estimated cost.

{
  "tier": "pro",
  "stripe": { "status": "active" },
  "usage": {
    "month": "2026-02",
    "count": 1234,
    "cost": "$6.70"
  }
}

POST /api/billing/checkout

Create a Stripe Checkout session to subscribe. Returns a URL to redirect the user to.

{
  "url": "https://checkout.stripe.com/c/pay/..."
}

POST /api/billing/portal

Create a Stripe Billing Portal session to manage subscription, update payment method, or cancel. Returns a URL.

Verdicts & Scores

Each verification returns a score (0–100) and a verdict:

Verdict	Score Range	Meaning
deliverable	80–100	Email address exists and can receive mail
risky	40–79	Email may exist but has risk factors (catch-all, disposable, etc.)
undeliverable	0–39	Email does not exist or cannot receive mail
unknown	40–60	Could not determine deliverability (timeout, greylisting)

Score Modifiers

Factor	Effect
SMTP 250 response	Base score 95
SMTP 550 rejection	Base score 10
SMTP timeout / error	Base score 50
No MX records	Score 0
Catch-all domain	Capped at 70
Disposable domain	-40 penalty
Role-based address	-10 penalty

Check Types

Check	Field	Description
Syntax	`checks.syntax`	Validates email format (RFC 5321), length limits, allowed characters
Disposable	`checks.disposable`	Checks against 1,190+ known temporary/throwaway email domains
Role-based	`checks.role_based`	Detects generic addresses like admin@, info@, support@, noreply@
MX Records	`checks.mx`	Looks up DNS MX records to verify the domain can receive email
SMTP	`checks.smtp`	Connects to the mail server and tests if the mailbox accepts mail (RCPT TO)
Catch-all	`checks.catch_all`	Probes with a random address to detect domains that accept all mail

Note: MX record lookups are cached for 1 hour per domain. When verifying multiple emails at the same domain, subsequent lookups are instant.