Real-time API - Real-time Email Validation API

Real-time API Key



API Integration

The Real-time API utilizes a credit-based pricing structure, consuming 1 credit per successful passed/failed test result. It offers seamless integration with virtually any website or application, supporting various programming languages. To use the Real-time API, your application must send a simple HTTP GET or POST request with two parameters: your API key and the email address to be processed. The API will return the verification results in either JSON or XML format. For a comprehensive list of possible responses, please refer to the "Main Status Responses" section.

JSON or XML Response

The API responds in JSON format by default. To receive the response in XML format, include the parameter xml=true in your requests.

Request Labeling

By default, the Real-time API labels failed emails added to your blacklist with "Real-time API". To customize this label, include the parameter label=Contact Form (URL encoded if necessary) to track the source of the emails.

Main Status Responses

Status="passed" - A passed response indicates an address that has passed all tests.
--Event="mailbox_exists" - The address provided passed all tests.

Status="failed" - A failed response indicates an address that has failed one 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 valid MX server.
--Event="blacklisted_external" - The address provided was found in your external 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" - An unknown response indicates an address that cannot be accurately tested.
--Event="is_catchall" - Is a Catchall MX server configuration.
--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 intended version.
"mailbox" - The mailbox that was validated.
"domain" - The domain 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.
"timestampUTC" - The UTC timestamp of when the address was validated.
"execution" - The amount of time taken to validate this address in ms.
"creditsRemaining" - The amount of validations remaining in your account balance.
"hourlyQuotaRemaining" - The amount of API requests remaining in your account for this hourly segment.
"mxEnrichment" - Useful information related to the MX server such as IP, Hostname, Geolocation, ISP, and ASN details.




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.bulkemailchecker.com/real-time/?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 Python and requests

import requests
import json
import urllib.parse

# Set the API key and email to be validated
api_key = ''
email = 'example@email.com'

# URL encode the email
encoded_email = urllib.parse.quote(email)

# Use requests to make the request
url = f'https://api.bulkemailchecker.com/real-time/?key={api_key}&email={encoded_email}'
response = requests.get(url, timeout=15)

# Decode the JSON response
json_response = response.json()

# If the address has failed validation, alert the user they entered an invalid email
if json_response.get('status') == 'failed':
    # Send alert
    print('Invalid email address')




Example of email validation using Go and net/http

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "time"
    "io/ioutil"
)

func main() {
    // Set the API key and email to be validated
    apiKey := ""
    email := "example@email.com"
    
    // URL encode the email
    encodedEmail := url.QueryEscape(email)
    
    // Use net/http to make the request
    baseUrl := "https://api.bulkemailchecker.com/real-time/"
    params := url.Values{}
    params.Add("key", apiKey)
    params.Add("email", encodedEmail)
    
    // Create the URL with query parameters
    apiUrl := fmt.Sprintf("%s?%s", baseUrl, params.Encode())

    client := &http.Client{
        Timeout: 15 * time.Second,
    }

    resp, err := client.Get(apiUrl)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    // Read the response body
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    // Decode the JSON response
    var jsonResponse map[string]interface{}
    if err := json.Unmarshal(body, &jsonResponse); err != nil {
        fmt.Println("Error:", err)
        return
    }

    // If the address has failed validation, alert the user they entered an invalid email
    if status, ok := jsonResponse["status"].(string); ok && status == "failed" {
        // Send alert
        fmt.Println("Invalid email address")
    }
}




Example of email validation using Node.js and axios

const axios = require('axios');
const querystring = require('querystring');

// Set the API key and email to be validated
const apiKey = '';
const email = 'example@email.com';

// URL encode the email
const encodedEmail = querystring.escape(email);

// Use axios to make the request
const url = `https://api.bulkemailchecker.com/real-time/?key=${apiKey}&email=${encodedEmail}`;

axios.get(url, { timeout: 15000 })
    .then(response => {
        const jsonResponse = response.data;

        // If the address has failed validation, alert the user they entered an invalid email
        if (jsonResponse.status === 'failed') {
            // Send alert
            console.log('Invalid email address');
        }
    })
    .catch(error => {
        console.error('Error:', error);
    });




