Real-time Email Verification API Documentation

Integrate real-time email validation into any application. Simple REST API with support for JSON and XML responses.

https://api.bulkemailchecker.com/real-time/

API Overview

The Real-time Email Verification API allows you to validate email addresses instantly from any application. Using a simple HTTP GET or POST request, you can verify emails and receive detailed results about deliverability, syntax validity, and more.

Credit Usage: The API uses a credit-based pricing structure, consuming 1 credit per successful passed/failed test result. Unknown results do not consume credits.

Key Features

  • Real-time Validation - Results in under 2 seconds
  • Multiple Formats - JSON (default) or XML responses
  • Language Agnostic - Works with any programming language
  • MX Enrichment - Detailed mail server information
  • Typo Suggestions - Automatic email correction suggestions

Authentication

All API requests require authentication using your unique API key. You can find your API key in your account dashboard.

https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@example.com

Keep your API key secure! Never expose your API key in client-side code or public repositories.

Request Parameters

The following parameters can be included in your API requests:

Parameter Required Description
key Required Your unique API key for authentication
email Required The email address to validate (URL encoded)
xml Optional Set to true to receive XML response instead of JSON
label Optional Custom label for tracking (e.g., Contact Form). URL encode if necessary.

Request Labeling: By default, failed emails are labeled "Real-time API" in your blacklist. Use the label parameter to customize this for tracking purposes.

Response Format

The API returns responses in JSON format by default. To receive XML, add xml=true to your request.

Example JSON Response

{
  "status": "passed",
  "event": "mailbox_exists",
  "details": "The address provided passed all tests.",
  "email": "example@gmail.com",
  "emailSuggested": "",
  "mailbox": "example",
  "domain": "gmail.com",
  "isComplainer": false,
  "isDisposable": false,
  "isFreeService": true,
  "isGibberish": false,
  "isOffensive": false,
  "isRoleAccount": false,
  "timestampUTC": "2026-01-22T04:52:08Z",
  "execution": "0.03",
  "creditsRemaining": 99,
  "hourlyQuotaRemaining": 2498,
  "mxEnrichment": {
    "mxIp": "142.250.102.27",
    "mxHostname": "alt4.gmail-smtp-in.l.google.com",
    "mxCity": "",
    "mxPostalCode": "",
    "mxState": "Texas",
    "mxStateISOCode": "TX",
    "mxCountry": "United States",
    "mxCountryISOCode": "US",
    "mxContinent": "North America",
    "mxContinentISOCode": "NA",
    "mxTimezone": "America/Chicago",
    "mxLatitude": "32.7797",
    "mxLongitude": "-96.8022",
    "mxIsp": "Google Servers",
    "mxIspOrganization": "Google Servers",
    "mxAsn": 15169,
    "mxAsnOrganization": "GOOGLE",
    "mxIps": ["142.250.102.27", "172.253.116.27", "..."],
    "mxHostnames": ["alt4.gmail-smtp-in.l.google.com", "..."]
  }
}

Example XML Response

<BulkEmailChecker>
  <status>passed</status>
  <event>mailbox_exists</event>
  <details>The address provided passed all tests.</details>
  <email>example@gmail.com</email>
  <emailSuggested></emailSuggested>
  <mailbox>example</mailbox>
  <domain>gmail.com</domain>
  <isComplainer>false</isComplainer>
  <isDisposable>false</isDisposable>
  <isFreeService>true</isFreeService>
  <isGibberish>false</isGibberish>
  <isOffensive>false</isOffensive>
  <isRoleAccount>false</isRoleAccount>
  <timestampUTC>2026-01-22T04:52:08Z</timestampUTC>
  <execution>0.03</execution>
  <creditsRemaining>99</creditsRemaining>
  <hourlyQuotaRemaining>2498</hourlyQuotaRemaining>
  <mxEnrichment>
    <mxIp>142.250.102.27</mxIp>
    <mxHostname>alt4.gmail-smtp-in.l.google.com</mxHostname>
    <mxCity></mxCity>
    <mxPostalCode></mxPostalCode>
    <mxState>Texas</mxState>
    <mxStateISOCode>TX</mxStateISOCode>
    <mxCountry>United States</mxCountry>
    <mxCountryISOCode>US</mxCountryISOCode>
    <mxContinent>North America</mxContinent>
    <mxContinentISOCode>NA</mxContinentISOCode>
    <mxTimezone>America/Chicago</mxTimezone>
    <mxLatitude>32.7797</mxLatitude>
    <mxLongitude>-96.8022</mxLongitude>
    <mxIsp>Google Servers</mxIsp>
    <mxIspOrganization>Google Servers</mxIspOrganization>
    <mxAsn>15169</mxAsn>
    <mxAsnOrganization>GOOGLE</mxAsnOrganization>
    <mxIps>
      <ip>142.250.102.27</ip>
      <ip>172.253.116.27</ip>
      <ip>142.251.16.27</ip>
      <ip>192.178.223.27</ip>
      <ip>173.194.76.27</ip>
    </mxIps>
    <mxHostnames>
      <hostname>alt4.gmail-smtp-in.l.google.com</hostname>
      <hostname>alt1.gmail-smtp-in.l.google.com</hostname>
      <hostname>gmail-smtp-in.l.google.com</hostname>
      <hostname>alt2.gmail-smtp-in.l.google.com</hostname>
      <hostname>alt3.gmail-smtp-in.l.google.com</hostname>
    </mxHostnames>
  </mxEnrichment>
