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:
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.
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.
API calls can return following errors:
Description |
---|
The request did not contain HTTP header Key. |
The value of the Key HTTP header was invalid. |
There was not enough requests on the account to perform the requested operation. |
The caller or the callback was blacklisted. Please contact support. |
The caller executes too many requests too quickly. See the Limits section below. |
The value of ARG argument is invalid. The argument's value was either in invalid format, too long, or otherwise in conflict with the specification. |
The request did not contain ARG argument, which was required. |
The request could not be completed. This could happen when the service is in the maintenance mode or due to an unexpected error. Please try again in a few minutes. If the problem persists for more than 30 minutes, please contact support. |
An error occurred during parsing the request. Please check that your code conforms to the specification. |
The caller is not authorized to perform the requested operation. |
The identifier of the requested object was not found. |
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.
EMAIL_RESULT structure is defined as follows (see Email Verifier Results Categories for more on categories) :
Name | Type | Description |
---|---|---|
emailAddress | string | Email address that was verified. |
validNoDisposableNoCatchAll | bool | Set if the email address belongs to Valid emails that are neither disposable, nor catch all category. |
disposable | bool | Set if the email address belongs to Disposable emails category. |
catchAll | bool | Set if the email address belongs to Catch all domain emails category. |
invalidGoodFormat | bool | Set if the email address belongs to Invalid emails with valid email address format category. |
invalidBadFormat | bool | Set if the email address belongs to Email addresses in invalid format category. |
unknown | bool | Set if the email address belongs to Email addresses which validity could not be checked category. |
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.
The following fields are included to the successful call reponse:
Name | Type | Description |
---|---|---|
results | array | Array of EMAIL_RESULT structures. |
Creates and immediately starts a new task that verifies up to 10,000 emails.
The following fields are included to the successful call reponse:
Name | Type | Description |
---|---|---|
taskId | string | Identifier of the task. If callbackUrl was provided on the input, this is the identifier that will be added to the query string. |
taskUrl | string | The full URL where to check for the task results. See Get Task Results call below. |
Returns the current task status and if the task is finished, it also returns the results.
The following fields are included to the successful call reponse:
Name | Type | Description |
---|---|---|
taskStatus | int |
One of the following values:
|
totalEmails | int | Total number of emails in the task. |
emailsFinished | int | Number of emails that have been verified already. |
invalidFormatCount | int | Number of emails in the Email addresses in invalid format category. |
invalidGoodFormatCount | int | Number of emails in Invalid emails with valid email address format category. |
catchAllCount | int | Number of emails in Catch all domain emails category. |
disposableCount | int | Number of emails in Disposable emails category. |
validCount | int | Number of emails in Valid emails that are neither disposable, nor catch all category. |
unknownCount | int | Number of emails in Email addresses which validity could not be checked category. |
timeStart | string | The date and time when the task started. Format is YYYY-MM-DD hh:mm:ss, timezone is UTC. |
timeFinish | string | The date and time when the task finished. Format is YYYY-MM-DD hh:mm:ss, timezone is UTC. Only included if the task is finished. |
timeExpire | string | The date and time of the task expiration. Format is YYYY-MM-DD hh:mm:ss, timezone is UTC. Only included if the task is finished. |
results | string | Array of EMAIL_RESULT structures. Only included if the task is finished. |
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.
Download Archive with Sample Filesusing 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; } } }
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.
Download Archive with Sample Files<?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; } } }