API Documentation

Email Validation API

Powerful, real-time email validation with SMTP verification, disposable email detection, and fraud analysis. Get started with our comprehensive API documentation.

Quick Start Guide

Step-by-Step Setup

1

Sign Up & Get API Key

Create your account and get your API key from the dashboard

# Get your API key from the dashboard
curl -X GET "https://extractmail.com/dashboard" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
2

Validate Your First Email

Test the API with a simple email validation

curl -X POST "https://extractmail.com/validate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
3

Check Your Response

You'll get a detailed validation result with confidence score

{
  "email": "[email protected]",
  "is_valid": true,
  "confidence_score": 95,
  "details": "Valid business email"
}

Pro Tip

Start with the free plan (5 validations/month) to test the API. Upgrade to Basic ($39/mo) for bulk validation and file uploads.

Authentication

All API requests require authentication using either JWT tokens (for web sessions) or API keys (for programmatic access). Include your token in the Authorization header.

Authentication Methods

Method 1: JWT Token (Web Sessions)

POST /auth/google

Authenticate using Google OAuth to get your JWT token for web sessions.

// Example: Using Google OAuth
const response = await fetch('/auth/google', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    credential: 'GOOGLE_ID_TOKEN'
  })
});

const data = await response.json();
// Token will be set as secure HTTP-only cookie

Method 2: API Key (Programmatic Access)

Get your API key from the dashboard and use it directly in the Authorization header.

# Using API key directly
curl -X POST "https://extractmail.com/validate" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Important

Keep your JWT tokens secure. They're automatically set as secure HTTP-only cookies for web applications, or can be used as Bearer tokens for API access.

Core Endpoints

POST /validate

Validate a single email address with comprehensive analysis.

Request Body

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

Response

{
  "email": "[email protected]",
  "is_valid": true,
  "is_disposable": false,
  "is_free_provider": false,
  "domain_info": {
    "domain": "example.com",
    "has_mx_records": true
  },
  "mx_records": ["mail.example.com"],
  "smtp_check": true,
  "possible_fraud": false,
  "details": "Valid business email",
  "confidence_score": 95
}

Complete Example

// JavaScript Example
const validateEmail = async (email) => {
  try {
    const response = await fetch('/validate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_JWT_TOKEN'
      },
      body: JSON.stringify({ email })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();
    console.log('Validation result:', result);
    
    // Check confidence score
    if (result.confidence_score >= 80) {
      console.log('High confidence - email is likely valid');
    } else if (result.confidence_score >= 50) {
      console.log('Medium confidence - proceed with caution');
    } else {
      console.log('Low confidence - likely invalid');
    }
    
    return result;
  } catch (error) {
    console.error('Validation failed:', error);
  }
};

// Usage
validateEmail('[email protected]');

Request Body

Response

{
  "results": [
    {
      "email": "[email protected]",
      "is_valid": true,
      "details": "Valid business email",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "email": "[email protected]",
      "is_valid": true,
      "details": "Valid business email",
      "timestamp": "2024-01-15T10:30:01Z"
    },
    {
      "email": "[email protected]",
      "is_valid": false,
      "details": "Disposable email detected",
      "timestamp": "2024-01-15T10:30:02Z"
    }
  ],
  "remaining_validations": 1847
}
POST /validate/bulk

Upload CSV or Excel files to validate thousands of emails at once.

// JavaScript File Upload Example
const uploadFile = async (file) => {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('format', file.name.split('.').pop()); // csv, xlsx, etc.

  const response = await fetch('/validate/bulk', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    },
    body: formData
  });

  const results = await response.json();
  
  // Results include a task_id for downloading Excel file
  if (results[0]?.task_id) {
    // Download processed file
    window.open(`/download-results/${results[0].task_id}`);
  }
  
  return results;
};

User Management

GET /user/profile

Get current user profile and plan information.

