Email Verification API Documentation and Samples

Table of Contents

• 1 API Credentials
• 2 General Mechanisms
• 3 API Calls
• 4 Sample Implementations

1 API Credentials

Before API can be used, the user has to register a Bulk Email Verifier account and obtain an API Key. When you are logged in Bulk Email Verifier, under My Account section, click API Access link in the left side menu:

2 General Mechanisms

2.1 Requests and Authentication

All calls to Bulk Email Verifier are authenticated HTTP GET or HTTP POST requests. POST requests use application/x-www-form-urlencoded content type. All calls are made to URL in a generic format:

where $ACTION is specific to the API call – see below.

The authentication is implemented using a HTTP header Key, which must be set to your account API Key.

2.2 Responses

A response to an API call is in JSON format. In case of a successful call, the format is

In case of an error, the format is

where $MESSAGE is a string. See next section for list of error messages.

2.3 Error Messages

API calls can return following errors:

2.4 Limits

All API calls are rate limited. The default limit is 20 calls per 120 seconds. If you need higer limits, please contact support with your request.

2.5 Common Structures

EMAIL_RESULT structure is defined as follows (see Email Verifier Results Categories for more on categories) :

3 API Calls

3.1 Fast Verification of Single Email Address

This API call is designed to be usable for real-time verification – for example, in account registration forms. It should be understood that the quality of the verification provided by this call can't be as high as of the full verification process (provided by Task API calls, see below), which takes much longer time.

This call is designed to finish within 20 seconds. For most emails, the result will be provided in less than 10 seconds. If the verification process takes longer than 20 seconds, the API call puts the email address in the unknown category (see Email Verifier Results Categories) and returns to the caller within the 20 second limit.

3.1.1 Input Parameters

• $ACTION = Single
• HTTP METHOD = POST
• POST body arguments:
  • email – The email address to verify.

3.1.2 Output Response

The following fields are included to the successful call reponse:

3.2 Create New Task

Creates and immediately starts a new task that verifies up to 10,000 emails.

3.2.1 Input Parameters

• $ACTION = TaskCreate
• HTTP METHOD = POST
• POST body arguments:
  • emails – A comma separated list of email addresses to verify. The list can contain up to 10,000 email addresses.
  • callbackUrl (optional) – If specified, and the task is created and started successfully, it points to a URL that receives a HTTP GET request once the task is finished. The task identifier will be added to the URL query string as id=$ID. For example, if you pass http://www.example.com/myCallback?some=parameter as the callbackUrl, once the task is finished, our server will send an HTTP GET request to http://www.example.com/myCallback?some=parameter&id=$ID. The callback handler is expected to return a single line response containing BEV: OK. Callbacks that return something else may get blacklisted.

3.2.2 Output Response

The following fields are included to the successful call reponse:

3.3 Get Task Results

Returns the current task status and if the task is finished, it also returns the results.

3.3.1 Input Parameters

• $ACTION = TaskResult/$ID
• HTTP METHOD = GET

3.3.2 Output Response

The following fields are included to the successful call reponse:

4 Sample Implementations

C# Implementation

A basic C# sample that demonstrates how to call fast verification API to verify a single email, and how to create a new task for full verification and wait for results using polling method.

using System;
using System.Text;
using System.Collections.Generic;
using System.Threading;
using System.Security.Cryptography.X509Certificates;
using System.Net.Security;

