Home
Email Validation Quickstart

API QUICKSTART

Version 2: Getting Started

POSTMAN COLLECTION

To test version 2 of the API in Postman, save the Postman Collection contents as a .json file or you can get the file from our GitHub repository.

In Postman, on the top menu, click on File, then choose Import. Then choose the JSON file you saved or downloaded from GitHub to import it.

Postman Collection JSON file:

The ZeroBounce email validation API operates both in real time and in bulk. If you need to verify emails consistently and would like to save time and automate the process, we recommend using the bulk feature.

The API detects more than 30 types of risky email addresses, prevents them from getting on your list and helps to maintain your email hygiene for a longer period of time. A healthy email list supports your sender reputation and is a cornerstone of good email deliverability.

Activate the API today by installing it on your registration and signup forms, or wherever you collect email addresses online.

Need help getting started with the email validation API? Get in touch with our customer support team. We are here to answer your questions and assist you around the clock, 365 days a year.

Get Credit Balance (v2)

This API will tell you how many credits you have left on your account. It's simple, fast and easy to use.

Here are a few scenarios that businesses will use this API for.

You use our API to validate emails and you need to check within a certain time-frame when your credit balance is too low, so you can make a payment.
You want to track how many email validation credits you're using per your defined time-frame to generate useful statistical information.
You want to automate and integrate information into your application dashboard that shows you your currently remaining credit balance.

Below, you will find the instructions on how to use our API. It's very easy to use and it requires SSL.

GET /V2/GETCREDITS

API URL: https://api.zerobounce.net/v2/getcredits

Below you will find the instructions on how to use our API, it's very easy to use and requires SSL. The API requires that you have an active credit balance and will never consume a credit for any unknown result.

URL Parameters

Parameter
Description
api_key
Your API Key, found in your account.

GET CREDIT BALANCE CODE SAMPLES

This API will tell you how many credits you have left on your account. It's simple, fast and easy to use.

If you want to call the API from your browser to test it, all you have to do is to replace the API KEY with your key:

https://api.zerobounce.net/v2/getcredits?api_key=[replacewithyours]

This API will tell you how many credits you have left on your account.

The API will return these results in a JSON format using the "getcredits" method. credits - The amount of credits you have left in your account for email validations. If a -1 is returned, that means your API Key is invalid.

ENDPOINT RESPONSE

This API will tell you how many credits you have left on your account. It's simple, fast and easy to use.

Successful Response

Error Response

GetCredits V1 and V2 Rate Limits

We allow a maximum of 50.000 requests in 1 hour for the https://api.zerobounce.net/v1/getcredits and https://api.zerobounce.net/v2/getcredits before temporarily blocking for 1 day.

Bad API key requests to https://api.zerobounce.net/v1/getcredits and https://api.zerobounce.net/v2/getcredits 200 times in 1 hour will result in a temporary block for 1 day.

Version 1 of the email validation API will no longer be available on May 1st, 2023. Please make preparations to upgrade to Version 2 at your earliest convenience.

How to use the ZeroBounce API

Validate Emails (v1)

To test out or API without using credits - Please use the emails provided in our sandbox documentation.

The response time for our API is between one second and 70 seconds. Since API's are meant to be fast by nature, we limit the amount of time we spend validating an email address. So if we encounter a slow mail server or a mail server with a greylisting algorithm you will get an unknown result. You can always re-validate those conditions, uploading a file to the bulk email validator.

On average 96-98% of all domains will return in 1 to 5 seconds, there are a handful of domains that run off Postfix/Dovecot that have a 20 second connection time for real-time validations and a very small fractional percentage of other domains that are very slow to respond to SMTP inquiries. All the major ISP will return in 1 to 3 seconds, which is usually the majority of most email distribution.

GET /V1/VALIDATE

API URL: https://bulkapi.zerobounce.net/v1/validate

API URL (With GEO Append): https://bulkapi.zerobounce.net/v1/validatewithip

URL Parameters

Parameter
Description
email
The email address you want to validate
ip_address
The IP Address the email signed up from (Can be blank, but parameter required)
api_key
Your API Key, found in your account

If you want to call the API from your browser to test it, all you need to do is to replace the API KEY with your key:

https://api.zerobounce.net/v1/validatewithip?apikey=replacewithyours&email=valid@example.com&ipAddress=156.124.12.145
or if you don't need GEO Append simply call the validate method.

https://api.zerobounce.net/v1/validate?apikey=replacewithyours&email=valid@example.com

The API will return these results in a JSON format using the "validate" method.

Properties
Description
address
The email address you are validating.
status
[valid, invalid, catch-all, unknown, spamtrap, abuse, do_not_mail]
sub_status
[antispam_system, greylisted, mail_server_temporary_error, forcible_disconnect, mail_server_did_not_respond, timeout_exceeded, failed_smtp_connection, mailbox_quota_exceeded, exception_occurred, possible_traps, role_based, global_suppression, mailbox_not_found, no_dns_entries, failed_syntax_check, possible_typo, unroutable_ip_address, leading_period_removed, does_not_accept_mail, alias_address]
account
The portion of the email address before the "@" symbol.
domain
The portion of the email address after the "@" symbol.
disposable
[true, false] If the email domain is disposable, which are usually temporary email addresses.
toxic
[true, false] These email addresses are known to be abuse, spam, or bot created.
firstname
The first name of the owner of the email when available or [null].
lastname
The last name of the owner of the email when available or [null].
gender
The gender of the owner of the email when available or [null].
creationdate
The creation date of the email when available or [null] [Obsolete].
location
The location of the owner of the email when available or [null] [Obsolete].
processedat
The UTC time the email was validated.

The API will return these additional fields using the "validatewithip" will return these additional additional fields using the validatewithip method:

Properties
Description
city
The city of the IP passed in.
region
The region/state of the IP passed in.
zipcode
The zipcode of the IP passed in.
country
The country of the IP passed in.

VALIDATE EMAILS CODE SAMPLES

ENDPOINT RESPONSE

Successful Response

Successful Response with IP

Error Response

API Validation V1 and V2 Rate Limits

We allow a maximum of 50.000 requests in 10 seconds (validations) for the https://api.zerobounce.net/v1/validate and https://api.zerobounce.net/v2/validate before temporarily blocking for 1 minute.

Bad API key requests to https://api.zerobounce.net/v1/validate and https://api.zerobounce.net/v2/validate 200 times in 1 hour will result in a temporary block for 1 hour.