Documentation - EmailsVerify

Introduction

The EmailsVerify API allows you to validate email addresses in real-time, helping you maintain a clean email list and improve deliverability.

Our verification process checks various aspects of an email address:

Syntax validation
Domain existence
MX records check
Mailbox verification
Disposable email detection
Free email provider detection

Note: Our API is designed for high performance and accuracy. We guarantee 98%+ accuracy rate for email verification.

Authentication

To use the EmailsVerify API, you need an API key. You can obtain one by signing up for an account.

Include your API key in the Authorization header of your requests:

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

Security warning: Protect your API key as you would a password. Do not expose it in client-side code or public repositories.

Quick Start

Here's how to get started with the EmailsVerify API:

JavaScript

// Using fetch API
const verifyEmail = async (email) => {
  try {
    const response = await fetch('https://api.emailsverify.com/v1/verify', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({ email })
    });
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error verifying email:', error);
  }
};

// Example usage
verifyEmail('[email protected]')
  .then(result => console.log(result));

Python

import requests

def verify_email(email):
    url = 'https://api.emailsverify.com/v1/verify'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    payload = {'email': email}
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# Example usage
result = verify_email('[email protected]')
print(result)

PHP

<?php
function verify_email($email) {
    $url = 'https://api.emailsverify.com/v1/verify';
    $data = array('email' => $email);
    $options = array(
        'http' => array(
            'header'  => "Content-type: application/json\r\n" .
                        "Authorization: Bearer YOUR_API_KEY\r\n",
            'method'  => 'POST',
            'content' => json_encode($data)
        )
    );
    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    return json_decode($result, true);
}

// Example usage
$result = verify_email('[email protected]');
print_r($result);
?>

Verification Endpoint

The main endpoint for email verification is:

POST https://api.emailsverify.com/v1/verify

Request Parameters

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

Response Object

The API returns a JSON object with the following fields:

Field	Type	Description
email	string	The email address that was verified
status	string	The verification status (deliverable, undeliverable, risky, unknown)
reason	string	The reason for the status result
score	float	A score between 0 and 1 indicating the confidence in the result
domain	object	Information about the email domain
account	object	Information about the email account

Example Response

{
  "email": "[email protected]",
  "status": "deliverable",
  "reason": "accepted_email",
  "score": 0.96,
  "domain": {
    "name": "example.com",
    "exists": true,
    "has_mx_records": true,
    "is_disposable": false,
    "is_free_provider": false
  },
  "account": {
    "exists": true,
    "disabled": false
  }
}

Status Codes

The API uses conventional HTTP response codes to indicate the success or failure of an API request:

Code	Description
200 - OK	The request was successful
400 - Bad Request	The request was invalid or missing required parameters
401 - Unauthorized	No valid API key provided
403 - Forbidden	The API key doesn't have permission to perform the request
429 - Too Many Requests	Rate limit exceeded
500 - Server Error	An error occurred on the server

Integration Guide

Follow these best practices to integrate our verification service into your application:

1. Form Validation

Verify emails in real-time as users enter them in your registration forms:

// Example of form validation with our API
document.getElementById('email-form').addEventListener('blur', async function(event) {
  const email = event.target.value;
  const resultElement = document.getElementById('validation-result');
  
  if (email) {
    resultElement.textContent = 'Verifying...';
    
    try {
      const result = await verifyEmail(email);
      
      if (result.status === 'deliverable') {
        resultElement.textContent = 'Email is valid!';
        resultElement.className = 'text-green-500';
      } else {
        resultElement.textContent = `Email may not be deliverable: ${result.reason}`;
        resultElement.className = 'text-red-500';
      }
    } catch (error) {
      resultElement.textContent = 'Verification failed. Please try again.';
      resultElement.className = 'text-yellow-500';
    }
  }
});

2. Backend Implementation

Integrate verification before sending emails to ensure high deliverability:

// Node.js example with Express
const express = require('express');
const axios = require('axios');
const app = express();

app.use(express.json());

// Middleware to verify emails before processing
async function verifyEmailMiddleware(req, res, next) {
  const { email } = req.body;
  
  try {
    const response = await axios.post('https://api.emailsverify.com/v1/verify', 
      { email },
      { 
        headers: { 
          'Authorization': `Bearer ${process.env.EMAIL_VERIFY_API_KEY}`,
          'Content-Type': 'application/json'
        } 
      }
    );
    
    if (response.data.status === 'deliverable') {
      // Email is valid, continue with the request
      next();
    } else {
      // Email is not deliverable
      res.status(400).json({ 
        error: 'Invalid email address',
        details: response.data
      });
    }
  } catch (error) {
    console.error('Email verification error:', error);
    // Continue anyway if the verification service fails
    next();
  }
}

// Apply middleware to routes that need email verification
app.post('/register', verifyEmailMiddleware, (req, res) => {
  // Process registration
  res.json({ success: true });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Bulk Verification

For bulk email verification, use our dedicated bulk endpoint:

POST https://api.emailsverify.com/v1/verify/bulk

The request accepts an array of email addresses:

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

The response will include verification results for each email:

{
  "results": [
    {
      "email": "[email protected]",
      "status": "deliverable",
      "reason": "accepted_email",
      "score": 0.95
      // Other fields...
    },
    {
      "email": "[email protected]",
      "status": "undeliverable",
      "reason": "invalid_mailbox",
      "score": 0.2
      // Other fields...
    },
    {
      "email": "[email protected]",
      "status": "deliverable",
      "reason": "accepted_email",
      "score": 0.87
      // Other fields...
    }
  ],
  "summary": {
    "total": 3,
    "deliverable": 2,
    "undeliverable": 1,
    "risky": 0,
    "unknown": 0
  }
}

Note: Bulk verification is available on all paid plans. The maximum number of emails per request depends on your plan.

Webhooks

For long-running bulk verification jobs, you can use webhooks to receive notifications when the process is complete:

Setting Up Webhooks

1. Register a webhook URL in your account dashboard

2. Submit bulk verification requests with the webhook parameter:

{
  "emails": ["[email protected]", "[email protected]", ...],
  "webhook_url": "https://your-server.com/webhook-handler",
  "webhook_data": {
    "job_id": "custom-job-123",
    "user_id": "user-456"
  }
}

3. Implement a webhook handler on your server:

// Express webhook handler example
app.post('/webhook-handler', express.json(), (req, res) => {
  const { event_type, data, webhook_data } = req.body;
  
  console.log(`Received webhook: ${event_type}`);
  console.log(`Job ID: ${webhook_data.job_id}`);
  
  if (event_type === 'bulk_verification_completed') {
    // Process the completed verification results
    const { results, summary } = data;
    
    // Update your database or notify users
    // ...
    
    console.log(`Verification job completed. ${summary.deliverable} of ${summary.total} emails are deliverable.`);
  }
  
  // Always respond with 200 OK to acknowledge receipt
  res.status(200).send('Webhook received');
});

Webhook Events

Event Type	Description
bulk_verification_completed	Sent when a bulk verification job is complete
bulk_verification_failed	Sent when a bulk verification job fails
usage_limit_warning	Sent when you reach 80% of your monthly limit

API Documentation