POST/api/v1/verify

Verify Email

Verify a single email address in real-time. Returns detailed verification results including validity status, risk score, and comprehensive checks.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API key
Content-Type	Yes	Must be application/json

Body Parameters

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

Example Request

curl -X POST https://validmail.io/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com"
  }'

Response

Response Fields

Field	Type	Description
email	string	The verified email address (normalized)
status	string	valid \| invalid \| risky \| unknown
score	number	Confidence score from 0-100
verdict	string	Human-readable result explanation
checks	object	Detailed check results (see below)
meta	object	Metadata including response time

Checks Object

Field	Type	Description
syntax.valid	boolean	Email format is valid
dns.valid	boolean	Domain has valid DNS records
dns.hasMx	boolean	Domain has MX records
smtp.valid	boolean \| null	Mailbox exists (null if unable to verify)
smtp.catchAll	boolean	Domain accepts all emails
disposable	boolean	Is a disposable/temporary email
roleBased	boolean	Is a role-based address (info@, etc.)
freeProvider	boolean	Is from a free email provider
spamTrap	boolean	Is a known spam trap

Example Response

{
  "email": "john.doe@example.com",
  "status": "valid",
  "score": 95,
  "verdict": "Email verified with high confidence",
  "checks": {
    "syntax": {
      "valid": true,
      "normalized": "john.doe@example.com"
    },
    "dns": {
      "valid": true,
      "hasMx": true,
      "mxRecords": ["mx1.example.com", "mx2.example.com"]
    },
    "smtp": {
      "valid": true,
      "catchAll": false,
      "reason": "Mailbox exists"
    },
    "disposable": false,
    "roleBased": false,
    "freeProvider": false,
    "spamTrap": false,
    "domainReputation": {
      "score": 85,
      "isBlacklisted": false
    }
  },
  "meta": {
    "responseTime": 1234
  }
}

Status Values

valid

The email address exists and can receive emails. Safe to send.

invalid

The email address does not exist or cannot receive emails. Do not send.

risky

The email may be valid but has risk factors (disposable, catch-all, etc.). Send with caution.

unknown

Could not determine validity (server timeout, greylisting, etc.). Manual review recommended.

Code Examples

JavaScript

async function verifyEmail(email) {
  const response = await fetch('https://validmail.io/api/v1/verify', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VALIDMAIL_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return response.json();
}

// Usage
const result = await verifyEmail('test@example.com');
console.log(result.status); // 'valid', 'invalid', 'risky', or 'unknown'

Python

import requests
import os

def verify_email(email):
    response = requests.post(
        'https://validmail.io/api/v1/verify',
        headers={
            'Authorization': f'Bearer {os.environ["VALIDMAIL_API_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={'email': email}
    )

    response.raise_for_status()
    return response.json()

# Usage
result = verify_email('test@example.com')
print(result['status'])  # 'valid', 'invalid', 'risky', or 'unknown'

PHP

<?php

function verifyEmail($email) {
    $ch = curl_init('https://validmail.io/api/v1/verify');

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('VALIDMAIL_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode(['email' => $email]),
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Usage
$result = verifyEmail('test@example.com');
echo $result['status']; // 'valid', 'invalid', 'risky', or 'unknown'

Error Codes

Code	Status	Description
INVALID_EMAIL	400	Email format is invalid
MISSING_EMAIL	400	Email parameter is required
INVALID_API_KEY	401	API key is invalid or revoked
INSUFFICIENT_CREDITS	403	No verification credits remaining
RATE_LIMITED	429	Too many requests