Email Verification API: Complete Developer Guide

Published Feb 10, 2024 • 12 min read

Building an app that sends emails? An email verification API can save you from bounces, complaints, and blacklists. This guide covers everything: authentication, endpoints, code examples, best practices.

What is an Email Verification API?

An email verification API is a REST API that checks if an email address is valid and deliverable before you send to it. It performs real-time checks including:

• Syntax validation (RFC 5322 compliance) - see our email regex patterns guide
• Domain verification (MX records exist)
• SMTP handshake (mailbox actually exists)
• Risk detection (disposable, role-based, catch-all) - learn about disposable email detection

Why Use an API vs Manual Validation?

Quick Start (5 Minutes)

1. Get Your API Key

Sign up at Emails Wipes and generate an API key from your dashboard.

2. Make Your First Request

Endpoint: POST https://emails-wipes.com/api/v1/verify

cURL Example

curl -X POST https://emails-wipes.com/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

{
  "email": "[email protected]",
  "status": "valid",
  "deliverable": true,
  "disposable": false,
  "role_based": false,
  "catch_all": false,
  "free_provider": true,
  "domain": "example.com",
  "mx_records": ["mail.example.com"],
  "smtp_valid": true,
  "processing_time_ms": 243
}

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_abc123def456...

Security Tips:

• Never expose API keys in client-side code (JavaScript)
• Use environment variables: process.env.EMAIL_API_KEY
• Rotate keys quarterly
• Monitor usage for anomalies

Available Endpoints

1. Single Email Verification

POST /api/v1/verify

Request Body:

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

Response Fields:

• status: valid | invalid | risky | unknown
• deliverable: Can this email receive mail? (learn about validation accuracy)
• disposable: Temp email service (e.g., 10minutemail)
• role_based: Generic address (info@, support@)
• catch_all: Domain accepts all addresses (see catch-all detection)
• smtp_valid: Mailbox exists (SMTP check)

2. Bulk Verification

POST /api/v1/verify/bulk

Verify up to 1,000 emails in one request.

Request Body:

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

Response:

{
  "results": [
    { "email": "[email protected]", "status": "valid", ... },
    { "email": "[email protected]", "status": "invalid", ... },
    { "email": "[email protected]", "status": "risky", ... }
  ],
  "summary": {
    "total": 3,
    "valid": 1,
    "invalid": 1,
    "risky": 1
  }
}

3. Usage Statistics

GET /api/v1/usage

Check your monthly API usage and quota.

{
  "period": "2024-02",
  "verifications_used": 4523,
  "quota": 10000,
  "remaining": 5477,
  "reset_date": "2024-03-01"
}

Code Examples

Python

import requests

API_KEY = "sk_live_your_key_here"
API_URL = "https://emails-wipes.com/api/v1/verify"

def verify_email(email):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    response = requests.post(API_URL, json={"email": email}, headers=headers)
    return response.json()

# Example usage
result = verify_email("[email protected]")
if result["deliverable"]:
    print(f"✅ {result['email']} is valid")
else:
    print(f"❌ {result['email']} is invalid")

Node.js

const axios = require('axios');

const API_KEY = 'sk_live_your_key_here';
const API_URL = 'https://emails-wipes.com/api/v1/verify';

async function verifyEmail(email) {
  const response = await axios.post(API_URL, 
    { email },
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );
  return response.data;
}

// Example usage
verifyEmail('[email protected]')
  .then(result => {
    if (result.deliverable) {
      console.log(`✅ ${result.email} is valid`);
    } else {
      console.log(`❌ ${result.email} is invalid`);
    }
  });

PHP

<?php
$api_key = 'sk_live_your_key_here';
$api_url = 'https://emails-wipes.com/api/v1/verify';

function verify_email($email, $api_key, $api_url) {
    $ch = curl_init($api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['email' => $email]));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $api_key,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

$result = verify_email('[email protected]', $api_key, $api_url);
if ($result['deliverable']) {
    echo "✅ {$result['email']} is valid\n";
} else {
    echo "❌ {$result['email']} is invalid\n";
}
?>

Rate Limits

HTTP 429 Response (Rate Limit Exceeded):

{
  "error": "rate_limit_exceeded",
  "message": "You've exceeded 60 requests/min. Upgrade your plan.",
  "retry_after": 45
}

