Email Verification REST API

The NullBounce REST API enables real-time synchronous email validation directly in your registration forms, SaaS checkouts, webhook workers, and backend pipelines.

---

Getting an API Key

1. Sign up ↗ for a free NullBounce account (includes 100 free test credits).
2. Go to the API Keys ↗ page in your dashboard.
3. Click Add API Key, enter a label (e.g. Production Backend), and copy your generated token.

---

Authentication

All API requests must be transmitted over HTTPS. Authenticate by passing your secret key in the Authorization HTTP header with the Token prefix:

Authorization: Token YOUR_API_KEY
Content-Type: application/json
Accept: application/json

---

Rate Limits & Concurrency

• Standard throughput: Up to 10 requests per second (600 requests/minute).
• If your application exceeds this threshold, the API responds with HTTP status code 429 Too Many Requests.
• Need higher concurrency for massive streaming pipelines? Contact support for dedicated throughput provisioning.

---

Security & CORS (Important)

By design, our verification endpoints do not allow cross-origin browser requests (CORS).

Do not call the API from frontend JavaScript

Never put your private API key directly in client-side code (Vue, React, Svelte, or browser scripts). Doing so publicly exposes your token, allowing anyone to consume your credits or view account metadata.

Recommended Architecture:
Make the call from your backend server, cloud function (AWS Lambda, Cloudflare Workers, Next.js API Routes), or serverless action. Your frontend sends the email to your backend, and your backend securely queries NullBounce.

---

1. Validate Email Address

POSThttps://app.nullbounce.com/api/v1/validate/ ↗

Verifies a single email address in real time via RFC syntax audit, DNS/MX check, and live SMTP mailbox handshake.

Request Body

{
  "email": "alex@company.com"
}

Code Examples

cURL

curl --request POST \
  --url https://app.nullbounce.com/api/v1/validate/ \
  --header 'accept: application/json' \
  --header 'authorization: Token YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"email": "alex@company.com"}'

Node.js

const response = await fetch("https://app.nullbounce.com/api/v1/validate/", {
  method: "POST",
  headers: {
    "Authorization": "Token YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({ email: "alex@company.com" })
});

const data = await response.json();
console.log(data);

Python

import requests

url = "https://app.nullbounce.com/api/v1/validate/"
headers = {
    "Authorization": "Token YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {"email": "alex@company.com"}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

PHP

<?php
$ch = curl_init("https://app.nullbounce.com/api/v1/validate/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['email' => 'alex@company.com']));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Token YOUR_API_KEY',
    'Content-Type: application/json',
    'Accept: application/json'
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($result);

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "io"
)

func main() {
  url := "https://app.nullbounce.com/api/v1/validate/"
  payload, _ := json.Marshal(map[string]string{"email": "alex@company.com"})

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
  req.Header.Set("Authorization", "Token YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("Accept", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI("https://app.nullbounce.com/api/v1/validate/")
req = Net::HTTP::Post.new(
  uri,
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Token YOUR_API_KEY'
)
req.body = { email: 'alex@company.com' }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

puts JSON.parse(res.body)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://app.nullbounce.com/api/v1/validate/"))
                .header("Authorization", "Token YOUR_API_KEY")
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString("{\"email\": \"alex@company.com\"}"))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Response Attributes (200 OK)

{
  "email": "alex@company.com",
  "result": "Safe",
  "status_text": "Valid",
  "substatus_text": null,
  "is_disposable": false,
  "is_role": false,
  "is_free": false
}

Parameter	Type	Possible Values	Description
email	String	Email string	The verified address normalized.
result	String	Safe, Invalid, Risky, Unknown	Final high-level verdict. Use this for instant binary accept/reject decisions.
status_text	String	Valid, Invalid, Catch-All, Unknown	Technical deliverability state from the MTA handshake.
substatus_text	String / null	Mailbox Not Found, No Smtp, etc.	Granular rejection reason if deliverability failed.
is_disposable	Boolean	true / false	true if domain belongs to a burner email service (e.g. Mailinator).
is_role	Boolean	true / false	true for departmental inboxes (info@, support@).
is_free	Boolean	true / false	true for consumer webmail (Gmail, Yahoo, Outlook.com).

Detailed Status Meanings

Review our complete Understanding Validation Results guide for an in-depth breakdown of all deliverability states and sub-statuses.

---

Live API Tester

You can test a live validation request right here (enter your API key and an email):

Your API-Key

Email to validate

Validate Email

---

2. Check Credit Balance

GEThttps://app.nullbounce.com/api/v1/balance/ ↗

Returns the total remaining credit balance for your account.

Request

curl --request GET \
  --url https://app.nullbounce.com/api/v1/balance/ \
  --header 'authorization: Token YOUR_API_KEY'

Response (200 OK)

The response body contains an integer representing available verification credits:

432351

Live Balance Tester

Your API-Key

Check Balance

---

HTTP Error Codes

Status Code	Reason	Meaning
200 OK	Success	The request succeeded and returned a validation payload.
400 Bad Request	Invalid Input	Malformed JSON or missing required email parameter.
402 Payment Required	No Credits	Your account credit balance is depleted. Top up in Plans & Upgrade ↗.
403 Forbidden	Invalid Token	The API token is invalid, revoked, or missing the Token prefix.
415 Unsupported Type	Wrong Headers	Request header Content-Type must be application/json.
429 Too Many Requests	Rate Limit	You exceeded 10 requests/second. Implement exponential backoff.
500 Server Error	Internal Error	Unexpected server failure. Retry the request with backoff.

---

No-Code Automations (n8n)

Automating without code? You can connect NullBounce directly to your CRM, web forms, and Google Sheets using our official verified community node in n8n.
👉 Explore the n8n Integration Guide