Example of email validation using Ruby and net/http

require 'net/http'
require 'uri'
require 'json'

# Set the API key and email to be validated
api_key = ''
email = 'example@email.com'

# URL encode the email
encoded_email = URI.encode(email)

# Use net/http to make the request
url = URI.parse("https://api.bulkemailchecker.com/real-time/?key=#{api_key}&email=#{encoded_email}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url.request_uri)
response = http.request(request)

# Decode the JSON response
json_response = JSON.parse(response.body)

# If the address has failed validation, alert the user they entered an invalid email
if json_response['status'] == 'failed'
  # Send alert
  puts 'Invalid email address'
end




Example of email validation using Java and HttpURLConnection

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URLEncoder;
import java.net.URL;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class EmailValidator {

    public static void main(String[] args) {
        // Set the API key and email to be validated
        String apiKey = "";
        String email = "example@email.com";

        try {
            // URL encode the email
            String encodedEmail = URLEncoder.encode(email, "UTF-8");

            // Create the URL with query parameters
            String apiUrl = "https://api.bulkemailchecker.com/real-time/?key=" + apiKey + "&email=" + encodedEmail;

            // Use HttpURLConnection to make the request
            URL url = new URL(apiUrl);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.setConnectTimeout(15000);
            connection.setReadTimeout(15000);

            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
                String inputLine;
                StringBuffer response = new StringBuffer();

                while ((inputLine = in.readLine()) != null) {
                    response.append(inputLine);
                }
                in.close();

                // Decode the JSON response
                JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();

                // If the address has failed validation, alert the user they entered an invalid email
                if ("failed".equals(jsonResponse.get("status").getAsString())) {
                    // Send alert
                    System.out.println("Invalid email address");
                }
            } else {
                System.out.println("GET request failed");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}




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.bulkemailchecker.com/real-time/";
        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 the response and print it out to the console
        HttpWebResponse response = (HttpWebResponse)request.GetResponse();
        Console.WriteLine(new StreamReader(response.GetResponseStream()).ReadToEnd());
        Console.ReadLine();
    }
}






Example of email validation in Google Sheets

The basic example provided is a simple IMPORTXML function that can validate a email address.

Please note, it is advised to copy the verification results to a new spreadsheet for saving, as Google may run the ImportXML function unexpectedly when the spreadsheet is opened again and reprocess all of your previously validated addresses. Bulk Email Checker will not honor refund requests in the instance of consumed verifications due to reprocessing.

//ImportXML function to be used via Google Sheets
=IMPORTXML("https://api.bulkemailchecker.com/real-time/?key=&xml=true&email="&[CELL-CONTAINING-EMAIL-TO-VALIDATE];"//BulkEmailChecker")




Example of email validation in Microsft Excel

The basic example provided is a simple VBA Macro using an IMPORTXML function which can be added via Excel's programming tab to validate a email address.

//ImportXML Module to add via Excel's programming tab.
Function ImportXML(url As String, query As String)
    Dim document    As MSXML2.DOMDocument60
    Dim http        As New MSXML2.XMLHTTP60
    http.Open "GET", url, False
    http.send
    Set document = http.responseXML
    ImportXML = document.SelectSingleNode(query).nodeTypedValue
End Function

//ImportXML Module Syntax to validate an email address
=ImportXML("https://api.bulkemailchecker.com/real-time/key=&xml=true&email=[EMAIL-TO-VALIDATE]";"BulkEmailChecker")



Real-time API Limits

  • Limit of maximum requests per hour
  • Limit of threads / concurrent connections
Real-time API Passed - 10 Day
0,0,0,0,0,0,0,0,0,0
Real-time API Failed - 10 Day
0,0,0,0,0,0,0,0,0,0
Real-time API Unknown - 10 Day
0,0,0,0,0,0,0,0,0,0
Real-time API Threads Limit Reached - 10 Day
0,0,0,0,0,0,0,0,0,0