</BulkEmailChecker>

Status Codes & Events

The API returns one of three main status codes with detailed event information:

PASSED - Valid Email Address

Event Description
mailbox_exists The email address passed all validation tests and the mailbox exists

FAILED - Invalid Email Address

Event Description
mailbox_does_not_exist The mailbox does not exist on the mail server
mailbox_full The mailbox is full and cannot receive new emails
invalid_syntax The email address format is invalid (RFC non-compliant)
domain_does_not_exist The domain has no valid DNS records
mxserver_does_not_exist The domain has no valid MX (mail exchange) records
blacklisted_external The address is in your external blacklist
blacklisted_failed The address was previously verified as failed
blacklisted_domain The domain is in your domain blacklist

UNKNOWN - Cannot Be Determined

Event Description
is_catchall Domain accepts all emails (catch-all configuration)
is_greylisting Server uses greylisting spam prevention
inconclusive Transient error occurred - please retry later

Credit Usage: Only "passed" and "failed" results consume credits. "Unknown" results do not use any credits.

Additional Response Fields

The API returns additional metadata to help you make informed decisions:

Field Type Description
details String Human-readable description of the validation result
email String The email address that was validated
emailSuggested String Suggested correction if a typo was detected (e.g., gmail.con → gmail.com)
mailbox String The mailbox portion of the email (before @)
domain String The domain portion of the email (after @)
isComplainer Boolean Address is known to frequently report spam
isDisposable Boolean Address uses a disposable/temporary email service
isFreeService Boolean Address is from a free email provider (Gmail, Yahoo, etc.)
isGibberish Boolean Address appears to be random/meaningless characters
isOffensive Boolean Address contains offensive or inappropriate words
isRoleAccount Boolean Address is a role account (info@, admin@, support@)
timestampUTC String UTC timestamp of when validation occurred (ISO 8601 format)
execution String Time taken to validate in seconds (e.g., "0.07")
creditsRemaining Integer Credits remaining in your account
hourlyQuotaRemaining Integer API requests remaining for current hour
mxEnrichment Object MX server enrichment data (see table below)

mxEnrichment Object Fields

The mxEnrichment object contains detailed information about the mail server:

Field Type Description
mxIp String Primary MX server IP address
mxHostname String Primary MX server hostname
mxCity String City where MX server is located (if available)
mxPostalCode String Postal code of MX server location (if available)
mxState String State/region of MX server location
mxStateISOCode String ISO code of state (e.g., "TX" for Texas)
mxCountry String Country where MX server is located
mxCountryISOCode String ISO country code (e.g., "US")
mxContinent String Continent where MX server is located
mxContinentISOCode String ISO continent code (e.g., "NA" for North America)
mxTimezone String Timezone of MX server (e.g., "America/Chicago")
mxLatitude String Latitude coordinates of MX server
mxLongitude String Longitude coordinates of MX server
mxIsp String Internet Service Provider hosting the MX server
mxIspOrganization String Organization name of the ISP
mxAsn Integer Autonomous System Number of the network
mxAsnOrganization String Organization name associated with the ASN
mxIps Array All MX server IP addresses for the domain
mxHostnames Array All MX server hostnames for the domain

Code Examples

Copy and paste these examples to quickly integrate email verification into your application:

