Quick Start

Get started with ValidMail email verification in under 5 minutes. This guide will walk you through making your first API call.

Prerequisites

• A ValidMail account (sign up free)
• An API key from your dashboard

After signing up, navigate to your dashboard and go to the API Keys section. Click "Create New Key" to generate your API key.

Use the verify endpoint to validate an email address. Here are examples in different languages:

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

const response = await fetch('https://validmail.io/api/v1/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'test@example.com' }),
});

const result = await response.json();
console.log(result);

import requests

response = requests.post(
    'https://validmail.io/api/v1/verify',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={'email': 'test@example.com'}
)

result = response.json()
print(result)

The API returns a JSON response with the verification result:

{
  "email": "test@example.com",
  "status": "valid",
  "score": 95,
  "verdict": "Email verified with high confidence",
  "checks": {
    "syntax": { "valid": true },
    "dns": { "valid": true, "hasMx": true },
    "smtp": { "valid": true, "catchAll": false },
    "disposable": false,
    "roleBased": false,
    "freeProvider": true
  },
  "meta": {
    "responseTime": 1234
  }
}

Here's an example of how to use the verification result in your application:

async function validateEmail(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 }),
  });

  const result = await response.json();

  // Handle based on status
  switch (result.status) {
    case 'valid':
      // Safe to send - proceed with signup/email
      return { valid: true, message: 'Email verified' };

    case 'invalid':
      // Block - email doesn't exist
      return { valid: false, message: 'Please enter a valid email' };

    case 'risky':
      // Warning - may want to ask for confirmation
      if (result.checks.disposable) {
        return { valid: false, message: 'Disposable emails not allowed' };
      }
      return { valid: true, warning: result.verdict };

    default:
      // Unknown - let through but flag for review
      return { valid: true, warning: 'Could not fully verify' };
  }
}