ZeroBounce Documentation

The ZeroBounce Developer Hub

Welcome to the ZeroBounce developer hub. You'll find comprehensive guides and documentation to help you start working with ZeroBounce as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Documentation

Validate Emails

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.

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 algorythm you will get an unknown result. You can always re-validate those conditions, uploading a file to the bulk email validator.

Calling The API

Try
    Dim apiKey as string = "Your Secret Key"
    Dim emailToValidate as string = "example@example.com"
    Dim responseString as string = ""
    Dim apiURL as string = "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")
 
 
    Dim request As HttpWebRequest = DirectCast(WebRequest.Create(apiURL), HttpWebRequest)
    request.Timeout = 150000
    request.Method = "GET"
 
    Using response As WebResponse = request.GetResponse()
        response.GetResponseStream().ReadTimeout = 20000
        Using ostream As New StreamReader(response.GetResponseStream())
            responseString = ostream.ReadToEnd()
        End Using
    End Using
Catch ex as exception
'Catch Exception - All errors will be shown here - if there are issues with the API
End Try
try {
string apiKey = "Your Secret Key";
string emailToValidate = "example@example.com";
string responseString = "";
    string apiURL = "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")
 
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiURL);
    request.Timeout = 150000;
    request.Method = "GET";
 
    using (WebResponse response = request.GetResponse()) {
        response.GetResponseStream().ReadTimeout = 20000;
        using (StreamReader ostream = new StreamReader(response.GetResponseStream())) {
            responseString = ostream.ReadToEnd();
        }
    }
    } catch (exception ex) {
//Catch Exception - All errors will be shown here - if there are issues with the API
}
<?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);
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);
?>
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
 
public class MyClass {
 
    public static void main(String[] args){
 
        String key = "Your Secret Key";
        String email = "example@example.com";
        String ip = "99.123.12.122";
        String targetURL = "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;
 
        HttpURLConnection connection = null;
        final String USER_AGENT = "Mozilla/5.0";
 
        try {
            URL url = new URL(targetURL);
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.addRequestProperty("User-Agent", USER_AGENT);
            connection.setUseCaches(false);
            connection.setDoOutput(true);
 
            BufferedReader in = new BufferedReader(
                    new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
 
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
 
            //print result
            System.out.println(response.toString());
 
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
 
    }
}
url = "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"] = ipaddress
 
response = requests.get(url, params=params)
 
# Print the returned json
print json.loads(response.content)
let key = "Your Secret Key"
let email = "example@example.com"
let url = URL(string: String(format: "https://api.zerobounce.net/v1/validate?apikey=%@&email=%@", key, email))
let ip = "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))
let task = URLSession.shared.dataTask(with: url!) { (data, response, error) in
    if error != nil {
        NSLog("Error \(String(describing: error))")
    } else {
        do {
            let parsedData = try JSONSerialization.jsonObject(with: data!) as! [String:Any]
            for (key, value) in parsedData {
                NSLog("\(key) = \(value) ")
            }
        } catch {
            print("Error deserializing JSON: \(error)")
        }
    }
}
task.resume()
NSString *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);
    });
});
Add to build.gradle (App) in the "android" bracket:
useLibrary 'org.apache.http.legacy'
 
Example:
 
android {
    compileSdkVersion 25
    useLibrary 'org.apache.http.legacy'
}
 
-----------------------------------
Filename: JsonParser.java
 
 
import android.os.AsyncTask;
import org.json.JSONObject;
import java.util.Iterator;
 
public class MainActivity extends AppCompatActivity {
 
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
 
        new AsyncTaskParseJson().execute();
    }
}
 
public class AsyncTaskParseJson extends AsyncTask<String, String, String> {
 
    String key = "Your Secret Key";
    String email = "example@example.com";
    String ip = "99.123.12.122";
    String url = "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;
 
    @Override
    protected void onPreExecute() {
    }
 
    @Override
    protected String doInBackground(String... arg0) {
 
        JsonParser jParser = new JsonParser();
        JSONObject json = jParser.getJSONFromUrl(url);
        Iterator keys = json.keys();
        while( keys.hasNext() ) {
            String key = (String)keys.next();
            try {
                System.out.println("ZeroBounce: "+key+" = " +json.get(key).toString());
            }
            catch (Exception e){}
        }
 
        return null;
    }
    @Override
    protected void onPostExecute(String strFromDoInBg) {}
}
 
----------------------------------
Filename: MainActivity.java
 
package com.zerobounce.zbapiandroid;
 
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.UnsupportedEncodingException;
 
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;
import org.json.JSONException;
import org.json.JSONObject;
 
import android.util.Log;
 
public class JsonParser {
 
    final String TAG = "JsonParser.java";
 
    static InputStream is = null;
    static JSONObject jObj = null;
    static String json = "";
 
    public JSONObject getJSONFromUrl(String url) {
 
        try {
 
            DefaultHttpClient httpClient = new DefaultHttpClient();
            HttpGet httpGet = new HttpGet(url);
 
            HttpResponse httpResponse = httpClient.execute(httpGet);
            HttpEntity httpEntity = httpResponse.getEntity();
            is = httpEntity.getContent();
 
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        } catch (ClientProtocolException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
 
        try {
 
            BufferedReader reader = new BufferedReader(new InputStreamReader(is, "iso-8859-1"), 8);
            StringBuilder sb = new StringBuilder();
            String line = null;
            while ((line = reader.readLine()) != null) {
                sb.append(line + "\n");
            }
            is.close();
            json = sb.toString();
 
        } catch (Exception e) {
            Log.e(TAG, "Error converting result " + e.toString());
        }
 
        try {
            jObj = new JSONObject(json);
        } catch (JSONException e) {
            Log.e(TAG, "Error parsing data " + e.toString());
        }
 
        return jObj;
    }
}

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

address - The email address you are validating.
status - [Valid |Invalid |Catch-All |Unknown |Spamtrap |Abuse |DoNotMail]
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 diposable, which are usually temporary email addresses.
toxic - [true|false] These domains are known for abuse, spam, and 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].
creation date - The creation date of the email when available or [null].
location - The location of the owner of the email when available or [null].
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

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.

Please visit our Status Code Documentation for an explanation of each status.

Successful response sample from the API using the "validate" method

{
 "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 sample from the API using the "validatewithip" method

{
 "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"
 }

Failure response sample using the API with either method

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

Validate Emails