<?php

// Set the API key and email to be validated
$key = 'YOUR_API_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);

// Check validation result
if($json['status'] == 'failed'){
    // Handle invalid email
    echo 'Invalid email address';
}

?>
import requests
import urllib.parse

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

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

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

# Parse JSON response
json_response = response.json()

# Check validation result
if json_response.get('status') == 'failed':
    print('Invalid email address')
const axios = require('axios');
const querystring = require('querystring');

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

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

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

axios.get(url, { timeout: 15000 })
    .then(response => {
        const jsonResponse = response.data;
        
        // Check validation result
        if (jsonResponse.status === 'failed') {
            console.log('Invalid email address');
        }
    })
    .catch(error => {
        console.error('Error:', error);
    });
package main

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

func main() {
    // Set the API key and email to be validated
    apiKey := "YOUR_API_KEY"
    email := "example@email.com"
    
    // URL encode the email
    encodedEmail := url.QueryEscape(email)
    
    // Build the URL
    apiUrl := fmt.Sprintf(
        "https://api.bulkemailchecker.com/real-time/?key=%s&email=%s",
        apiKey, encodedEmail,
    )

    client := &http.Client{Timeout: 15 * time.Second}
    resp, err := client.Get(apiUrl)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    
    var jsonResponse map[string]interface{}
    json.Unmarshal(body, &jsonResponse)

    // Check validation result
    if status, ok := jsonResponse["status"].(string); ok && status == "failed" {
        fmt.Println("Invalid email address")
    }
}
require 'net/http'
require 'uri'
require 'json'

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

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

# Make the API 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)

# Parse JSON response
json_response = JSON.parse(response.body)

# Check validation result
if json_response['status'] == 'failed'
  puts 'Invalid email address'
end
import java.io.*;
import java.net.*;
import com.google.gson.*;

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

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

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

            // Make the request
            URL url = new URL(apiUrl);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setConnectTimeout(15000);

            BufferedReader in = new BufferedReader(
                new InputStreamReader(conn.getInputStream())
            );
            StringBuilder response = new StringBuilder();
            String line;
            while ((line = in.readLine()) != null) {
                response.append(line);
            }
            in.close();

            // Parse JSON response
            JsonObject json = JsonParser
                .parseString(response.toString())
                .getAsJsonObject();

            // Check validation result
            if ("failed".equals(json.get("status").getAsString())) {
                System.out.println("Invalid email address");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
using System;
using System.Net;
using System.IO;
using System.Web;

class Program
{
    static void Main(string[] args)
    {
        // Set the API key and email to be validated
        string apiKey = "YOUR_API_KEY";
        string email = "example@email.com";
        
        // Build the URL
        string url = "https://api.bulkemailchecker.com/real-time/";
        string postData = "key=" + apiKey + "&email=" 
            + HttpUtility.UrlEncode(email);

        // Create request
        HttpWebRequest request = (HttpWebRequest)
            WebRequest.Create(url);
        request.Method = "POST";
        request.ContentType = "application/x-www-form-urlencoded";

        // Send request
        byte[] postBytes = System.Text.Encoding.ASCII
            .GetBytes(postData);
        request.ContentLength = postBytes.Length;
        
        Stream requestStream = request.GetRequestStream();
        requestStream.Write(postBytes, 0, postBytes.Length);
        requestStream.Close();

        // Get response
        HttpWebResponse response = (HttpWebResponse)
            request.GetResponse();
        string result = new StreamReader(
            response.GetResponseStream()
        ).ReadToEnd();
        
        Console.WriteLine(result);
    }
}

Spreadsheet Integration

Verify emails directly in Google Sheets or Microsoft Excel without writing any code:

Google Sheets

Use the IMPORTXML function to validate emails directly in your spreadsheet:

=IMPORTXML("https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&xml=true&email="&A1;"//BulkEmailChecker")

Important: Copy verification results to a new sheet for saving. Google may re-run IMPORTXML when reopening the spreadsheet, which could reprocess and consume credits. We cannot honor refund requests for credits consumed due to reprocessing.

Microsoft Excel

Add this VBA module via Excel's Developer tab to enable email verification:

' Add this module via Excel's Developer 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

Then use this formula in your cells:

=ImportXML("https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&xml=true&email="&A1;"BulkEmailChecker")

Ready to Get Started?

Create your free account to get started now.