namespace BEV_API
{
  class Program
  {
    static void Main(string[] args)
    {
      if ((args.Length != 2) && (args.Length != 3))
      {
        Console.WriteLine("Usage: bev-api <API Key> <Email Address> [Comma Separated Email List]");
        return;
      }

      string apiKey = args[0];
      string emailForSingleQuery = args[1];

      // API initialization
      BevApi api = new BevApi(apiKey);

      // Verify single email - guaranteed to end within 20 seconds.
      Console.WriteLine("Sending single email verification request.");
      BevApiResponseSingle singleResponse;
      if (api.VerifyEmail(emailForSingleQuery, out singleResponse))
      {
        PrintVerificationResults(singleResponse.results);
      }
      else Console.WriteLine("Email verification failed. Error message: {0}", singleResponse.message);

      Console.WriteLine();
      Console.WriteLine("----------------------------------------------");
      Console.WriteLine();

      if (args.Length == 2)
        return;

      string emailListForTaskQuery = args[2];
      string[] emailsForTaskQuery = emailListForTaskQuery.Split(new char[] { ',' });

      // Create new big task and wait until it finishes.
      Console.WriteLine("Creating new verification task for {0} emails.", emailsForTaskQuery.Length);
      BevApiResponseTaskCreate taskCreateResponse;
      if (api.CreateTask(emailListForTaskQuery, out taskCreateResponse))
      {
        Console.WriteLine("New task created, result URL: {0}", taskCreateResponse.taskUrl);

        int intervalSeconds = emailsForTaskQuery.Length;
        Console.WriteLine();
        Console.WriteLine("Polling task in {0} seconds intervals.", intervalSeconds);

        bool done = false;
        while (!done)
        {
          Thread.Sleep(intervalSeconds * 1000);

          BevApiResponseTaskResult taskResultResponse;
          if (api.GetTaskResults(taskCreateResponse.taskUrl, out taskResultResponse, out done))
          {
            if (done)
            {
              Console.WriteLine("Task is finished!");
              Console.WriteLine("  Started: {0}", taskResultResponse.timeStart);
              Console.WriteLine("  Finished: {0}", taskResultResponse.timeFinish);
              Console.WriteLine("  Expires: {0}", taskResultResponse.timeExpire);
              Console.WriteLine("  Total number of emails: {0}", taskResultResponse.totalEmails);
              Console.WriteLine("  Number of valid emails that are neither disposable, nor catch all: {0}", taskResultResponse.validCount);
              Console.WriteLine("  Number of disposable email: {0}", taskResultResponse.disposableCount);
              Console.WriteLine("  Number of catch all domain emails: {0}", taskResultResponse.catchAllCount);
              Console.WriteLine("  Number of invalid emails with valid email address format: {0}", taskResultResponse.invalidGoodFormatCount);
              Console.WriteLine("  Number of email addresses in invalid format: {0}", taskResultResponse.invalidFormatCount);
              Console.WriteLine("  Number of email addresses which validity could not be checked: {0}", taskResultResponse.unknownCount);
              Console.WriteLine();
              Console.WriteLine();
              PrintVerificationResults(taskResultResponse.results);
            }
            else Console.WriteLine("Task is {0}, progress is {1}/{2} emails ...", taskResultResponse.taskStatus, taskResultResponse.emailsFinished, taskResultResponse.totalEmails);
            Console.WriteLine();
          }
          else Console.WriteLine("Checking for task results failed. Error message: {0}", taskResultResponse.message);
        }
      }
      else Console.WriteLine("Unable to create new task. Error message: {0}", taskCreateResponse.message);
    }

    static void PrintVerificationResults(BevEmailResult[] Results)
    {
      if (Results == null)
      {
        Console.WriteLine("No results!");
        return;
      }

      foreach (BevEmailResult evr in Results)
      {
        Console.WriteLine("Results for email address '{0}':", evr.emailAddress);
        Console.WriteLine("  Is valid email that is neither disposable, nor catch all: {0}", evr.validNoDisposableNoCatchAll);
        Console.WriteLine("  Is disposable email: {0}", evr.disposable);
        Console.WriteLine("  Is catch all domain email: {0}", evr.catchAll);
        Console.WriteLine("  Is invalid email with valid email address format: {0}", evr.invalidGoodFormat);
        Console.WriteLine("  Is email address in invalid format: {0}", evr.invalidBadFormat);
        Console.WriteLine("  Is email address which validity could not be checked: {0}", evr.unknown);
        Console.WriteLine();
      }

    }

    public static bool RemoteCertificateValidationCallback(Object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors)
    {
      return true;
    }
  }
}

using System;
using System.Collections.Generic;
using System.Collections.Specialized;
using System.Linq;
using System.Text;
using System.Security.Cryptography;
using System.IO;
using System.Net;
using System.Threading;
using System.Web;
using Newtonsoft.Json;

namespace BEV_API
{
  public class BevApi
  {
    private string key;

    public const string ApiUrl = "https://bulk-email-verifier.biz/api/{0}";

    public BevApi(string ApiKey)
    {
      key = ApiKey;
    }

