How to use the ZeroBounce API

Validate Emails (v1)

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. This endpoint can be called asynchronously and is currently not rate limited.

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
  • ipaddress
    The IP Address the email signed up from (Can be blank, but parameter required)
  • apikey
    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

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
' Complete API Libraries and Wrappers can be found here: ' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_netTryDimapiKey asstring="Your Secret Key"DimemailToValidate asstring="example@example.com" DimresponseString asstring=""DimapiURL asstring="https://api.zerobounce.net/v1/validate?apikey="&apiKey &"&email="&HttpUtility.UrlEncode(emailToValidate)'Uncomment out to use the optional API with IP Lookup'Dim apiURL as string="https://api.zerobounce.net/v1/validatewithip?apikey=" & apiKey & "&email=" & HttpUtility.UrlEncode(emailToValidate) & "&ipaddress=" & HttpUtility.UrlEncode("99.123.12.122")Dimrequest AsHttpWebRequest =DirectCast(WebRequest.Create(apiURL),HttpWebRequest)request.Timeout=150000request.Method ="GET"Usingresponse AsWebResponse =request.GetResponse()response.GetResponseStream().ReadTimeout =20000Usingostream AsNewStreamReader(response.GetResponseStream())responseString =ostream.ReadToEnd()EndUsingEndUsingCatchex asexception
'Catch Exception - All errors will be shown here - if there are issues with the APIEndTry
// Complete API Libraries and Wrappers can be found here: // https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__c-sharptry{stringapiKey ="Your Secret Key";stringemailToValidate ="example@example.com";stringresponseString ="";stringapiURL ="https://api.zerobounce.net/v1/validate?apikey="+apiKey +"&email="+HttpUtility.UrlEncode(emailToValidate);//Uncomment out to use the optional API with IP Lookup//string apiURL="https://api.zerobounce.net/v1/validatewithip?apikey=" + apiKey + "&email=" + HttpUility.UrlEncode(emailToValidate); + "&ipaddress=" + HttpUtility.UrlEncode("99.123.12.122")HttpWebRequestrequest =(HttpWebRequest)WebRequest.Create(apiURL);request.Timeout =150000;request.Method ="GET";using(WebResponseresponse =request.GetResponse()){response.GetResponseStream().ReadTimeout =20000;using(StreamReaderostream =newStreamReader(response.GetResponseStream())){responseString =ostream.ReadToEnd();}}}catch(exception ex){//Catch Exception - All errors will be shown here - if there are issues with the API}
<?php// Complete API Libraries and Wrappers can be found here: // https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__php//set the api key and email to be validated$apiKey='Your Secret Key';$emailToValidate='example@example.com';$IPToValidate='99.123.12.122';// use curl to make the request$url='https://api.zerobounce.net/v1/validate?apikey='.$apiKey.'&email='.urlencode($emailToValidate);//Uncomment out to use the optional API with IP Lookup// $url='https://api.zerobounce.net/v1/validatewithip?apikey='.$apiKey.'&email='.urlencode($emailToValidate).'&ipaddress='.urlencode($IPToValidate);$ch=curl_init($url);//PHP 5.5.19 and higher has support for TLS 1.2curl_setopt($ch,CURLOPT_SSLVERSION,6);curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);curl_setopt($ch,CURLOPT_CONNECTTIMEOUT,15);curl_setopt($ch,CURLOPT_TIMEOUT,150);$response=curl_exec($ch);curl_close($ch);//decode the json response$json=json_decode($response,true);?>
//Complete API Libraries and Wrappers can be found here: //https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__javaimportjava.io.BufferedReader;importjava.io.InputStreamReader;importjava.net.HttpURLConnection;importjava.net.URL;publicclassMyClass{publicstaticvoidmain(String[]args){Stringkey ="Your Secret Key";Stringemail ="example@example.com";Stringip ="99.123.12.122";StringtargetURL ="https://api.zerobounce.net/v1/validate?apikey="+key+"&email="+email;// Uncomment out to use the optional API with IP Lookup// String targetURL="https://api.zerobounce.net/v1/validatewithip?apikey="+key+"&email="+email+"&ipaddress="+ip;HttpURLConnectionconnection =null;finalStringUSER_AGENT ="Mozilla/5.0";try{URLurl =newURL(targetURL);connection =(HttpURLConnection)url.openConnection();connection.setRequestMethod("GET");connection.addRequestProperty("User-Agent",USER_AGENT);connection.setUseCaches(false);connection.setDoOutput(true);BufferedReaderin =newBufferedReader(newInputStreamReader(connection.getInputStream()));StringinputLine;StringBufferresponse =newStringBuffer();while((inputLine =in.readLine())!=null){response.append(inputLine);}in.close();//print resultSystem.out.println(response.toString());}catch(Exceptione){e.printStackTrace();}finally{if(connection !=null){connection.disconnect();}}}}
# Complete API Libraries and Wrappers can be found here: # https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__pythonurl ="https://api.zerobounce.net/v1/validate"apikey ="Your Secret Key"email ="example@example.com"ipaddress ="99.123.12.122"params ={"email":email,"apikey":apikey}# Uncomment to use the optional API with IP Lookup# params["ipaddress"]=ipaddressresponse =requests.get(url,params=params)# Print the returned jsonprintjson.loads(response.content)
// Complete API Libraries and Wrappers can be found here: // https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOSletkey ="Your Secret Key"letemail ="example@example.com"leturl =URL(string:String(format:"https://api.zerobounce.net/v1/validate?apikey=%@&email=%@",key,email))letip ="99.123.12.122"// Uncomment out to use the optional API with IP Lookup// let url=URL(string: String(format: "https://api.zerobounce.net/v1/validatewithip?apikey=%@&email=%@&ipaddress=%@", key, email, ip))lettask =URLSession.shared.dataTask(with:url!){(data,response,error)iniferror !=nil{NSLog("Error (String(describing: error))")}else{do{letparsedData =tryJSONSerialization.jsonObject(with:data!)as![String:Any]for(key,value)inparsedData {NSLog("(key)=(value) ")}}catch{print("Error deserializing JSON: (error)")}}}task.resume()
// Complete API Libraries and Wrappers can be found here: // https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOSNSString *key =@"Your Secret Key";NSString *email =@"example@example.com";NSString *ip =@"99.123.12.122";NSString *urlString =[NSString stringWithFormat:@"https://api.zerobounce.net/v1/validate?apikey=%@&email=%@",key,email];// NSString *urlString=[NSString stringWithFormat:@"https://api.zerobounce.net/v1/validatewithip?apikey=%@&email=%@&ipaddress=%@", key, email, ip];// Uncomment out to use the optional API with IP Lookup__block NSURL *url =[NSURL URLWithString:urlString];dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT,0),^{NSData *response =[NSData dataWithContentsOfURL:url];NSDictionary *arrResponse =nil;if(response!=nil){arrResponse =[NSJSONSerialization JSONObjectWithData:response options:kNilOptions error:nil];}dispatch_async(dispatch_get_main_queue(),^(void){for(NSString *key in[arrResponse allKeys]){NSLog(@"%@: %@",key,[arrResponse objectForKey:key]);}// callback(nil, arr);});});
// Complete API Libraries and Wrappers can be found here: // https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__android//Add to build.gradle (App) in the "android" bracket:useLibrary 'org.apache.http.legacy'//Example:android {compileSdkVersion 25useLibrary 'org.apache.http.legacy'}//-----------------------------------//Filename: JsonParser.javaimportandroid.os.AsyncTask;importorg.json.JSONObject;importjava.util.Iterator;publicclassMainActivityextendsAppCompatActivity{@OverrideprotectedvoidonCreate(BundlesavedInstanceState){super.onCreate(savedInstanceState);newAsyncTaskParseJson().execute();}}publicclassAsyncTaskParseJsonextendsAsyncTask<String,String,String>{Stringkey ="Your Secret Key";Stringemail ="example@example.com";Stringip ="99.123.12.122";Stringurl ="https://api.zerobounce.net/v1/validate?apikey="+key+"&email="+email;// Uncomment out to use the optional API with IP Lookup// String url="https://api.zerobounce.net/v1/validatewithip?apikey="+key+"&email="+email+"&ipaddress="+ip;@OverrideprotectedvoidonPreExecute(){}@OverrideprotectedStringdoInBackground(String...arg0){JsonParserjParser =newJsonParser();JSONObjectjson =jParser.getJSONFromUrl(url);Iteratorkeys =json.keys();while(keys.hasNext()){Stringkey =(String)keys.next();try{System.out.println("ZeroBounce: "+key+"="+json.get(key).toString());}catch(Exceptione){}}returnnull;}@OverrideprotectedvoidonPostExecute(StringstrFromDoInBg){}}//----------------------------------//Filename: MainActivity.javapackagecom.zerobounce.zbapiandroid;importjava.io.BufferedReader;importjava.io.IOException;importjava.io.InputStream;importjava.io.InputStreamReader;importjava.io.UnsupportedEncodingException;importorg.apache.http.HttpEntity;importorg.apache.http.HttpResponse;importorg.apache.http.client.ClientProtocolException;importorg.apache.http.client.methods.HttpGet;importorg.apache.http.impl.client.DefaultHttpClient;importorg.json.JSONException;importorg.json.JSONObject;importandroid.util.Log;publicclassJsonParser{finalStringTAG ="JsonParser.java";staticInputStreamis =null;staticJSONObjectjObj =null;staticStringjson ="";publicJSONObjectgetJSONFromUrl(Stringurl){try{DefaultHttpClienthttpClient =newDefaultHttpClient();HttpGethttpGet =newHttpGet(url);HttpResponsehttpResponse =httpClient.execute(httpGet);HttpEntityhttpEntity =httpResponse.getEntity();is =httpEntity.getContent();}catch(UnsupportedEncodingExceptione){e.printStackTrace();}catch(ClientProtocolExceptione){e.printStackTrace();}catch(IOExceptione){e.printStackTrace();}try{BufferedReaderreader =newBufferedReader(newInputStreamReader(is,"iso-8859-1"),8);StringBuildersb =newStringBuilder();Stringline =null;while((line =reader.readLine())!=null){sb.append(line +"
");}is.close();json =sb.toString();}catch(Exceptione){Log.e(TAG,"Error converting result "+e.toString());}try{jObj =newJSONObject(json);}catch(JSONExceptione){Log.e(TAG,"Error parsing data "+e.toString());}returnjObj;}}

Endpoint Response

Successful Response

{"address":"flowerjill@aol.com","status":"Valid","sub_status":"","account":"flowerjill","domain":"aol.com","disposable":false,"toxic":false,"firstname":"Jill","lastname":"Stein","gender":"female","location":null,"creationdate":null,"processedat":"2017-04-01 02:48:02.592"}

Successful Response with IP

{"address":"flowerjill@aol.com","status":"Valid","sub_status":"","account":"flowerjill","domain":"aol.com","disposable":false,"toxic":false,"firstname":"Jill","lastname":"Stein","gender":"female","location":null,"country":"United States","region":"Florida","city":"West Palm Beach","zipcode":"33401","creationdate":null,"processedat":"2017-04-01 02:48:02.592"}

Error Response

{"error":"Invalid API Key or your account ran out of credits"}