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.