    private string SendRequest(string Action, NameValueCollection Params)
    {
      string responseData = null;
      StreamReader respStream = null;
      try
      {
        string requestStr = string.Format(ApiUrl, Action);
        HttpWebRequest request = (HttpWebRequest)WebRequest.Create(requestStr);
        request.Method = "POST";

        request.Headers["Key"] = key;

        string postData = "";
        foreach (string pKey in Params)
          postData += string.Format("{0}{1}={2}", postData.Length > 0 ? "&" : "",
            HttpUtility.UrlEncode(pKey), HttpUtility.UrlEncode(Params[pKey]));

        byte[] postDataBytes = Encoding.UTF8.GetBytes(postData);
        request.ContentType = "application/x-www-form-urlencoded";
        request.ContentLength = postDataBytes.Length;
        Stream dataStream = request.GetRequestStream();
        dataStream.Write(postDataBytes, 0, postDataBytes.Length);

        HttpWebResponse response = (HttpWebResponse)request.GetResponse();

        respStream = new StreamReader(response.GetResponseStream());
        responseData = respStream.ReadToEnd();
      }
      catch
      {
      }

      if (respStream != null) respStream.Close();

      return responseData;
    }

    private bool ProcessResponse<T>(string Json, ref T Response) where T : BevApiResponse
    {
      bool result = false;

      if (!string.IsNullOrEmpty(Json))
      {
        try
        {
          Response = JsonConvert.DeserializeObject<T>(Json);
          result = Response.success;
        }
        catch
        {
          Response.message = "Invalid response received from API server.";
        }
      }
      else Response.message = "Unable to get response from API server.";

      return result;
    }

    public bool VerifyEmail(string Email, out BevApiResponseSingle Response)
    {
      Response = new BevApiResponseSingle();
      NameValueCollection nvc = new NameValueCollection();
      nvc.Add("email", Email);
      string json = SendRequest("Single", nvc);
      return ProcessResponse(json, ref Response);
    }

    public bool CreateTask(string EmailList, out BevApiResponseTaskCreate Response)
    {
      Response = new BevApiResponseTaskCreate();
      NameValueCollection nvc = new NameValueCollection();
      nvc.Add("emails", EmailList);
      string json = SendRequest("TaskCreate", nvc);
      return ProcessResponse(json, ref Response);
    }

    public bool GetTaskResults(string TaskResultUrl, out BevApiResponseTaskResult Response, out bool Done)
    {
      Response = new BevApiResponseTaskResult();
      Done = true;

      string responseData = null;
      StreamReader respStream = null;
      try
      {
        HttpWebRequest request = (HttpWebRequest)WebRequest.Create(TaskResultUrl);
        request.Method = "GET";

        request.Headers["Key"] = key;

        HttpWebResponse response = (HttpWebResponse)request.GetResponse();

        respStream = new StreamReader(response.GetResponseStream());
        responseData = respStream.ReadToEnd();
      }
      catch
      {
      }
      if (respStream != null) respStream.Close();

      bool res = ProcessResponse(responseData, ref Response);
      if (res)
        Done = Response.taskStatus == BevApiTaskStatus.Finished;

      return res;
    }
  }


  public class BevApiRequest
  {
    public string emails { get; set; }
  }

  public class BevApiResponse
  {
    public bool success { get; set; }
    public string message { get; set; }
  }

  public class BevApiResponseSingle : BevApiResponse
  {
    public BevEmailResult[] results { get; set; }
  }

  public class BevApiResponseTaskCreate : BevApiResponse
  {
    public string taskUrl { get; set; }
  }

  public class BevApiResponseTaskResult : BevApiResponse
  {
    public BevApiTaskStatus taskStatus;

    public int totalEmails;
    public int emailsFinished;

    public int invalidFormatCount;
    public int invalidGoodFormatCount;
    public int catchAllCount;
    public int disposableCount;
    public int validCount;
    public int unknownCount;

    public string timeStart;
    public string timeFinish;
    public string timeExpire;

    public BevEmailResult[] results;
  }


  public enum BevApiTaskStatus { Creating, Created, Queued, Running, Finished, Expired }

  public class BevEmailResult
  {
    public string emailAddress { get; set; }
    public bool validNoDisposableNoCatchAll { get; set; }
    public bool disposable { get; set; }
    public bool catchAll { get; set; }
    public bool invalidGoodFormat { get; set; }
    public bool invalidBadFormat { get; set; }
    public bool unknown { get; set; }
  }
}

PHP 5 Implementation

A basic PHP sample that demonstrates how to call fast verification API to verify a single email, and how to create a new task for full verification and use of callback URL to get notified when the task is finished.

<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);

include __DIR__ . "/BevApi.php";