Error Handling

Common Error Codes

Error Handling Example (Python)

import requests
import time

def verify_with_retry(email, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(API_URL, json={"email": email}, headers=headers)

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Retrying after {retry_after}s...")
                time.sleep(retry_after)
            elif response.status_code >= 500:
                print(f"Server error. Retrying ({attempt+1}/{max_retries})...")
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                return {"error": response.json()}
        except Exception as e:
            print(f"Request failed: {e}")

    return {"error": "Max retries exceeded"}

Best Practices

1. Validate at Collection Point

Verify emails when users sign up, not before sending campaigns. This prevents bad data from entering your database.

2. Use Bulk Endpoints for Large Lists

Verifying 10,000 emails? Use /verify/bulk instead of 10,000 individual requests:

• Faster: 1 bulk request vs 10,000 singles
• Cheaper: Same credit cost, less network overhead
• Simpler: One response to parse

3. Cache Results

Email validity doesn't change often. Cache results for 30-90 days:

import redis
cache = redis.Redis()

def verify_cached(email):
    cached = cache.get(f"email:{email}")
    if cached:
        return json.loads(cached)

    result = verify_email(email)
    cache.setex(f"email:{email}", 2592000, json.dumps(result))  # 30 days
    return result

4. Handle Timeouts

SMTP checks can take 1-5 seconds. Set request timeouts to 10 seconds:

response = requests.post(API_URL, json={"email": email}, headers=headers, timeout=10)

5. Monitor API Health

Track API uptime and latency. Alert if:

• Response time > 5 seconds
• Error rate > 1%
• Quota usage > 90%

Integration Examples

Sign-Up Form Validation (React)

import { useState } from 'react';

function SignUpForm() {
  const [email, setEmail] = useState('');
  const [valid, setValid] = useState(null);

  const handleVerify = async () => {
    const response = await fetch('https://emails-wipes.com/api/v1/verify', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ email })
    });
    const result = await response.json();
    setValid(result.deliverable);
  };

  return (
    <form>
      <input 
        value={email} 
        onChange={(e) => setEmail(e.target.value)} 
        onBlur={handleVerify}
      />
      {valid === false && <p style={{color: 'red'}}>Invalid email</p>}
    </form>
  );
}

WordPress Integration

add_action('user_register', 'verify_user_email');

function verify_user_email($user_id) {
    $user = get_userdata($user_id);
    $email = $user->user_email;

    $response = wp_remote_post('https://emails-wipes.com/api/v1/verify', [
        'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
        'body' => json_encode(['email' => $email])
    ]);

    $result = json_decode(wp_remote_retrieve_body($response));

    if (!$result->deliverable) {
        wp_delete_user($user_id);
        wp_die('Invalid email address. Please use a valid email.');
    }
}

Pricing

Overage: $0.01 per additional verification (all plans)

Launch offer: Use code REDDIT50 for 50% off your first 3 months

FAQ

How accurate is the API?

Our API achieves 99.5% accuracy through multi-layer validation:

• Syntax checks (regex + RFC validation)
• DNS/MX record verification
• SMTP handshake (mailbox existence)
• Disposable/catch-all detection

How fast is verification?

Average response time:

• Syntax check: <50ms
• DNS check: 100-300ms
• SMTP check: 500-3000ms
• Total: 1-3 seconds per email

Do you store verified emails?

No. We only log:

• Hashed email (for caching, 30 days)
• Validation result (valid/invalid/risky)
• Timestamp

Full email addresses are never stored.

Can I verify emails from any country?

Yes. We support international domains including:

• Country-code TLDs (.uk, .de, .fr, .jp)
• Internationalized domains (IDN)
• Unicode email addresses (RFC 6531)

What happens if the API is down?

We guarantee 99.9% uptime. If the API is unreachable:

• Implement retry logic with exponential backoff
• Fall back to basic syntax validation
• Check our status page: status.emails-wipes.com

Conclusion

Email verification APIs are essential for any app that sends email. They save money (fewer bounces), protect sender reputation, and improve deliverability.

Key takeaways:

• ✅ Verify at collection point (sign-up forms)
• ✅ Use bulk endpoints for large lists
• ✅ Cache results for 30-90 days
• ✅ Handle errors gracefully (retry logic)
• ✅ Monitor API health and quota