{
  "email": "[email protected]",
  "username": "user123",
  "current_plan": "Basic",
  "remaining_validations": 1850,
  "current_validations": 150,
  "api_key": "your-api-key-here"
}
GET /user/stats

Get user usage statistics and remaining quota.

{
  "remaining_validations": 1850,
  "current_validations": 150,
  "current_plan": "Basic"
}

Response Format

Field Type Description
email string The normalized email address
is_valid boolean Whether the email is valid and deliverable
is_disposable boolean Whether the email is from a disposable provider
is_free_provider boolean Whether the email is from a free provider (Gmail, Yahoo, etc.)
domain_info object Information about the email domain
mx_records array List of MX records for the domain
smtp_check boolean Whether SMTP verification passed
possible_fraud boolean Whether the email shows signs of fraud
details string Detailed validation results and explanations
confidence_score integer Confidence score from 0-100 based on all validation factors

Error Handling

The API returns standard HTTP status codes and detailed error messages.

Common Error Responses

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

Validation limit reached for your plan

429 Rate Limited

Too many requests - please slow down

Error Response Format

{
  "detail": "Not enough validations remaining. You need 10 validations but only have 5 remaining."
}

Common Error Scenarios

Invalid Email Format

When the email format is invalid:

{
  "detail": "The email address is not valid. It must have exactly one @-sign."
}

Plan Limit Exceeded

When you've reached your monthly validation limit:

{
  "detail": "Validation limit reached. Please upgrade your plan."
}

Bulk Validation Not Available

When trying to use bulk features on free plan:

{
  "detail": "Bulk email validation is not available on the free plan. Please upgrade to access this feature."
}

Rate Limits & Plans

Free Plan

  • • 5 validations/month
  • • Single email validation only
  • • Basic features included

Basic Plan - $39/mo

  • • 2,000 validations/month
  • • Bulk file upload (CSV/Excel)
  • • API access
  • • Priority support

Enterprise Plans

  • Premium: 10K validations/month - $99/mo
  • Enterprise 50K: 50K validations/month - $299/mo
  • Enterprise 100K: 100K validations/month - $499/mo
  • • Advanced reporting & dedicated support

Code Examples

Python

import requests

def validate_email(email, token):
    url = "https://extractmail.com/validate"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    data = {"email": email}
    
    response = requests.post(url, json=data, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None

# Usage
result = validate_email("[email protected]", "your_jwt_token")
if result and result['is_valid']:
    print(f"Email is valid with {result['confidence_score']}% confidence")

Node.js

const axios = require('axios');

async function validateEmail(email, token) {
    try {
        const response = await axios.post(
            'https://extractmail.com/validate',
            { email },
            {
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Content-Type': 'application/json'
                }
            }
        );
        
        return response.data;
    } catch (error) {
        console.error('Validation failed:', error.response?.data || error.message);
        return null;
    }
}

// Usage
validateEmail('[email protected]', 'your_jwt_token')
    .then(result => {
        if (result && result.is_valid) {
            console.log(`Email is valid with ${result.confidence_score}% confidence`);
        }
    });

PHP

 $email]);
    
    $options = [
        'http' => [
            'header' => "Content-type: application/json\r\n" .
                       "Authorization: Bearer $token\r\n",
            'method' => 'POST',
            'content' => $data
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    if ($result === FALSE) {
        return null;
    }
    
    return json_decode($result, true);
}

// Usage
$result = validateEmail('[email protected]', 'your_jwt_token');
if ($result && $result['is_valid']) {
    echo "Email is valid with " . $result['confidence_score'] . "% confidence";
}
?>

cURL

# Single email validation
curl -X POST "https://extractmail.com/validate" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

# File upload
curl -X POST "https://extractmail.com/validate/bulk" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "[email protected]" \
  -F "format=csv"

Support & Contact

Need Help?

Our support team is here to help you integrate and use the Email Validation API effectively.

Response Times

  • Free Plan: 24-48 hours
  • Basic Plan: 4-12 hours
  • Enterprise: 1-4 hours