// Settings 
$apiKey = "INSERT YOUR API KEY HERE";
$emailForSingleQuery = "abc@mailinator.com";
$emailListForTaskQuery = "abc@mailinator.com,def@mailinator.com,dfgaii@asdiofjaeriogjrgioj.,gaer 'er 'g er ger @asdfdsaf.com";

$thisUrl = "http" . (!empty($_SERVER['HTTPS'])?"s":"") . "://" . $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'];


// API initialization
$api = new BevApi($apiKey);

// Accept asynchronous callback.
if (isset($_GET['id'])) {
  $id = $_GET['id'];
  $res = $api->GetTaskResults($id);

  $output = "Task is finished!\n"
          . "  Started: " . $res->timeStart . "\n"
          . "  Finished: " . $res->timeFinish . "\n"
          . "  Expires: " . $res->timeExpire . "\n"
          . "  Total number of emails: " . $res->totalEmails . "\n"
          . "  Number of valid emails that are neither disposable, nor catch all: " . $res->validCount . "\n"
          . "  Number of disposable email: " . $res->disposableCount . "\n"
          . "  Number of catch all domain emails: " . $res->catchAllCount . "\n"
          . "  Number of invalid emails with valid email address format: " . $res->invalidGoodFormatCount . "\n"
          . "  Number of email addresses in invalid format: " . $res->invalidFormatCount . "\n"
          . "  Number of email addresses which validity could not be checked: " . $res->unknownCount . "\n"
          . "\n\n";

  foreach ($res->results as $result)
  {
    $output .= VerificationResultToString($result);
  }
  
  file_put_contents(__DIR__ . "/Result-$id.txt", $output);
  echo "BEV: OK\n";
  exit;
}


echo "Sending single email for quick verification ...<br>";
$response = $api->VerifyEmail($emailForSingleQuery);
if ($response->success) {
  $res = $response->results[0];
  echo nl2br(VerificationResultToString($res));
} else {
  echo "Verification failed: " . $response->message . "<br>";
  exit;
}


echo "Creating new task for full verification ...<br>";
$response = $api->TaskCreate($emailListForTaskQuery, $thisUrl);
if ($response->success) {
  $taskId = $response->taskId;
  $taskUrl = $response->taskUrl;
  echo "Task created with ID '$taskId', task check URL is '$taskUrl'.<br>";
  echo "Task result will be written to Result-$taskId.txt once the task is finished.<br>";
} else {
  echo "Verification failed: " . $response->message . "<br>";
  exit;
}

function VerificationResultToString($res) {
  $output = "Results for " . $res->emailAddress . ":\n"
          . "  Is valid email that is neither disposable, nor catch all: " . boolstr($res->validNoDisposableNoCatchAll) . "\n"
          . "  Is disposable email: " . boolstr($res->disposable) . "\n"
          . "  Is catch all domain email: " . boolstr($res->catchAll) . "\n"
          . "  Is invalid email with valid email address format: " . boolstr($res->invalidGoodFormat) . "\n"
          . "  Is email address in invalid format: " . boolstr($res->invalidBadFormat) . "\n"
          . "  Is email address which validity could not be checked: " . boolstr($res->unknown) . "\n"
          . "\n\n";
  return $output;
}

function boolstr($b) {
  return $b ? 'true' : 'false';
}

<?php

class BevApi
{
  const API_URL = "https://bulk-email-verifier.biz/Api/";
  const TASK_STATUS_CREATING = 0;
  const TASK_STATUS_CREATED  = 1;
  const TASK_STATUS_QUEUED   = 2;
  const TASK_STATUS_RUNNING  = 3;
  const TASK_STATUS_FINISHED = 4;
  const TASK_STATUS_EXPIRED  = 5;

  private $key;

  public function __construct($key)
  {
    $this->key = $key;
  }

  /**
   * @param $action
   * @param array $params
   * @return array
   * @throws Exception
   */
  private function postRequest($action, array $params = array())
  {
    $result = null;

    try {
      $postFields = http_build_query($params);

      // generate extra headers
      $headers = array(
        'Key: ' . $this->key
      );

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_URL, self::API_URL . $action);
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
      curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
      curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
      $res = curl_exec($ch);

      if ($res === false) {
        throw new \Exception('Could not get a reply: ' . curl_error($ch));
      } else {
        $result = json_decode($res, true);

        if ($result === null) {
          throw new \Exception('Invalid response received.');
        }
      }
    } catch (\Exception $e) {
      throw $e;
    }

