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 in which businesses should use this API:
- When using our API to validate emails, periodically check your credit balance to avoid service interruptions caused by insufficient credits.
- Track how many email validationⓘ credits you're using per your defined time frame to generate useful statistical information.
- Automate and integrate information into your application dashboard that shows you your current 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 DEFAULT URL: https://api.zerobounce.net/v2/getcredits
API U.S.A. URL*: https://api-us.zerobounce.net/v2/getcredits
API EU URL: https://api-eu.zerobounce.net/v2/getcredits
*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.
Below you will find the instructions on how to use our API. It's very easy to use and requires SSL. The API requires an active credit balance and will never consume a credit for any unknown result.
URL Parameters
- ParameterDescription
- api_keyYour API Key, found in your account.
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.
If you want to call the API from your browser to test it, all you have to do is replace the API KEY with your key:
API DEFAULT URL: https://api.zerobounce.net/v2/getcredits?api_key=[replacewithyours]
API U.S.A. URL*: https://api-us.zerobounce.net/v2/getcredits?api_key=[replacewithyours]
API EU URL: https://api-eu.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’ is the value that shows the number of credits left in your account for email validations. If a -1 is returned, that means your API Key is invalid.
*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.
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
{"Credits":2375323}Error Response
{"Credits":-1}GetCredits V2 Rate Limits
We allow a maximum of 80,000 requests in 1 hour before temporarily blocking for 1 day for the following endpoints:
- https://api.zerobounce.net/v2/getcredits
- https://api-us.zerobounce.net/v2/getcredits
- https://api-eu.zerobounce.net/v2/getcredits
Bad API key requests (200 times in 1 hour) to the following endpoints will result in a temporary block for 1 day:
- https://api.zerobounce.net/v2/getcredits
- https://api-us.zerobounce.net/v2/getcredits
- https://api-eu.zerobounce.net/v2/getcredits
*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.
Get API Usage (v2)
GET /v2/getapiusage
API DEFAULT URL: https://api.zerobounce.net/v2/getapiusage
API U.S.A. URL*: https://api-us.zerobounce.net/v2/getapiusage
API EU URL: https://api-eu.zerobounce.net/v2/getapiusage
*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.
URL Parameters
- ParameterDescription
- api_keyYour API Key can be found in your account.
- start_dateThe start date of when you want to view API usage. (format: yyyy-mm-dd)
- end_dateThe end date of when you want to view API usage. (format: yyyy-mm-dd)
https://api.zerobounce.net/v2/getapiusage?api_key=your-api-key&start_date=2018-01-01&end_date=2019-12-12
https://api-us.zerobounce.net/v2/getapiusage?api_key=your-api-key&start_date=2018-01-01&end_date=2019-12-12
https://api-eu.zerobounce.net/v2/getapiusage?api_key=your-api-key&start_date=2018-01-01&end_date=2019-12-12
The API will return these results in a JSON format using the "getapiusage" method.
The API will return these results in a JSON format using the "getapiusage" method.
- ParameterDescription
- totalTotal number of times the API has been called
- status_validTotal valid email addresses returned by the API
- status_invalidTotal invalid email addresses returned by the API
- status_catch_allTotal catch-all email addresses returned by the API
- status_do_not_mailTotal do not mail email addresses returned by the API
- status_spamtrapTotal spamtrap email addresses returned by the API
- status_unknownTotal unknown email addresses returned by the API
- sub_status_toxicTotal number of times the API has a sub status of "toxic"
- sub_status_disposableTotal number of times the API has a sub status of "disposable"
- sub_status_role_basedTotal number of times the API has a sub status of "role_based"
- sub_status_possible_trapTotal number of times the API has a sub status of "possible_trap"
- sub_status_global_suppressionTotal number of times the API has a sub status of "global_suppression"
- sub_status_timeout_exceededTotal number of times the API has a sub status of "timeout_exceeded"
- sub_status_mail_server_temporary_errorTotal number of times the API has a sub status of "mail_server_temporary_error"
- sub_status_mail_server_did_not_respondTotal number of times the API has a sub status of "mail_server_did_not_respond"
- sub_status_greylistedTotal number of times the API has a sub status of "greylisted"
- sub_status_antispam_systemTotal number of times the API has a sub status of "antispam_system"
- sub_status_does_not_accept_mailTotal number of times the API has a sub status of "does_not_accept_mail"
- sub_status_exception_occurredTotal number of times the API has a sub status of "exception_occurred"
- sub_status_failed_syntax_checkTotal number of times the API has a sub status of "failed_syntax_check"
- sub_status_mailbox_not_foundTotal number of times the API has a sub status of "mailbox_not_found"
- sub_status_unroutable_ip_addressTotal number of times the API has a sub status of "unroutable_ip_address"
- sub_status_possible_typoTotal number of times the API has a sub status of "possible_typo"
- sub_status_no_dns_entriesTotal number of times the API has a sub status of "no_dns_entries"
- sub_status_role_based_catch_allTotal role based catch alls the API has a sub status of "role_based_catch_all"
- sub_status_mailbox_quota_exceededTotal number of times the API has a sub status of "mailbox_quota_exceeded"
- sub_status_forcible_disconnectTotal forcible disconnects the API has a sub status of "forcible_disconnect"
- sub_status_failed_smtp_connectionTotal failed SMTP connections the API has a sub status of "failed_smtp_connection"
- sub_status_mx_forwardTotal number times the API has a sub status "mx_forward"
- start_dateStart date of query. (format: yyyy/mm/dd)
- end_dateEnd date of query. (format: yyyy/mm/dd)
GET API USAGE CODE SAMPLES
ENDPOINT RESPONSE
Successful Response
{
"total": 120,
"status_valid": 17,
"status_invalid": 69,
"status_catch_all": 9,
"status_do_not_mail": 16,
"status_spamtrap": 0,
"status_unknown": 6,
"sub_status_toxic": 0,
"sub_status_disposable": 1,
"sub_status_role_based": 1,
"sub_status_possible_trap": 0,
"sub_status_global_suppression": 14,
"sub_status_timeout_exceeded": 0,
"sub_status_mail_server_temporary_error": 0,
"sub_status_mail_server_did_not_respond": 0,
"sub_status_greylisted": 6,
"sub_status_antispam_system": 0,
"sub_status_does_not_accept_mail": 27,
"sub_status_exception_occurred": 0,
"sub_status_failed_syntax_check": 20,
"sub_status_mailbox_not_found": 12,
"sub_status_unroutable_ip_address": 0,
"sub_status_possible_typo": 0,
"sub_status_no_dns_entries": 10,
"sub_status_role_based_catch_all": 0,
"sub_status_mailbox_quota_exceeded": 0,
"sub_status_forcible_disconnect": 0,
"sub_status_failed_smtp_connection": 0,
"sub_status_leading_period_removed": 0,
"sub_status_alias_address": 2,
"sub_status_mx_forward": 0,
"sub_status_alternate": 0,
"sub_status_blocked": 0,
"sub_status_allowed": 0,
"start_date": "1/1/2023",
"end_date": "1/30/2024"
}Error Response - API Key
{"error":"Invalid API Key"}Error Response - Date
{"error":"Invalid Date"}GetApiUsage V2 Rate Limits
Bad requests (200 times in 1 hour) to the following endpoints will result in a temporary block for 1 hour:
- https://api.zerobounce$.net/v2/getapiusage
- https://api-us.zerobounce.net/v2/getapiusage
- https://api-eu.zerobounce$.net/v2/getapiusage
*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.
Single Email Validator - Real time (v2)
Below are the instructions for our single email validator API, which requires SSL. The API also requires that you have an active credit balance and will never consume a credit for any unknown result. This endpoint can be called asynchronously and is not currently rate-limited.
To test out our API without using credits, please use the emails provided in our Sandbox Mode (v2).
The response time for our API is between one second and 30 seconds. Since APIs are meant to be fast by nature, we limit the amount of time we spend validating an email address. If we encounter a slow mail server or a mail server with a greylisting algorithm, you will get an unknown result. You can always revalidate those conditions by 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 on Postfix/Dovecot, which have a 20-second connection time for real-time validations, and a very small fraction of other domains that are slow to respond to SMTP inquiries. All major ISPs will respond in 1 to 3 seconds, which is typically the majority of email distribution.
- GET /V2/VALIDATE
API DEFAULT URL: https://api.zerobounce.net/v2/validate
API U.S.A. URL*: https://api-us.zerobounce.net/v2/validate
API EU URL: https://api-eu.zerobounce.net/v2/validate
Below are the instructions for our single email validator API, which requires SSL. The API also requires that you have an active credit balance and will never consume a credit for any unknown result. This endpoint can be called asynchronously and is not currently rate-limited.
*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.
URL Parameters
- ParameterDescription
- emailThe email address you want to validate
- ip_addressThe IP Address the email signed up from (Can be blank, or can be missing entirely)
- api_keyYour API Key, found in your account.
- timeoutThe duration (3 - 60 seconds) allowed for the validation. If met, the API will return unknown / greylisted. (optional parameter)
- activity_data[true/false] +Activity Data information will be appended to the validation result. (optional parameter)
Learn more about Activity Data. - verify_plus[true/false] +If set to ‘true,’ Verify+ validation method will be used to get the validation result. It overrides the account settings made regarding Verify+. (optional parameter)
Learn more about Verify+
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/v2/validate?api_key=replacewithyours&email=valid@example.com&ip_address=156.124.12.145
https://api-us.zerobounce.net/v2/validate?api_key=replacewithyours&email=valid@example.com&ip_address=156.124.12.145
https://api-eu.zerobounce.net/v2/validate?api_key=replacewithyours&email=valid@example.com&ip_address=156.124.12.145
TO VERIFY AN EMAIL ADDRESS, USE THE FOLLOWING CODES FOR THE FOLLOWING LANGUAGES:
Successful Response
{
"address":"flowerjill@aol.com",
"status":"valid",
"sub_status":"",
"free_email":true,
"did_you_mean":null,
"account":"flowerjill",
"domain":"aol.com",
"domain_age_days": "8426",
"active_in_days": "365",
"smtp_provider":"yahoo",
"mx_record":"mx-aol.mail.gm0.yahoodns.net",
"mx_found": "true",
"firstname":"Jill",
"lastname":"Stein",
"gender":"female",
"country":"United States",
"region":"Florida",
"city":"West Palm Beach",
"zipcode":"33401",
"processed_at":"2017-04-01 02:48:02.592"
}
Error Response
{"error":"Invalid API Key or your account ran out of credits"}
// Failure response sample using the API with either method Get
THE API WILL RETURN THESE RESULTS IN A JSON FORMAT USING THE "VALIDATE" METHOD.
JSON Properties
- PropertiesDescription
- addressThe email address you are validating.
- status[valid, invalid, catch-all, unknown, spamtrap, abuse, do_not_mail]
- sub_status[alternate, 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_trap, 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, role_based_catch_all, disposable, toxic, accept_all, gold]
- accountThe portion of the email address before the "@" symbol.
- domainThe portion of the email address after the "@" symbol.
- did_you_meanSuggestive Fix for an email typo
- domain_age_daysAge of the email domain in days or [null].
- active_in_daysThe last activity date that is less than [30/60/90/180/365/365+]
- free_email[true/false] If the email comes from a free provider.
- mx_found[true/false] Does the domain have an MX record.
- mx_recordThe preferred MX record of the domain
- smtp_providerThe SMTP Provider of the email or [null] [BETA].
- firstnameThe first name of the owner of the email when available or [null].
- lastnameThe last name of the owner of the email when available or [null].
- genderThe gender of the owner of the email when available or [null].
- cityThe city of the IP passed in or [null]
- regionThe region/state of the IP passed in or [null]
- zipcodeThe zipcode of the IP passed in or [null]
- countryThe country of the IP passed in or [null]
- processed_atThe UTC time the email was validated.
API Validation V2 Rate Limits
We allow a maximum of 80,000 requests in 10 seconds (validations) for the following endpoints:
- https://api.zerobounce.net/v2/validate
- https://api-us.zerobounce.net/v2/validate
- https://api-eu.zerobounce.net/v2/validate
Exceeding this limit will result in a temporary block for 1 minute.
Bad API key requests (200 times in 1 hour) to the following endpoints will result in a temporary block for 1 hour:
- https://api.zerobounce.net/v2/validate
- https://api-us.zerobounce.net/v2/validate
- https://api-eu.zerobounce.net/v2/validate
*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.
If you require an increase beyond the default rate limits, please contact our support team to discuss your needs.
Greylist API Processing Documentation
The Greylist Validation feature allows you to validate greylisted domains directly with the ZeroBounce API. Whenever you receive an unknown/greylisted result during validation, the email will be reprocessed to provide a result.
There are two options to enable and use this functionality:
- Pickup
To use the Pickup option, add the following parameter to the normal /v2/validate call:
- ParameterDescription
- greylist_processingEnable greylisting processing.
Possible values: true/false
You can reattempt the validation request after 30 minutes by including the new parameter to obtain a result.
Any duplicate requests will return an error message suggesting to retry later.
{"Message": "Greylist validation still in progress. Please try again later."}
ZeroBounce deducts credits after a successful pickup.
- Webhook
To create a webhook, add the following two parameters to the normal /v2/validate call:
- ParameterDescription
- greylist_processingEnable greylisting processing.
- Possible values: true/false
- callback_urlDestination URL for greylist validation results
For webhooks, duplicate requests are allowed. If you make the same request twice, you can expect two callbacks. Each callback will be charged.
When the greylist processing is complete, we will send an HTTP request to your callback_url with the result.
ZeroBounce deducts credits upon a successful callback to the callback_url.
We will consider the callback successful if your endpoint response has status code 200 or 201.
Website Availability and WHOIS Checker
The Website Availability and WHOIS Checker enhances the email validationⓘ process by including website availability checks and WHOIS data retrieval for domains. You can control the new functionality via the domain_info parameter. It will influence the validation response by adding or omitting specific fields based on their value.
- ParameterPossible valuesDescription
- domain_infoTrue/FalseIndicates whether the website availability and WHOIS data should be included in the validation response.
Response Fields
When the domain_info parameter is set to true, the response will include the additional fields ‘domain_website_exists’ and ‘domain_registrant_company_name.’ If the ‘domain_info’ parameter is false or not provided, these fields will not appear in the response.
- New propertiesPossible valuesDescription
- domain_website_existsTrue/False/uncheckedIndicates if the website for the domain is accessible
- domain_registrant_company_nameRegistrant info not found/Company LLC/uncheckedUnchecked: the response returns too early.
Descriptions include: failed_syntax_check, no_dns_entries, exception_occurred, greylisted
Registrant info not found: registrant not found for the domain
Company LLC: The company which holds the domain name
Usage Notes
To use the Website Availability and WHOIS Checker feature, take care to implement the following:
- To enable the new website availability and WHOIS checks, ensure the domain_info parameter is set to true in your validation requests.
- If these checks are not needed, omit the domain_info parameter or set it to false to reduce processing time and exclude unnecessary fields from the response.
If you have any questions or encounter difficulties in using the WHOIS checker, reach out to our live chat customer support - available 24/7.
Batch Email Validator - Real time (v2)
This endpoint allows you to send us batches up to 200 emails at a time. It is rate limited to 5 uses per minute, if you exceed the rate limit, you will be blocked for 10 minutes. If you're looking to do single email validations, please use our single email validator endpoint.
If you're looking to upload files with emails greater than 200 at a time without any rate limiting restrictions, please use our ,Bulk File Management Endpoints which also includes anti-greylisting as an added benefit.
This endpoint can take up to 70 seconds to return the results of the entire batch. We currently don't have an SDK for this endpoint, but SDK's are available for our other endpoints.
- POST /V2/VALIDATEBATCH
API URL:
- api.zerobounce.net/v2/validatebatch
- api-us.zerobounce.net/v2/validatebatch
- api-eu.zerobounce.net/v2/validatebatch
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
- ParameterDescription
- api_keyYour API Key
- email_batch[Array of Objects], Format:{"email_address": "valid@example.com","ip_address": "1.1.1.1"}
- timeoutThe duration (10 - 120 seconds) allowed for the validation. If met, the API will return unknown / greylisted. (optional parameter)
- activity_data[true/false] If set to ‘true,’ Activity Data information will be appended to the validation result. (optional parameter)
Learn more about Activity Data. - verify_plus[true/false] If set to ‘true,’ Verify+ validation method will be used to get the validation result. It overrides the account settings made regarding Verify+. (optional parameter)
Learn more about Verify+.
EXAMPLE POST REQUEST
{
"api_key":"Your API Key",
"email_batch":[
{"email_address": "valid@example.com","ip_address": "1.1.1.1"},
{"email_address": "invalid@example.com","ip_address": "1.1.1.1"},
{"email_address": "disposable@example.com","ip_address": null}
],
"activity_data" : true,
"verify_plus": true
}
TO USE THIS ENDPOINT, USE THE CODE EXAMPLES BELOW FOR THE DESIRED LANGUAGE:
Successful Response
{
"email_batch": [
{
"address": "valid@example.com",
"status": "valid",
"sub_status": "",
"free_email": false,
"did_you_mean": null,
"account": null,
"domain": null,
"domain_age_days": "9692",
"active_in_days": "365",
"smtp_provider": "example",
"mx_found": "true",
"mx_record": "mx.example.com",
"firstname": "zero",
"lastname": "bounce",
"gender": "male",
"country": null,
"region": null,
"city": null,
"zipcode": null,
"processed_at": "2020-09-17 17:43:11.829"
},
{
"address": "invalid@example.com",
"status": "invalid",
"sub_status": "mailbox_not_found",
"free_email": false,
"did_you_mean": null,
"account": null,
"domain": null,
"domain_age_days": "9692",
"active_in_days": "365",
"smtp_provider": "example",
"mx_found": "true",
"mx_record": "mx.example.com",
"firstname": "zero",
"lastname": "bounce",
"gender": "male",
"country": null,
"region": null,
"city": null,
"zipcode": null,
"processed_at": "2020-09-17 17:43:11.830"
},
{
"address": "disposable@example.com",
"status": "do_not_mail",
"sub_status": "disposable",
"free_email": false,
"did_you_mean": null,
"account": null,
"domain": null,
"domain_age_days": "9692",
"active_in_days": "365",
"smtp_provider": "example",
"mx_found": "true",
"mx_record": "mx.example.com",
"firstname": "zero",
"lastname": "bounce",
"gender": "male",
"country": null,
"region": null,
"city": null,
"zipcode": null,
"processed_at": "2020-09-17 17:43:11.830"
}
],
"errors": []
}
Error Response
{
"email_batch": [],
"errors": [
{
"error": "Invalid API Key or your account ran out of credits",
"email_address": "all"
}
]
}
THE API WILL RETURN A JSON OBJECT WITH 2 ARRAY VALUES, "EMAIL_BATCH" AND "ERRORS" USING THE "BATCHVALIDATE" METHOD.
The email_batch property will be an array of validated results and the errors array will be an array of errors encountered during batch vaidation, if any.
JSON Properties
- PropertiesDescription
- email_batch[Array] An Array of validated emails
- errors[Array] An Array of errors encuontered, if any
email_batch Properties
- PropertiesDescription
- addressThe email address you are validating.
- status[valid, invalid, catch-all, unknown, spamtrap, abuse, do_not_mail]
- sub_status[alternate, 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_trap, 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, role_based_catch_all, disposable, toxic]
- accountThe portion of the email address before the "@" symbol.
- domainThe portion of the email address after the "@" symbol.
- did_you_meanSuggestive Fix for an email typo
- domain_age_daysAge of the email domain in days or [null].
- active_in_daysLast activity date that is less than [30/60/90/180/365/365+]
- free_email[true/false] If the email comes from a free provider.
- mx_found[true/false] Does the domain have an MX record.
- mx_recordThe preferred MX record of the domain
- smtp_providerThe SMTP Provider of the email or [null] [BETA].
- firstnameThe first name of the owner of the email when available or [null].
- lastnameThe last name of the owner of the email when available or [null].
- genderThe gender of the owner of the email when available or [null].
- cityThe city of the IP passed in or [null]
- regionThe region/state of the IP passed in or [null]
- zipcodeThe zipcode of the IP passed in or [null]
- countryThe country of the IP passed in or [null]
- processed_atThe UTC time the email was validated.
Custom Filter Rules for AllowList and BlockList
Email validationⓘ allowlists and blocklists
The ZeroBounce email validator allows users to create custom filters to allow or block emails, email domains, specific mx records or TLD (Top Level Domain). Making these allowlists and blocklists will enable you to customize your email validation experience for your needs.
Creating these custom filters simplifies email validationⓘ by automatically allowing or blocking values and improve email list validation efficiency.
GETTING STARTED
To create your email validationⓘ rules, sign in to your ZeroBounce account and visit your account settings.
- Go to Account.
- Click on Email Validation Rules or scroll down to “New Email Validation Rule.”
ADDING AN “ALLOW” OR “BLOCK” RULE
In the settings, you’ll find two mandatory dropdown fields. You must select a value for both to create a new rule successfully.
Important Note - Before you begin, know that more specific rules will take priority over less specific ones.
For example:
Rule 1: Block - Email - test@example.com
Overrides
Rule 2: Allow - Domain - example.com
- Under Rule, select Allow or Block.
Allow will create an exception for all emails, email domains, mx records or tld that match the value entered.Block will ensure that all emails, email domains, mx records or tld that match the value entered are automatically filtered and blocked from email validation. - Under Target, select a value to allow or block: “domain”, “mx record”, "tld" or “email”.
- In the third mandatory field, Value, enter the exact value for the target selected during step two.
Example domain value - example.com.Example mx record value - long.string.example.comExample tld value - .comExample email value - test@example.com - Ensure that your value is correct. Then, click Create.Your complete list of custom rules will appear below under “Your Email Validationⓘ Rules.”
MODIFY OR DELETE CUSTOM RULES
If you need to edit an existing rule, you can do so by locating the rule in your list and clicking Modify.
Doing so will prompt your rule to appear in the customization field above. You can then switch your rule from Allow to Block or vice versa.
If you wish to edit the Target or Value, delete the rule from your list and create a new one. You can do this by clicking Delete. A confirmation screen will appear to help prevent accidental rule changes on your account.
Then, you may create a new rule that contains the proper Rule, Target and Value.
If you experience issues creating your custom allow or block rules, please contact the ZeroBounce support team - available 24/7 via phone, email or live chat.
Sandbox Mode (v2)
To help you test every scenario of status and sub_status codes with the API, we put together a list of emails that will return specific results when used with the API for testing purposes. Testing with these emails will not use any of your credits.
In addition, we also provide an IP address to test with to get GEO-Location results.
You will still need to use your API KEY with these test email addresses.
- disposable@example.com
- invalid@example.com
- valid@example.com
- toxic@example.com
- donotmail@example.com
- spamtrap@example.com
- abuse@example.com
- unknown@example.com
- catch_all@example.com
- antispam_system@example.com
- does_not_accept_mail@example.com
- exception_occurred@example.com
- failed_smtp_connection@example.com
- failed_syntax_check@example.com
- forcible_disconnect@example.com
- global_suppression@example.com
- greylisted@example.com
- leading_period_removed@example.com
- mail_server_did_not_respond@example.com
- mail_server_temporary_error@example.com
- mailbox_quota_exceeded@example.com
- mailbox_not_found@example.com
- no_dns_entries@example.com
- possible_trap@example.com
- possible_typo@example.com
- role_based@example.com
- timeout_exceeded@example.com
- unroutable_ip_address@example.com
- free_email@example.com
- role_based_catch_all@example.com
You can use this IP to test the GEO Location in the API.
99.110.204.1
Please view our status codes documentation to learn more about each status.
Status Codes (v2)
DELIVERABILITY STATUS EXPLANATION
- valid - These are emails that we determined to be valid and safe to email to, they will have a very low bounce rate of under 2%. If you receive bounces it can be because your IP might be blacklisted where our IP was not. Sometimes the email accounts exist, but they are only accepting mail from people in their contact lists. Sometimes you will get throttle on number of emails you can send to a specific domain per hour. It's important to look at the SMTP Bounce codes to determine why.
- invalid - These are emails that we determined to be invalid, please delete them from your mailing list.
- catch-all - These emails are impossible to validate without sending a real email and waiting for a bounce. The term Catch-all means that the email server tells you that the email is valid, whether it's valid or invalid. If you want to email these addresses, I suggest you segment them into a catch-all group and know that some of these will most likely bounce.
- spamtrap - These emails are believed to be spamtraps and should not be mailed. We have technology in place to determine if certain emails should be classified as spamtrap. We don't know all the spamtrap email addresses, but we do know a lot of them. Read our Guide to Spam Traps to learn more.
- abuse- These emails are of people who are known to click the abuse links in emails, hence abusers or complainers. We recommend not emailing these addresses.
- do_not_mail - These emails are of companies, role-based, or people you just want to avoid emailing to. They are broken down into 6 sub-categories "disposable","toxic", "role_based", "role_based_catch_all", "global_suppression" and "possible_trap". Examine this file and determine if you want to email these address. They are valid email addresses, but shouldn't be mailed in most cases.
- unknown - These emails we weren't able to validate for one reason or another. Typical cases are "Their mail server was down" or "the anti-spam system is blocking us". In most cases, 80% unknowns are invalid/bad email addresses. We have the lowest "unknowns" of any email validator, and we don't make this statement lightly. We paid and tested email lists at over 50 different validation companies to compare results. If you do encounter a large number of unknowns, please submit those for re-validation. Remember you are not charged for unknown results, credits will be credited back. If you still have a large number, contact us and we will take a look and verify.
We also provide a sub_status code to help explain some of the unknown and invalid results, not all unknowns and invalids will have sub_status codes.
SUB STATUS EXPLANATION
- alias_address- (valid) These emails addresses act as forwarders/aliases and are not real inboxes, for example if you send an email to forward@example.com and then the email is forwarded to realinbox@example.com. It's a valid email address and you can send to them, it's just a little more information about the email address. We can sometimes detect alias email addresses and when we do we let you know.
- antispam_system- (unknown) These emails have anti-spam systems deployed that are preventing us from validating these emails. You can submit these to us through the contact us screen to look into.
- does_not_accept_mail- (invalid) These domains only send mail and don't accept it.
- exception_occurred- (unknown) These emails caused an exception when validating. If this happens repeatedly, please let us know.
- failed_smtp_connection- (unknown) These emails belong to a mail server that won't allow an SMTP connection. Most of the time, these emails will end up being invalid.
- failed_syntax_check- (Invalid) Emails that fail RFC syntax protocols
- forcible_disconnect- (Unknown) These emails belong to a mail server that disconnects immediately upon connecting. Most of the time, these emails will end up being invalid.
- global_suppression- (do_not_mail) These emails are found in many popular global suppression lists (GSL), they consist of known ISP complainers, direct complainers, purchased addresses, domains that don't send mail, and known litigators.
- greylisted- (Unknown) Emails where we are temporarily unable to validate them. A lot of times if you resubmit these emails they will validate on a second pass.
- leading_period_removed- (valid) If a valid gmail.com email address starts with a period '.' we will remove it, so the email address is compatible with all mailing systems.
- mail_server_did_not_respond- (unknown) These emails belong to a mail server that is returning a temporary error. Most of the time, these emails will end up being invalid.
- mailbox_quota_exceeded- (invalid) These emails exceeded their space quota and are not accepting emails. These emails are marked invalid.
- mailbox_not_found- (invalid) These emails addresses are valid in syntax, but do not exist. These emails are marked invalid.
- no_dns_entries- (invalid) These emails are valid in syntax, but the domain doesn't have any records in DNS or have incomplete DNS Records. Therefore, mail programs will be unable to or have difficulty sending to them. These emails are marked invalid.
- possible_trap- (do_not_mail) These emails contain keywords that might correlate to possible spam traps like spam@ or @spamtrap.com. Examine these before deciding to send emails to them or not.
- possible_typo- (invalid) These are emails of commonly misspelled popular domains. These emails are marked invalid.
- role_based- (do_not_mail) These emails belong to a position or a group of people, like sales@ info@ and contact@. Role-based emails have a strong correlation to people reporting mails sent to them as spam and abuse.
- role_based_catch_all- (do_not_mail) These emails are role-based and also belong to a catch_all domain.
- timeout_exceeded- (unknown) These emails belong to a mail server that is responding extremely slow. Most of the time, these emails will end up being invalid.
- unroutable_ip_address- (invalid) These emails domains point to an un-routable IP address, these are marked invalid.
- disposable- (do_not_mail) These are temporary emails created for the sole purpose to sign up to websites without giving their real email address. These emails are short lived from 15 minutes to around 6 months. There is only 2 values (True and False). If you have valid emails with this flag set to TRUE, you shouldn't email them.
- toxic- (valid) These emails are valid, but they are likely to be secondary addresses for the users. Alternate emails are often used to sign up for accounts but otherwise do not see much engagement. As opposed to primary email addresses, which would look more formal, alternate emails will usually contain numbers or more special characters, e.g 12j.o-hn2023@gmail.com. Identifying alternate email addresses allows for better email list segmentation. Users with formal emails are more likely to engage with your content.
- accept_all - (valid) These addresses belong to domains on the ZeroBounce accept_all list. The destination mail server is configured to accept any recipient and never issue an SMTP bounce (e.g., amazon.com, zerobounce.net). Because long-term sending data shows an exceptionally low bounce rate (< 2 %), we treat them as Valid while flagging them with the accept_all sub-status so you can segmentor monitor engagement if desired.
- role_based_accept_all - (valid) These emails are role-based, belong to a catch_all domain and belong to domains on the ZeroBounce accept_all list.
We also provide other additional fields that you should take into consideration before emailing. If any of your valid emails have the disposable or toxic flag set to true, we recommend that you don't email them.
OTHER FIELDS
- free_email- [true/false] If the email comes from a free provider.
- mx_found- [true/false] Does the domain have an MX record.
- mx_record- The preferred MX record of the domain.
- smtp_provider- The SMTP Provider of the email or [null] (BETA).
V2 Changes
These are the items that changed between v1 and v2.
- Disposable and Toxic emails have been moved under the do_not_mail status with the appropriate sub_status (toxic, disposable)
- The "DoNotMail" status was changed to "do_not_mail"
- All statuses are now lowercase, instead of mixed case.
- We added a free_email property to indicate if the email domain is a free email provider can be used for [fraud prevention].
- We added a domain_age_days property, to let you know how old the domain is [fraud prevention].
- We added the smtp_provider property for the email domain, this feature is in beta.
- We added the mx_found property, to let you know if the domain has an MX record
- We added the mx_record property, to tell you the preferred MX record of the domain.
- We added the did_you_mean property, which will be populated if a typo is detected with a suggested correction.
- apiKey property was changed to api_key
- IPAddress property was changed to ip_address
- The validatewithip method was removed, it's now part of the validate method
- The location property was removed (wasn't being used)
- The creation_date property was removed (wasn't being used)
- processedat property is now processed_at
- We added a new sub_status called "role_based_catch_all"
- We added three new API, sendfile, filestatus, and getfile for bulk email validationⓘ.
- We added a new sub_status called "role_based_accept_all"
File Management Overview (v2)
Recommended API Usage
![[object Object], A I API Documentation](/_next/image?url=%2Fassets_next%2Fdocs%2Femail-validation-api%2Fapi_flow2.webp&w=2048&q=75)
Recommended File management endpoint usage
Send File (v2)
Have you activated our email validationⓘ API and would like to send your file?
The sendfile API allows you to send a file for bulk email validationⓘ. The content type needs to be multipart/form-data. Please refer to the C# example for details.
There is no restriction on file size, number of emails, or number of files you can submit using this endpoint. As long as you have the credits in your account to cover the number of emails submitted in the file, your file will be accepted.
Consider activating AutoPay in your ZeroBounce account and ensure you never run out of credits.
POST /V2/SENDFILE
API URL: https://bulkapi.zerobounce.net/v2/sendfile
URL Parameters
- ParameterDescription
- filecsv or txt file. Byte array contents for the submitted file. The content's header is type of "text/csv".
- api_keyYour API Key, found in your account. (Required)
- return_urlThe URL will be used to call back when the validation is completed. (Optional)
- email_address_columnThe column index of the email address in the file. Index starts from 1. (Required)
- first_name_columnThe column index of the first name column. (Optional)
- last_name_columnThe column index of the last name column. (Optional)
- gender_columnThe column index of the gender column. (Optional)
- ip_address_columnThe IP Address the email signed up from. (Optional)
- has_header_rowIf the first row from the submitted file is a header row. true or false (Optional)
- remove_duplicateIf you want the system to remove duplicate emails (true or false, default is true). Please note that if we remove more than 50% of the lines because of duplicates (parameter is true), system will return a 400 bad request error as a safety net to let you know that more than 50% of the file has been modified.
- allow_phase_2If Verify+ is enabled and there are more than 10 catch-all emails in the initial validation, setting this parameter to true will trigger the catch-all emails validation (phase 2) after the initial validation. Possible values are true or false (default is false). (Optional)
If a return_url was specified in the Multipart Form Data during the send file request, we will POST the following data to the URL when the validation process is complete.
{
"file_id": "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff",
"file_name": "Your file name.csv",
"upload_date": "2023-04-28T15:25:41Z"
}
SEND FILE CODE SAMPLES
ENDPOINT RESPONSE
Successful Response
{
"success": true,
"message": "File Accepted",
"file_name": "Your file name.csv",
"file_id": "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff"
}
Error Response
{
"success": false,
"error_message": "Error messages"
}The ZeroBounce email validationⓘ API is one of the most effective tools to keep bad data out of your list. The API can detect and reject more than 30 types of problematic email addresses, thus helping to maintain your email hygiene.
Need help sending your file for bulk email validationⓘ? Let us know – our team is available around the clock to assist you.
File Status (v2)
Would you like to check the status of a file you submitted for email validationⓘ via the ZeroBounce API? You can do that at any time – please see our instructions below.
The filestatus API returns the file processing status for the file that has been submitted using the sendfile API. Please refer to the C# example for details.
GET /V2/FILESTATUS
API URL: https://bulkapi.zerobounce.net/v2/filestatus
URL Parameters
- ParameterDescription
- api_keyYour API Key, found in your account.
- file_idThe returned file ID when calling sendfile API.
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 unique API key and the FILE ID with the returned file ID from sendfile API:
https://bulkapi.zerobounce.net/v2/filestatus?api_key=[replacewithyours]&file_id=[replacewithyours]
FILE STATUS CODE SAMPLES
Below you can find samples of both successful and error responses.
ENDPOINT RESPONSE
Successful Response
{
"success": true,
"file_id": "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff",
"file_name": "Your file name.csv",
"upload_date": "2023-04-28T15:25:41Z",
"file_status": "Complete",
"complete_percentage": "100%",
"return_url": "Your return URL if provided when calling sendfile API"
}
Error Response
{
"success": false,
"error_message": "Error messages"
}
Using the email validationⓘ API is an effective way to prevent erroneous and poor-quality data from entering your email lists. You can use the API in either bulk or real time. For each email address it verifies, the API consumes one credit from your ZeroBounce account. If you use the API on a consistent basis, please make sure your account is replenished periodically with credits.
Need help determining the status of your email validationⓘ API files? Please reach out to our Customer Support team. We are available around the clock to answer any questions and assist you.
Get File (v2)
Would you like to get your email validationⓘ API results? Please follow our instructions below.
The getfile API allows you to get the validation results for the file you submitted using sendfile API. Please refer to the C# example for details.
GET /V2/GETFILE
API URL: https://bulkapi.zerobounce.net/v2/getfile
URL Parameters
- ParameterDescription
- api_keyYour API Key, found in your account.
- file_idThe returned file ID when calling sendfile API.
- activity_dataPossible values: true/false
If set to ‘true’ activity data information will be appended to the results file.
Click here for more information about Activity Data.
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 API key and the FILE ID with the returned file ID from sendfile API:
https://bulkapi.zerobounce.net/v2/getfile?api_key=replacewithyours&file_id=[replacewithyours]
Or if you wish for Activity Data to be added to the results file please include activity_data=true:
https://bulkapi.zerobounce.net/v2/getfile?api_key=replacewithyours&file_id=[replacewithyours]&activity_data=true
GETFILE CODE SAMPLES
ENDPOINT RESPONSE
Successful Response
//N/AThe getfile API returns the validation results file. The returned content type is "application/octet-stream". You can get the file name from response.Content.Headers.ContentDisposition.FileName. If you are calling the API directly from the browser, you can either save or open the results file from the browser.
Error Response
{
"success": false,
"error_message": "Error messages"
} The ZeroBounce email validationⓘ API can be used either in real time or in bulk – if you need to validate emails consistently and would like to automate the process. The API detects more than 30 email status and sub-status codes, preventing risky and poor-quality data from being added to your email database.
Need help getting your email validationⓘ API results? Our team is here to lend a hand. Reach out to us anytime, we offer 24/7 customer support.
Delete File (v2)
Have you retrieved your email validationⓘ API results and would like to delete your file? You’ve come to the right place.
The deletefile API deletes the file that you submitted using the sendfile API. Please note that the file can be deleted only when its status is Complete.
API URL: https://bulkapi.zerobounce.net/v2/deletefile
GET /V2/DELETEFILE
URL Parameters
- ParameterDescription
- api_keyYour API Key, found in your account.
- file_idThe returned file ID when calling sendfile API.
DELETE FILE CODE SAMPLES
ENDPOINT RESPONSE
Below you can find examples of both successful and errors responses.
Successful Response
{
"success": true,
"message": "File Deleted",
"file_name": "test2",
"file_id": "b222a0fd-90d5-416c-8f1a-9cc3851fc823"
}Error Response
{
"success": false,
"error_message": "File cannot be found."
}The ZeroBounce email validation API streamlines your workflows and saves you time. The API returns 30 statuses and sub-statuses about the email data in your list. You can use it both in real time and in bulk – if you’d like to program it and automate your email verification.
The ZeroBounce API prevents erroneous and risky email addresses from being added to your database. It detects typos, abuse, role-based emails, catch-all emailsⓘ and spam traps, just to name a few. Once connected to your signup form, it verifies the email contact of every new subscriber, thus keeping your data accurate.
If you need help deleting your email validationⓘ API file, please let us know. Our team is here 24/7 to answer any questions and make things easier for you.