Real-Time Email Verification & Validation API

A low-latency RESTful API for developers. Integrate SMTP-based email validation into your Python, PHP, or Node.js apps in minutes.

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.

Rate Limits & Concurrency

The Real-time API is architected primarily for transactional email verification at the point of entry (e.g., user registration forms, checkout pages, and lead capture). To ensure low latency and stability for all transactional users, we enforce the following limits based on your account tier:

Account Tier Hourly Quota Max Concurrent Threads
Standard Account
(Default / < 1M Credits) 		1,500 req / hour 1 Thread
Volume Tier 1
(Purchase 1M+ Credits) 		2,500 req / hour 3 Threads
Volume Tier 2
(Purchase 10M+ Credits) 		4,000 req / hour 5 Threads

Processing Bulk or High-Volume Lists?

This endpoint is not optimized for batch processing. For bulk verification, high-concurrency workloads, or verifying millions of records, please use our Unlimited API Endpoint. It offers dedicated infrastructure with 50+ concurrent threads and zero hourly quotas.

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.

Key Data Points: Our JSON response automatically includes Disposable Email Detection, MX Record Enrichment, SMTP Handshake Status, and intelligent Typo Suggestions.

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

SDKs & Integration Scripts

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

PHP Email Verification Script (cURL)

<?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';
}
?>

Python Email Validation (Requests Library)

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')

Node.js Email Verification (Axios)

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);
    });

Go Email Validation Script (net/http)

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")
    }
}

Ruby Email Verification (Net::HTTP)

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

Java Email Validation (HttpURLConnection)

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();
        }
    }
}

C# Email Verification (HttpWebRequest)

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);
    }
}

Google Sheets & Excel Email Validation

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")

Developer FAQ

How should I handle HTTP 429 errors?

An HTTP 429 Too Many Requests response indicates you have exceeded your concurrency limit or hourly quota. Your application should implement an exponential back-off strategy, waiting 1-2 seconds before retrying the request.

What is the maximum concurrency for requests?

Standard accounts are limited to 1 concurrent thread. Volume tiers include higher concurrency limits (3-5 threads). For high-volume concurrency (5-50+ threads), please use our Unlimited API endpoint.

Do you enforce SSL/TLS encryption?

Yes. All API requests must be made over HTTPS (TLS 1.2 or higher). Plain HTTP requests will be rejected to ensure your API key and customer data remain encrypted in transit.

Should I cache verification results?

Yes. We strongly recommend caching results locally for 24 hours when available. This prevents redundant API calls if a user repeatedly submits a form with the same email, saving you credits and reducing latency.

Can I send batch requests to this endpoint?

No. The /real-time/ endpoint is optimized for single, transactional checks. For batch processing (CSV/Lists), please use our Dashboard Bulk Upload tool or the dedicated Unlimited API endpoint.

Does the API perform a full SMTP handshake?

Yes. We go beyond regex and DNS checks. We initiate a real SMTP session (HELO -> MAIL FROM -> RCPT TO) with the target server to confirm the specific mailbox exists, then disconnect before sending data.

How do you handle Server Greylisting?

If a mail server returns a Greylisting error (try again later), we return an Unknown status rather than a false negative. We do not charge credits for Unknown results caused by Greylisting or timeouts.

Do you store the email addresses I verify?

For the Real-time API, data is processed in transient memory and is not stored permanently in our database logs. We are fully GDPR and CCPA compliant and practice data minimization.

Can I use the API in client-side JavaScript?

We recommend calling the API from your backend server to keep your API key secure. If you must use client-side JS, ensure you implement a proxy server to hide your credentials from the browser source.

What response formats are supported?

The API defaults to JSON. You can request XML output by appending &xml=true to your query string. Both formats provide identical data structures and enrichment fields.

Do I need to whitelist your IP addresses?

No. Since you are making outbound requests to our API, whitelisting is generally unnecessary unless your server has strict outbound firewall rules. We utilize dynamic IP pools to ensure maximum uptime and high request reliability.

What is the recommended client-side timeout?

We strongly recommend setting a client-side timeout of 60 seconds. While approximately 95% of requests complete in under 2 seconds, deep SMTP handshakes with legacy infrastructure or servers utilizing Greylisting may require additional time. Our system permits up to 60 seconds before enforcing a timeout to ensure maximum compatibility with slower or private mail servers. If low latency is critical (e.g., checkout forms), we suggest implementing a 3-second "soft timeout" in your UI to maintain a smooth user experience.

Ready to Integrate Email Verification?

Create your account and get your API key in under 60 seconds.

Get Your Free API Key View Pricing
99.7% Accuracy Sub-Second Response PHP, Python, Node.js & More