RESTful API v4- Detailed JSON or XML Response
RESTful API v4 | Real-time Email Validation
API Integration:
The RESTful API uses 1 validation per successful attempt and can be integrated into nearly any website or application using the programming language of your choice. Your application needs to make a simple HTTP GET or POST request to the RESTful API with 2 requirements, your api key and the email address to be validated. The api will respond with a JSON or XML response for the result of the verification you just requested. Please see "Main Status Responses" for a list of all possible responses you may receive when querying the RESTful API.
XML or JSON response:
By default the api responds in a JSON format. To enable the XML response please send "xml=true" in your requests.
Request Labeling:
By default the api will label failed emails added to your in-house blacklist with the label "RESTful API v4". You can add a "label=Contact Form" to track exactly where you are receiving the emails from. Please url_encode the value if needed.
Main Status Responses:
Status="passed"- A passed response is an address that has passed all tests.
--Event="mailbox_exists"- The address provided passed all tests.
Status="failed"- A failed response is an address that has failed 1 or more tests.
--Event="mailbox_does_not_exist"- The address provided does not exist.
--Event="mailbox_full"- The mailbox is full.
--Event="invalid_syntax"- The address provided is not in a valid format.
--Event="domain_does_not_exist"- The address provided does not have a valid dns.
--Event="mxserver_does_not_exist"- The address provided does not have a mx server.
--Event="blacklisted_external"- The address provided was found in your (Mailchimp, Postmark, Sendgrid, etc.) blacklist.
--Event="blacklisted_failed"- The address provided was found in your failed blacklist containing previously failed addresses.
--Event="blacklisted_domain"- The domain provided was found in your domain blacklist.
Status="unknown"- A unknown response is an address that can not be accurately tested.
--Event="is_catchall"- Is a Catchall mx server config.
--Event="is_greylisting"- Greylisting is active on this server.
--Event="inconclusive"- Transient error, please try again later.
Additional Responses:
"email"- The address that was validated.
"emailSuggested"- The address contained a typo and we have suggested the most likely repaired version.
"mailbox"- The mailbox that was validated.
"domain"- The domain that was validated.
"mxIp"- The ip address of the mail server that was validated.
"mxLocation"- The location of the mail server that was validated.
"isComplainer"- The address is a frequent complainer.
"isDisposable"- The address is a disposable email address.
"isFreeService"- The address is a free email account.
"isOffensive"- The address contains bad words.
"isRoleAccount"- The address is a role account.
"validationsRemaining"- The amount of validations remaining in your account balance.
"hourlyQuotaRemaining"- The amount of api requests remaining in your account for this hourly segment.
"execution"- The amount of time taken to validate this address in ms.
Example of email validation using PHP and cURL
<?php
// set the api key and email to be validated
$key = '';
$email = urlencode('example@email.com');
// use curl to make the request
$url = 'https://api-v4.bulkemailchecker.com/?key='.$key.'&email='.$email;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 15);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$response = curl_exec($ch);
curl_close($ch);
// decode the json response
$json = json_decode($response, true);
// if address is failed, alert the user they entered an invalid email
if($json['status'] == 'failed'){
// send alert
}
?>
Example of email validation using C# (this is a simple console app but it can be adapted into an ASP.NET MVC.NET web page)
using System;
using System.Diagnostics;
using System.Net;
using System.IO;
class Program
{
static void Main(string[] args)
{
string emailValidate = "example@email.com";
string apikey = "";
string serviceUri = "https://api-v4.bulkemailchecker.com/";
string post_data = "key=" + apikey + "&email=" + Server.UrlEncode(emailValidate);
// create a request
HttpWebRequest request = (HttpWebRequest)
WebRequest.Create(serviceUri);
request.Method = "POST";
// turn our request string into a byte stream
byte[] postBytes = System.Text.Encoding.ASCII.GetBytes(post_data);
// this is important - make sure you specify type this way
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = postBytes.Length;
Stream requestStream = request.GetRequestStream();
// now send it
requestStream.Write(postBytes, 0, postBytes.Length);
requestStream.Close();
// grab te response and print it out to the console
HttpWebResponse response = (HttpWebResponse)request.GetResponse();
Console.WriteLine(new StreamReader(response.GetResponseStream()).ReadToEnd());
Console.ReadLine();
}
}
Rest API Usage
- 1 validation is consumed per successful attempt.
- Limit of maximum requests per hour.
- Limit of concurrent connections.