    return $result;
  }

  /**
   * @param $action
   * @return array
   * @throws Exception
   */
  private function getRequest($action)
  {
    $result = null;

    try {
      // generate extra headers
      $headers = array(
        'Key: ' . $this->key
      );

      $ch = curl_init();
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_URL, self::API_URL . $action);
      curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
      curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
      curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
      $res = curl_exec($ch);

      if ($res === false) {
        throw new \Exception('Could not get a reply: ' . curl_error($ch));
      } else {
        $result = json_decode($res, true);

        if ($result === null) {
          throw new \Exception('Invalid response received.');
        }
      }
    } catch (\Exception $e) {
      throw $e;
    }

    return $result;
  }

  public function VerifyEmail($email)
  {
    $response = $this->postRequest("Single", array('email' => $email));
    $result = new BevApiResponseSingle($response);

    return $result;
  }

  public function TaskCreate($emails, $callbackUrl)
  {
    $response = $this->postRequest("TaskCreate", array('emails' => $emails, 'callbackUrl' => $callbackUrl));
    $result = new BevApiResponseTaskCreate($response);

    return $result;
  }

  public function GetTaskResults($id)
  {
    $response = $this->getRequest("TaskResult/$id");
    $result = new BevApiResponseTaskResult($response);

    return $result;
  }
}

class BevApiResponse
{
  /** @var bool  */
  public $success;
  /** @var string|null */
  public $message;

  public function __construct(array $data)
  {
    foreach ($data as $key => $value) {

      if (!property_exists($this, $key)) {
        throw new \Exception("Invalid property {$key}.");
      }

      $this->{$key} = $value;
    }
  }
}

class BevApiResponseSingle extends BevApiResponse
{
  /** @var BevEmailResult[] */
  public $results;

  public function __construct(array $data)
  {
    foreach ($data as $key => $value) {
      if (!property_exists($this, $key)) {
        throw new \Exception("Invalid property {$key}.");
      }

      $this->{$key} = $value;
    }

    if (!empty($data['results'])) {
      $this->results = array();
      foreach ($data['results'] as $result) {
        $this->results[] = new BevEmailResult($result);
      }
    }
  }
}

class BevApiResponseTaskCreate extends BevApiResponse
{
  /** @var string */
  public $taskId;
  /** @var string */
  public $taskUrl;

  public function __construct(array $data)
  {
    foreach ($data as $key => $value) {
      if (!property_exists($this, $key)) {
        throw new \Exception("Invalid property {$key}.");
      }

      $this->{$key} = $value;
    }
  }
}

class BevApiResponseTaskResult extends BevApiResponse
{
  /** @var int */
  public $taskStatus;

  /** @var int */
  public $totalEmails;
  /** @var int */
  public $emailsFinished;

  /** @var int */
  public $invalidFormatCount;
  /** @var int */
  public $invalidGoodFormatCount;
  /** @var int */
  public $catchAllCount;
  /** @var int */
  public $disposableCount;
  /** @var int */
  public $validCount;
  /** @var int */
  public $unknownCount;

  /** @var string */
  public $timeStart;
  /** @var string */
  public $timeFinish;
  /** @var string */
  public $timeExpire;

  /** @var BevEmailResult[] */
  public $results;

  public function __construct(array $data)
  {
    foreach ($data as $key => $value) {
      if (!property_exists($this, $key)) {
        throw new \Exception("Invalid property {$key}.");
      }

      $this->{$key} = $value;
    }

    if (!empty($data['results'])) {
      $this->results = array();
      foreach ($data['results'] as $result) {
        $this->results[] = new BevEmailResult($result);
      }
    }
  }
}

class BevEmailResult
{
  /** @var string */
  public $emailAddress;
  /** @var bool */
  public $validNoDisposableNoCatchAll;
  /** @var bool */
  public $disposable;
  /** @var bool */
  public $catchAll;
  /** @var bool */
  public $invalidGoodFormat;
  /** @var bool */
  public $invalidBadFormat;
  /** @var bool */
  public $unknown;


  public function __construct(array $data)
  {
    foreach ($data as $key => $value) {
      if (!property_exists($this, $key)) {
        throw new \Exception("Invalid property {$key}.");
      }

      $this->{$key} = $value;
    }
  }
}