API Quickstart
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:
{
"info": {
"_postman_id": "948780e4-bf36-4c9c-bb29-2c32c9053091",
"name": "ZeroBounce API v2",
"schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
},
"item": [
{
"name": "Validate Emails",
"request": {
"method": "GET",
"header": [],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "https://api.zerobounce.net/v2/validate?api_key=replacewithyours&email=replacewithyours&ip_address=",
"protocol": "https",
"host": [
"api",
"zerobounce",
"net"
],
"path": [
"v2",
"validate"
],
"query": [
{
"key": "api_key",
"value": "replacewithyours",
"description": "Your API Key, found in your account."
},
{
"key": "email",
"value": "replacewithyours",
"description": "The email address you want to validate"
},
{
"key": "ip_address",
"value": "",
"description": "The IP Address the email signed up from (Can be blank, but parameter required)"
}
]
},
"description": "API for single email address validation."
},
"response": []
},
{
"name": "Get Credit Balance",
"request": {
"method": "GET",
"header": [],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "https://api.zerobounce.net/v2/getcredits?api_key=replacewithyours",
"protocol": "https",
"host": [
"api",
"zerobounce",
"net"
],
"path": [
"v2",
"getcredits"
],
"query": [
{
"key": "api_key",
"value": "replacewithyours",
"description": "Your API Key, found in your account."
}
]
},
"description": "This API will tell you how many credits you have left on your account."
},
"response": []
},
{
"name": "Send File",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "file",
"description": "csv or txt file",
"type": "file",
"src": ""
},
{
"key": "api_key",
"value": "replacewithyours",
"description": "Your API Key, found in your account. (Required)",
"type": "text"
},
{
"key": "return_url",
"value": "",
"description": "The URL will be used to call back when the validation is completed. (Optional)",
"type": "text",
"disabled": true
},
{
"key": "email_address_column",
"value": "replacewithyours",
"description": "The column index of the email address in your file. Index starts from 1. (Required, number)",
"type": "text"
},
{
"key": "first_name_column",
"value": "",
"description": "The column index of the first name column. (Optional, number)",
"type": "text",
"disabled": true
},
{
"key": "last_name_column",
"value": "",
"description": "The column index of the last name column. (Optional, number)",
"type": "text",
"disabled": true
},
{
"key": "gender_column",
"value": "",
"description": "The column index of the gender column. (Optional, number)",
"type": "text",
"disabled": true
},
{
"key": "ip_address_column",
"value": "",
"description": "The IP Address the email signed up from. (Optional, number)",
"type": "text",
"disabled": true
},
{
"key": "has_header_row",
"value": "",
"description": "If the first row from the submitted file is a header row. (Optional, true/false)",
"type": "text",
"disabled": true
}
]
},
"url": "https://bulkapi.zerobounce.net/v2/sendfile",
"description": "This API allows user to send a file for bulk email validation."
},
"response": []
},
{
"name": "File Status",
"request": {
"method": "GET",
"header": [],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "https://bulkapi.zerobounce.net/v2/filestatus?api_key=replacewithyours&file_id=replacewithyours",
"protocol": "https",
"host": [
"bulkapi",
"zerobounce",
"net"
],
"path": [
"v2",
"filestatus"
],
"query": [
{
"key": "api_key",
"value": "replacewithyours",
"description": "Your API Key, found in your account."
},
{
"key": "file_id",
"value": "replacewithyours",
"description": "The returned file ID when calling sendfile API."
}
]
},
"description": "The API returns the file processing status for the file been submitted using sendfile API."
},
"response": []
},
{
"name": "Get File",
"request": {
"method": "GET",
"header": [],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "https://bulkapi.zerobounce.net/v2/getfile?api_key=replacewithyours&file_id=replacewithyours",
"protocol": "https",
"host": [
"bulkapi",
"zerobounce",
"net"
],
"path": [
"v2",
"getfile"
],
"query": [
{
"key": "api_key",
"value": "replacewithyours",
"description": "Your API Key, found in your account."
},
{
"key": "file_id",
"value": "replacewithyours",
"description": "The returned file ID when calling sendfile API."
}
]
},
"description": "The API allows users to get the validation results file for the file been submitted using sendfile API."
},
"response": []
},
{
"name": "Delete File",
"request": {
"method": "GET",
"header": [],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "https://bulkapi.zerobounce.net/v2/deletefile?api_key=replacewithyours&file_id=replacewithyours",
"protocol": "https",
"host": [
"bulkapi",
"zerobounce",
"net"
],
"path": [
"v2",
"deletefile"
],
"query": [
{
"key": "api_key",
"value": "replacewithyours",
"description": "Your API Key, found in your account."
},
{
"key": "file_id",
"value": "replacewithyours",
"description": "The returned file ID when calling sendfile API."
}
]
},
"description": "The API returns the file processing status for the file been submitted using sendfile API."
},
"response": []
}
]
}
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://bulkapi.zerobounce.net/v2/validate
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, found in your account.
Get Credit Balance Code Samples
' Complete API Libraries and Wrappers can be found here:
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net
Try
Dim apiKey = "Your Secret Key"
Dim apiURL = "https://api.zerobounce.net/v2/getcredits?api_key=" & apiKey
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
// 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-sharp
try {
string apiKey = "Your Secret Key";
string apiURL = "https://api.zerobounce.net/v2/getcredits?api_key=" + apiKey;
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
// 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';
// use curl to make the request
$url = 'https://api.zerobounce.net/v2/getcredits?api_key='.$apiKey;
$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);
?>
//Complete API Libraries and Wrappers can be found here:
//https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__java
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 targetURL = "https://api.zerobounce.net/v2/getcredits?api_key="+key;
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();
}
}
}
}
# Complete API Libraries and Wrappers can be found here:
# https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__python
import requests
import json
target_url = "https://api.zerobounce.net/v2/getcredits?api_key="
secret_key = "Your Secret Key"
api_response = requests.get("%s%s" % (target_url, secret_key))
data = json.loads(api_response.content)
# prints the number of credits
print data["Credits"]
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
let key = "Your Secret Key"
let url = URL(string: String(format: "https://api.zerobounce.net/v2/getcredits?api_key=%@", key))
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 *urlString = [NSString stringWithFormat:@"https://api.zerobounce.net/v2/getcredits?api_key=%@", key];
__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 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 url = "https://api.zerobounce.net/v2/getcredits?api_key="+key;
@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 + "
");
}
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;
}
}
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
{"Credits":2375323}
Error Response
{"Credits":-1}
GET /v2/getapiusage
API URL: https://bulkapi.zerobounce.net/v2/getapiusage
URL Parameters
- ParameterDescription
- api_keyYour API Key, found in your account.
- start_dateThe start date of when you want to view API usage
- end_dateThe end date of when you want to view API usage
https://api.zerobounce.net/v2/getapiusage?%3Cyour%20key%3E&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"
- start_dateStart date of query
- end_dateEnd date of query
Get API Usage Code Samples
' Complete API Libraries and Wrappers can be found here:
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net
Try
Dim api_key as string = "Your Secret Key"
Dim start_date as string = "2018-01-01"
Dim end_date as string = "2019-12-12"
Dim responseString as string = ""
Dim apiURL as string = "https://api.zerobounce.net/v2/getapiusage?api_key=" & api_key & "&start_date=" & start_date & "&end_date=" & end_date
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
// 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-sharp
try {
string api_key = "Your Secret Key";
string start_date = "2018-01-01";
string end_date = "2019-12-12";
string responseString = "";
string apiURL = "https://api.zerobounce.net/v2/getapiusage?api_key=" + api_key + "&start_date=" + start_date + "&end_date=" + end_date;
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
// 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
$api_key = 'Your Secret Key';
$start_date = '2018-01-01';
$end_date = '2019-12-12';
// use curl to make the request
$url = 'https://api.zerobounce.net/v2/getapiusage?api_key='.$api_key.'&start_date='.$start_date.'&end_date='.$end_date;
$ch = curl_init($url);
//PHP 5.5.19 and higher has support for TLS 1.2
curl_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__java
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 start_date = "2018-01-01";
String end_date = "2019-12-12";
String targetURL = "https://api.zerobounce.net/v2/getapiusage?api_key="+key+"&start_date="+start_date+"&end_date="+end_date;
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();
}
}
}
}
# Complete API Libraries and Wrappers can be found here:
# https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__python
url = "https://api.zerobounce.net/v2/getapiusage"
api_key = "Your Secret Key"
start_date = "2018-01-01"
end_date = "2019-12-12"
params = {"api_key": api_key, "start_date": start_date, "end_date":end_date}
response = requests.get(url, params=params)
# Print the returned json
print json.loads(response.content)
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
let key = "Your Secret Key"
let start_date = "2018-01-01"
let end_date = "2019-12-12" //ip address can be blank
let url = URL(string: String(format: "https://api.zerobounce.net/v2/getapiusage?api_key=%@&start_date=%@&end_date=%@", key, start_date, end_date))
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()
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
NSString *key = @"Your Secret Key";
NSString *start_date = @"2018-01-01";
NSString *end_date = @"2019-12-12";
NSString *urlString = [NSString stringWithFormat:@"https://api.zerobounce.net/v2/getapiusage?api_key=%@&start_date=%@&end_date=%@", key, start_date, end_date];
__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 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 start_date = "2018-01-01";
String end_date = "2019-12-12";
String url = "https://api.zerobounce.net/v2/getapiusage?api_key="+key+"&start_date="+start_date+"&end_date="+end_date;
@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 + "
");
}
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;
}
}
Endpoint Response
Successful Response
{
"total": 3,
"status_valid": 1,
"status_invalid": 2,
"status_catch_all": 0,
"status_do_not_mail": 0,
"status_spamtrap": 0,
"status_unknown": 0,
"sub_status_toxic": 0,
"sub_status_disposable": 0,
"sub_status_role_based": 0,
"sub_status_possible_trap": 0,
"sub_status_global_suppression": 0,
"sub_status_timeout_exceeded": 0,
"sub_status_mail_server_temporary_error": 0,
"sub_status_mail_server_did_not_respond": 0,
"sub_status_greylisted": 0,
"sub_status_antispam_system": 0,
"sub_status_does_not_accept_mail": 0,
"sub_status_exception_occurred": 0,
"sub_status_failed_syntax_check": 0,
"sub_status_mailbox_not_found": 2,
"sub_status_unroutable_ip_address": 0,
"sub_status_possible_typo": 0,
"sub_status_no_dns_entries": 0,
"sub_status_role_based_catch_all": 0,
"sub_status_mailbox_quota_exceeded": 0,
"sub_status_forcible_disconnect": 0,
"sub_status_failed_smtp_connection": 0,
"start_date": "1/1/2018",
"end_date": "12/12/2019"
}
Error Response - API Key
{"error":"Invalid API Key"}
Error Response - Date
{"error":"Invalid Date"}
The sendfile API allows user 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.
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_keypi_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)
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": "10/20/2018 4:35:58 PM"
}
Send File Code Samples
' Complete API Libraries and Wrappers can be found here:
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net
' Send File Sample in VB.net
Public Class SendFileStatus
Public Property success As Boolean
Public Property message As String
Public Property file_name As String
Public Property file_id As String
End Class
Private Shared Sub SendFileAPITest()
Dim fileFullPath As String = $"full file path of a csv or txt file" ' required
Dim apiKey As String = "replace with your api key here" ' required
Dim emailAddressColumn As Integer = 2 ' required
Dim firstNameColumn As Integer? = 5 ' optional
Dim lastNameColumn As Integer? = 6 ' optional
Dim genderColumn As Integer? = Nothing ' optional
Dim ipAddressColumn As Integer? = 11 ' optional
Dim hasHeaderRow As Boolean? = True ' optional
Dim returnUrl As String = Nothing ' optional
Try
Dim sendFileStatus As SendFileStatus = SendFile(fileFullPath, apiKey, emailAddressColumn, firstNameColumn, lastNameColumn, genderColumn, ipAddressColumn, hasHeaderRow, returnUrl).Result
Console.Write(JsonConvert.SerializeObject(sendFileStatus, Formatting.Indented))
Catch ex As Exception
Console.Write(ex.InnerException.Message)
End Try
Console.ReadKey()
End Sub
Public Shared Async Function SendFile(ByVal fileFullPath As String,
ByVal apiKey As String,
ByVal emailAddressColumn As Integer,
ByVal Optional firstNameColumn As Integer? = Nothing,
ByVal Optional lastNameColumn As Integer? = Nothing,
ByVal Optional genderColumn As Integer? = Nothing,
ByVal Optional ipAddressColumn As Integer? = Nothing,
ByVal Optional hasHeaderRow As Boolean? = Nothing,
ByVal Optional returnUrl As String = Nothing) As Task(Of SendFileStatus)
If String.IsNullOrEmpty(fileFullPath) Then Throw New Exception("Error: fileFullPath is required")
If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
Dim fi = New FileInfo(fileFullPath)
Dim fileContents = File.ReadAllBytes(fi.FullName)
Dim fileName = fi.Name
Dim uri As Uri = New Uri("https://bulkapi.zerobounce.net/v2/sendfile")
Using client = New HttpClient()
Using request = New HttpRequestMessage(HttpMethod.Post, uri)
Dim multiPartContent As MultipartFormDataContent = New MultipartFormDataContent()
Dim byteArrayContent As ByteArrayContent = New ByteArrayContent(fileContents)
byteArrayContent.Headers.Add("Content-Type", "text/csv")
multiPartContent.Add(byteArrayContent, "file", fileName)
multiPartContent.Add(New StringContent(apiKey), "api_key")
multiPartContent.Add(New StringContent(emailAddressColumn.ToString()), "email_address_column")
If firstNameColumn IsNot Nothing Then multiPartContent.Add(New StringContent(firstNameColumn.ToString()), "first_name_column")
If lastNameColumn IsNot Nothing Then multiPartContent.Add(New StringContent(lastNameColumn.ToString()), "last_name_column")
If genderColumn IsNot Nothing Then multiPartContent.Add(New StringContent(genderColumn.ToString()), "gender_column")
If ipAddressColumn IsNot Nothing Then multiPartContent.Add(New StringContent(ipAddressColumn.ToString()), "ip_address_column")
If hasHeaderRow IsNot Nothing Then multiPartContent.Add(New StringContent(If((hasHeaderRow = True), "true", "false")), "has_header_row")
If returnUrl IsNot Nothing Then multiPartContent.Add(New StringContent(returnUrl.ToString()), "return_url")
request.Content = multiPartContent
Using response = Await client.SendAsync(request, HttpCompletionOption.ResponseContentRead, CancellationToken.None).ConfigureAwait(False)
Dim content = Await response.Content.ReadAsStringAsync()
If response.IsSuccessStatusCode = False Then
Dim error As String = $"StatusCode = {CInt(response.StatusCode)}, Content = {content}"
Throw New Exception(error)
End If
Return JsonConvert.DeserializeObject(Of SendFileStatus)(content)
End Using
End Using
End Using
End Function
// 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-sharp
// Send File Sample in C#
public class SendFileStatus
{
public bool success { get; set; }
public string message { get; set; }
public string file_name { get; set; }
public string file_id { get; set; }
}
private static void SendFileAPITest()
{
string fileFullPath = $"full file path of a csv or txt file"; //required
string apiKey = "replace with your api key here"; //required
int emailAddressColumn = 2; //required
int? firstNameColumn = 5; //optional
int? lastNameColumn = 6; //optional
int? genderColumn = null; //optional
int? ipAddressColumn = 11; //optional
bool? hasHeaderRow = true; //optional
string returnUrl = null; //optional
try
{
SendFileStatus sendFileStatus = SendFile(fileFullPath, apiKey, emailAddressColumn, firstNameColumn, lastNameColumn, genderColumn, ipAddressColumn, hasHeaderRow, returnUrl).Result;
Console.Write(JsonConvert.SerializeObject(sendFileStatus, Formatting.Indented));
}
catch (Exception ex)
{
Console.Write(ex.InnerException.Message);
}
Console.ReadKey();
}
public static async Task<SendFileStatus> SendFile(string fileFullPath, string apiKey, int emailAddressColumn,
int? firstNameColumn = null, int? lastNameColumn = null, int? genderColumn = null,
int? ipAddressColumn = null, bool? hasHeaderRow = null, string returnUrl = null)
{
if (string.IsNullOrEmpty(fileFullPath))
throw new Exception("Error: fileFullPath is required");
if (string.IsNullOrEmpty(apiKey))
throw new Exception("Error: apiKey is required");
var fi = new FileInfo(fileFullPath);
var fileContents = File.ReadAllBytes(fi.FullName);
var fileName = fi.Name;
Uri uri = new Uri(@"https://bulkapi.zerobounce.net/v2/sendfile");
using (var client = new HttpClient())
using (var request = new HttpRequestMessage(HttpMethod.Post, uri))
{
MultipartFormDataContent multiPartContent = new MultipartFormDataContent();
ByteArrayContent byteArrayContent = new ByteArrayContent(fileContents);
byteArrayContent.Headers.Add("Content-Type", "text/csv");
multiPartContent.Add(byteArrayContent, "file", fileName);
multiPartContent.Add(new StringContent(apiKey), "api_key");
multiPartContent.Add(new StringContent(emailAddressColumn.ToString()), "email_address_column");
if (firstNameColumn != null)
multiPartContent.Add(new StringContent(firstNameColumn.ToString()), "first_name_column");
if (lastNameColumn != null)
multiPartContent.Add(new StringContent(lastNameColumn.ToString()), "last_name_column");
if (genderColumn != null)
multiPartContent.Add(new StringContent(genderColumn.ToString()), "gender_column");
if (ipAddressColumn != null)
multiPartContent.Add(new StringContent(ipAddressColumn.ToString()), "ip_address_column");
if (hasHeaderRow != null)
multiPartContent.Add(new StringContent((hasHeaderRow == true) ? "true" : "false"), "has_header_row");
if (returnUrl != null)
multiPartContent.Add(new StringContent(returnUrl.ToString()), "return_url");
request.Content = multiPartContent;
using (var response = await client.SendAsync(request, HttpCompletionOption.ResponseContentRead, CancellationToken.None).ConfigureAwait(false))
{
var content = await response.Content.ReadAsStringAsync();
if (response.IsSuccessStatusCode == false)
{
var error = $"StatusCode = {(int)response.StatusCode}, Content = {content}";
throw new Exception(error);
}
return JsonConvert.DeserializeObject<SendFileStatus>(content);
}
}
}
<?php
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://bulkapi.zerobounce.net/v2/sendfile",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"
replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"
replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--",
CURLOPT_HTTPHEADER => array(
"Postman-Token: fae6714d-dc09-4e08-b50d-c97030603b61",
"cache-control: no-cache",
"content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
//Complete API Libraries and Wrappers can be found here:
//https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW");
RequestBody body = RequestBody.create(mediaType, "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"
replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"
replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--");
Request request = new Request.Builder()
.url("https://bulkapi.zerobounce.net/v2/sendfile")
.post(body)
.addHeader("content-type", "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW")
.addHeader("cache-control", "no-cache")
.addHeader("Postman-Token", "25d608ba-6cb5-4c8c-88d7-d47276c67d8e")
.build();
Response response = client.newCall(request).execute();
# Complete API Libraries and Wrappers can be found here:
# https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__python
import http.client
conn = http.client.HTTPConnection("bulkapi,zerobounce,net")
payload = "------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api_key"
replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email_address_column"
replacewithyours
------WebKitFormBoundary7MA4YWxkTrZu0gW--"
headers = {
'content-type': "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
'cache-control': "no-cache",
'Postman-Token': "bc455eda-9884-417e-b16f-3a5fef3f7540"
}
conn.request("POST", "v2,sendfile", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
import Foundation
let headers = [
"content-type": "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
"cache-control": "no-cache",
"Postman-Token": "2f68fcc3-d9b6-458b-b613-56f6a03e6617"
]
let parameters = [
[
"name": "api_key",
"value": "replacewithyours"
],
[
"name": "email_address_column",
"value": "replacewithyours"
]
]
let boundary = "----WebKitFormBoundary7MA4YWxkTrZu0gW"
var body = ""
var error: NSError? = nil
for param in parameters {
let paramName = param["name"]!
body += "--(boundary)
"
body += "Content-Disposition:form-data; name="(paramName)""
if let filename = param["fileName"] {
let contentType = param["content-type"]!
let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
if (error != nil) {
print(error)
}
body += "; filename="(filename)"
"
body += "Content-Type: (contentType)
"
body += fileContent
} else if let paramValue = param["value"] {
body += "
(paramValue)"
}
}
let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/sendfile")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
// Please select VB or C# language for Send File Sample#import <Foundation/Foundation.h>
NSDictionary *headers = @{ @"content-type": @"multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
@"cache-control": @"no-cache",
@"Postman-Token": @"92c5b06e-624f-44e5-bd86-f537bc6cef67" };
NSArray *parameters = @[ @{ @"name": @"api_key", @"value": @"replacewithyours" },
@{ @"name": @"email_address_column", @"value": @"replacewithyours" } ];
NSString *boundary = @"----WebKitFormBoundary7MA4YWxkTrZu0gW";
NSError *error;
NSMutableString *body = [NSMutableString string];
for (NSDictionary *param in parameters) {
[body appendFormat:@"--%@
", boundary];
if (param[@"fileName"]) {
[body appendFormat:@"Content-Disposition:form-data; name="%@"; filename="%@"
", param[@"name"], param[@"fileName"]];
[body appendFormat:@"Content-Type: %@
", param[@"contentType"]];
[body appendFormat:@"%@", [NSString stringWithContentsOfFile:param[@"fileName"] encoding:NSUTF8StringEncoding error:&error]];
if (error) {
NSLog(@"%@", error);
}
} else {
[body appendFormat:@"Content-Disposition:form-data; name="%@"
", param[@"name"]];
[body appendFormat:@"%@", param[@"value"]];
}
}
[body appendFormat:@"
--%@--
", boundary];
NSData *postData = [body dataUsingEncoding:NSUTF8StringEncoding];
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://bulkapi.zerobounce.net/v2/sendfile"]
cachePolicy:NSURLRequestUseProtocolCachePolicy
timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"%@", error);
} else {
NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
NSLog(@"%@", httpResponse);
}
}];
[dataTask resume];
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__android
//N/A
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,
"message": [
"Error messages"
]
}
The filestatus API returns the file processing status for the file been submitted using 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 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
' Complete API Libraries and Wrappers can be found here:
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net
' File Status Sample in VB.net
Public Class FileStatus
Public Property success As Boolean
Public Property file_id As String
Public Property file_name As String
Public Property upload_date As String
Public Property file_status As String
Public Property complete_percentage As String
Public Property return_url As String
End Class
Private Shared Sub FileStatusAPITest()
Dim apiKey As String = "replace with your api key here"
Dim fileID As String = "replace with the returned file ID when calling sendfile API"
Try
Dim fileStatus As FileStatus = FileStatusAsync(apiKey, fileID).Result
Console.Write(JsonConvert.SerializeObject(fileStatus, Formatting.Indented))
Catch ex As Exception
Console.Write(ex.InnerException.Message)
End Try
Console.ReadKey()
End Sub
Public Shared Async Function FileStatusAsync(ByVal apiKey As String, ByVal fileID As String) As Task(Of FileStatus)
If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
If String.IsNullOrEmpty(fileID) Then Throw New Exception("Error: fileID is required")
Dim uri As Uri = New Uri($"https://bulkapi.zerobounce.net/v2/filestatus?api_key={apiKey}&file_id={fileID}")
Using client = New HttpClient()
Using request = New HttpRequestMessage(HttpMethod.Get, uri)
Using response = Await client.SendAsync(request).ConfigureAwait(False)
Dim content = Await response.Content.ReadAsStringAsync()
If response.IsSuccessStatusCode = False Then
Dim error As String = $"StatusCode = {CInt(response.StatusCode)}, Content = {content}"
Throw New Exception(error)
End If
Return JsonConvert.DeserializeObject(Of FileStatus)(content)
End Using
End Using
End Using
End Function
// 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-sharp
// File Status Sample in C#
public class FileStatus
{
public bool success { get; set; }
public string file_id { get; set; }
public string file_name { get; set; }
public string upload_date { get; set; }
public string file_status { get; set; }
public string complete_percentage { get; set; }
public string return_url { get; set; }
}
private static void FileStatusAPITest()
{
string apiKey = "replace with your api key here";
string fileID = "replace with the returned file ID when calling sendfile API";
try
{
FileStatus fileStatus = FileStatusAsync(apiKey, fileID).Result;
Console.Write(JsonConvert.SerializeObject(fileStatus, Formatting.Indented));
}
catch (Exception ex)
{
Console.Write(ex.InnerException.Message);
}
Console.ReadKey();
}
public static async Task<FileStatus> FileStatusAsync(string apiKey, string fileID)
{
if (string.IsNullOrEmpty(apiKey))
throw new Exception("Error: apiKey is required");
if (string.IsNullOrEmpty(fileID))
throw new Exception("Error: fileID is required");
Uri uri = new Uri($"https://bulkapi.zerobounce.net/v2/filestatus?api_key={apiKey}&file_id={fileID}");
using (var client = new HttpClient())
using (var request = new HttpRequestMessage(HttpMethod.Get, uri))
using (var response = await client.SendAsync(request).ConfigureAwait(false))
{
var content = await response.Content.ReadAsStringAsync();
if (response.IsSuccessStatusCode == false)
{
var error = $"StatusCode = {(int)response.StatusCode}, Content = {content}";
throw new Exception(error);
}
return JsonConvert.DeserializeObject<FileStatus>(content);
}
}
<?php
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://bulkapi.zerobounce.net/v2/filestatus?api_key=replacewithyours&file_id=replacewithyours",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => "",
CURLOPT_HTTPHEADER => array(
"Postman-Token: 91504cea-f92f-46b0-97a4-338167072887",
"cache-control: no-cache"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
//Complete API Libraries and Wrappers can be found here:
//https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__java
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://bulkapi.zerobounce.net/v2/filestatus?api_key=replacewithyours&file_id=replacewithyours")
.get()
.addHeader("cache-control", "no-cache")
.addHeader("Postman-Token", "7fffd7a4-b2fd-4e8b-ac85-4099411f27ce")
.build();
Response response = client.newCall(request).execute();
# Complete API Libraries and Wrappers can be found here:
# https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__python
import http.client
conn = http.client.HTTPConnection("bulkapi,zerobounce,net")
payload = ""
headers = {
'cache-control': "no-cache",
'Postman-Token': "caa917fe-45ce-45ae-9456-2b039b999dcb"
}
conn.request("GET", "v2,filestatus", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
// Please select VB or C# language for File Status Sampleimport Foundation
let headers = [
"cache-control": "no-cache",
"Postman-Token": "4f1b92e2-034f-4fa0-94d9-b097d768668a"
]
let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/filestatus?api_key=replacewithyours&file_id=replacewithyours")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
#import <Foundation/Foundation.h>
NSDictionary *headers = @{ @"cache-control": @"no-cache",
@"Postman-Token": @"5e9c24ae-b577-4e33-8748-83f14e151ae9" };
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://bulkapi.zerobounce.net/v2/filestatus?api_key=replacewithyours&file_id=replacewithyours"]
cachePolicy:NSURLRequestUseProtocolCachePolicy
timeoutInterval:10.0];
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"%@", error);
} else {
NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
NSLog(@"%@", httpResponse);
}
}];
[dataTask resume];
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__android
// N/A
Endpoint Response
Successful Response
{
"success": true,
"file_id": "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff",
"file_name": "Your file name.csv",
"upload_date": "10/20/2018 4:35:58 PM",
"file_status": "Complete",
"complete_percentage": "100%",
"return_url": "Your return URL if provided when calling sendfile API"
}
Error Response
{
"success": false,
"message": "Error messages"
}
The getfile API allows users to get the validation results file for the file been 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.
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 and the FILE ID with the returned file ID from sendfile API:
https://bulkapi.zerobounce.net/v2/getfile?api_key=replacewithyours&file_id=replacewithyoursGetFile Code Samples
' Complete API Libraries and Wrappers can be found here:
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net
' Get File Sample in VB.net
Private Shared Sub GetFileAPITest()
Dim apiKey As String = "replace with your api key here"
Dim fileID As String = "replace with the returned file ID when calling sendfile API"
Dim dir As String = "C: emp"
Try
Dim filePath = GetFileAsync(apiKey, fileID, dir).Result
Console.Write($"File {filePath} retrieved successfully.")
Catch ex As Exception
Console.Write(ex.InnerException.Message)
End Try
Console.ReadKey()
End Sub
Public Shared Async Function GetFileAsync(ByVal apiKey As String, ByVal fileID As String, ByVal dir As String) As Task(Of String)
If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
If String.IsNullOrEmpty(fileID) Then Throw New Exception("Error: fileID is required")
Dim uri As Uri = New Uri($"https://bulkapi.zerobounce.net/v2/getfile?api_key={apiKey}&file_id={fileID}")
Using client = New HttpClient()
Using request = New HttpRequestMessage(HttpMethod.Get, uri)
Using response = Await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead).ConfigureAwait(False)
Using streamToReadFrom As Stream = Await response.Content.ReadAsStreamAsync()
If response.IsSuccessStatusCode = False Then
Dim [error] = $"StatusCode = {CInt(response.StatusCode)}, Content = {response.Content.ReadAsStringAsync().Result}"
Throw New Exception([error])
End If
Dim filePath = Path.Combine(dir, response.Content.Headers.ContentDisposition.FileName)
Using streamToWriteTo As Stream = File.Open(filePath, FileMode.Create)
Await streamToReadFrom.CopyToAsync(streamToWriteTo)
End Using
Return filePath
End Using
End Using
End Using
End Using
End Function
// 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-sharp
// Get File Sample in C#
private static void GetFileAPITest()
{
string apiKey = "replace with your api key here";
string fileID = "replace with the returned file ID when calling sendfile API";
string dir = @"C: emp"; // specify the directory where you want to save the results file
try
{
var filePath = GetFileAsync(apiKey, fileID, dir).Result;
Console.Write($"File {filePath} retrieved successfully.");
}
catch (Exception ex)
{
Console.Write(ex.InnerException.Message);
}
Console.ReadKey();
}
public static async Task<string> GetFileAsync(string apiKey, string fileID, string dir)
{
if (string.IsNullOrEmpty(apiKey))
throw new Exception("Error: apiKey is required");
if (string.IsNullOrEmpty(fileID))
throw new Exception("Error: fileID is required");
Uri uri = new Uri($"https://bulkapi.zerobounce.net/v2/getfile?api_key={apiKey}&file_id={fileID}");
using (var client = new HttpClient())
using (var request = new HttpRequestMessage(HttpMethod.Get, uri))
using (var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead).ConfigureAwait(false))
using (Stream streamToReadFrom = await response.Content.ReadAsStreamAsync())
{
if (response.IsSuccessStatusCode == false)
{
var error = $"StatusCode = {(int)response.StatusCode}, Content = {response.Content.ReadAsStringAsync().Result}";
throw new Exception(error);
}
var filePath = Path.Combine(dir, response.Content.Headers.ContentDisposition.FileName);
using (Stream streamToWriteTo = File.Open(filePath, FileMode.Create))
{
await streamToReadFrom.CopyToAsync(streamToWriteTo);
}
return filePath;
}
}
<?php
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__php
$request = new HttpRequest();
$request->setUrl('https://bulkapi.zerobounce.net/v2/getfile');
$request->setMethod(HTTP_METH_GET);
$request->setQueryData(array(
'api_key' => 'replacewithyours',
'file_id' => 'replacewithyours'
));
$request->setHeaders(array(
'Postman-Token' => '0a6c40b8-0cd4-4dbb-a57e-422558e7ab6a',
'cache-control' => 'no-cache'
));
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
?>
//Complete API Libraries and Wrappers can be found here:
//https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__java
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://bulkapi.zerobounce.net/v2/getfile?api_key=replacewithyours&file_id=replacewithyours")
.get()
.addHeader("cache-control", "no-cache")
.addHeader("Postman-Token", "d0b7d318-f3f6-47fb-842d-5622b26592c1")
.build();
Response response = client.newCall(request).execute();
# Complete API Libraries and Wrappers can be found here:
# https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__python
import http.client
conn = http.client.HTTPConnection("bulkapi,zerobounce,net")
payload = ""
headers = {
'cache-control': "no-cache",
'Postman-Token': "9f615d7e-60af-4746-9bcc-317b1f80a6bb"
}
conn.request("GET", "v2,getfile", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
import Foundation
let headers = [
"cache-control": "no-cache",
"Postman-Token": "6c8cb1cb-25ed-4e56-b4cb-65e949b8bdd1"
]
let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/getfile?api_key=replacewithyours&file_id=replacewithyours")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
Endpoint Response
Successful Response
//N/A
The 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,
"message": "Error messages"
}
The deletefile API deletes the file that was submitted using sendfile API. File can be deleted only when its status is Complete.
POST /v2/deletefile
API URL: https://bulkapi.zerobounce.net/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
' Complete API Libraries and Wrappers can be found here:
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net
' Delete File Sample in VB.net
Public Class ResponseResult
Public Property success As Boolean
Public Property message As String
Public Property file_id As String
Public Property file_name As String
End Class
Private Shared Sub DeleteFileAPITest()
Dim apiKey As String = "replace with your api key here"
Dim fileID As String = "replace with the returned file ID when calling sendfile API"
Try
Dim responseResult As ResponseResult = DeleteFileAsync(apiKey, fileID).Result
Console.Write(JsonConvert.SerializeObject(responseResult, Formatting.Indented))
Catch ex As Exception
Console.Write(ex.InnerException.Message)
End Try
Console.ReadKey()
End Sub
Public Shared Async Function DeleteFileAsync(ByVal apiKey As String, ByVal fileID As String) As Task(Of ResponseResult)
If String.IsNullOrEmpty(apiKey) Then Throw New Exception("Error: apiKey is required")
If String.IsNullOrEmpty(fileID) Then Throw New Exception("Error: fileID is required")
Dim uri As Uri = New Uri($"https://bulkapi.zerobounce.net/v2/deletefile?api_key={apiKey}&file_id={fileID}")
Using client = New HttpClient()
Using request = New HttpRequestMessage(HttpMethod.[Get], uri)
Using response = Await client.SendAsync(request).ConfigureAwait(False)
Dim content = Await response.Content.ReadAsStringAsync()
If response.IsSuccessStatusCode = False Then
Dim [error] = $"StatusCode = {CInt(response.StatusCode)}, Content = {content}"
Throw New Exception([error])
End If
Return JsonConvert.DeserializeObject(Of ResponseResult)(content)
End Using
End Using
End Using
End Function
// 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-sharp
// Delete File Sample in C#
public class ResponseResult
{
public bool success { get; set; }
public string message { get; set; }
public string file_id { get; set; }
public string file_name { get; set; }
}
private static void DeleteFileAPITest()
{
string apiKey = "replace with your api key here";
string fileID = "replace with the returned file ID when calling sendfile API";
try
{
ResponseResult responseResult = DeleteFileAsync(apiKey, fileID).Result;
Console.Write(JsonConvert.SerializeObject(responseResult, Formatting.Indented));
}
catch (Exception ex)
{
Console.Write(ex.InnerException.Message);
}
Console.ReadKey();
}
public static async Task<ResponseResult> DeleteFileAsync(string apiKey, string fileID)
{
if (string.IsNullOrEmpty(apiKey))
throw new Exception("Error: apiKey is required");
if (string.IsNullOrEmpty(fileID))
throw new Exception("Error: fileID is required");
Uri uri = new Uri($"https://bulkapi.zerobounce.net/v2/deletefile?api_key={apiKey}&file_id={fileID}");
using (var client = new HttpClient())
using (var request = new HttpRequestMessage(HttpMethod.Get, uri))
using (var response = await client.SendAsync(request).ConfigureAwait(false))
{
var content = await response.Content.ReadAsStringAsync();
if (response.IsSuccessStatusCode == false)
{
var error = $"StatusCode = {(int)response.StatusCode}, Content = {content}";
throw new Exception(error);
}
return JsonConvert.DeserializeObject<ResponseResult>(content);
}
}
<?php
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://bulkapi.zerobounce.net/v2/deletefile?api_key=replacewithyours&file_id=replacewithyours",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => "",
CURLOPT_HTTPHEADER => array(
"Postman-Token: 91504cea-f92f-46b0-97a4-338167072887",
"cache-control: no-cache"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
//Complete API Libraries and Wrappers can be found here:
//https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__java
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://bulkapi.zerobounce.net/v2/deletefile?api_key=replacewithyours&file_id=replacewithyours")
.get()
.addHeader("cache-control", "no-cache")
.addHeader("Postman-Token", "7fffd7a4-b2fd-4e8b-ac85-4099411f27ce")
.build();
Response response = client.newCall(request).execute();
# Complete API Libraries and Wrappers can be found here:
# https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__python
import http.client
conn = http.client.HTTPConnection("bulkapi,zerobounce,net")
payload = ""
headers = {
'cache-control': "no-cache",
'Postman-Token': "caa917fe-45ce-45ae-9456-2b039b999dcb"
}
conn.request("GET", "v2,deletefile", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
// Please select VB or C# language for File Status Sampleimport Foundation
let headers = [
"cache-control": "no-cache",
"Postman-Token": "4f1b92e2-034f-4fa0-94d9-b097d768668a"
]
let request = NSMutableURLRequest(url: NSURL(string: "https://bulkapi.zerobounce.net/v2/deletefile?api_key=replacewithyours&file_id=replacewithyours")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
#import <Foundation/Foundation.h>
NSDictionary *headers = @{ @"cache-control": @"no-cache",
@"Postman-Token": @"5e9c24ae-b577-4e33-8748-83f14e151ae9" };
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://bulkapi.zerobounce.net/v2/deletefile?api_key=replacewithyours&file_id=replacewithyours"]
cachePolicy:NSURLRequestUseProtocolCachePolicy
timeoutInterval:10.0];
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"%@", error);
} else {
NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
NSLog(@"%@", httpResponse);
}
}];
[dataTask resume];
Endpoint Response
Successful Response
{
"success": true,
"message": "File Deleted",
"file_name": "test2",
"file_id": "b222a0fd-90d5-416c-8f1a-9cc3851fc823"
}
Error Response
{
"success": false,
"message": "File cannot be found."
}
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 Mode (v2)
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 /v2/validate
API URL: https://api.zerobounce.net/v2/validate
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
- emailThe email address you want to validate
- ip_addressThe IP Address the email signed up from (Can be blank, but parameter required)
- api_keyYour 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/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:
' Complete API Libraries and Wrappers can be found here:
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_net
Try
Dim api_key as string = "Your Secret Key"
Dim emailToValidate as string = "example@example.com"
Dim ip_address = "" 'Can be blank, but parameter required on the API Call
Dim responseString as string = ""
Dim apiURL as string = "https://api.zerobounce.net/v2/validate?api_key=" & api_key & "&email=" & HttpUtility.UrlEncode(emailToValidate) & "&ip_address=" & System.Net.WebUtility.UrlEncode(ip_address)
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
// 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-sharp
try {
string api_key = "Your Secret Key";
string emailToValidate = "example@example.com";
string ip_address = "" //Can be blank, but parameter required on the API Call
string responseString = "";
string apiURL = "https://api.zerobounce.net/v2/validate?api_key=" + api_key + "&email=" + HttpUtility.UrlEncode(emailToValidate) + "&ip_address=" + HttpUtility.UrlEncode(ip_address);
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
// 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
$api_key = 'Your Secret Key';
$emailToValidate = 'example@example.com';
$IPToValidate = '99.123.12.122';
// use curl to make the request
$url = 'https://api.zerobounce.net/v2/validate?api_key='.$api_key.'&email='.urlencode($emailToValidate).'&ip_address='.urlencode($IPToValidate);
$ch = curl_init($url);
//PHP 5.5.19 and higher has support for TLS 1.2
curl_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__java
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"; //ip address can be blank
String targetURL = "https://api.zerobounce.net/v2/validate?api_key="+key+"&email="+email+"&ip_address="+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();
}
}
}
}
# Complete API Libraries and Wrappers can be found here:
# https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__python
url = "https://api.zerobounce.net/v2/validate"
api_key = "Your Secret Key"
email = "example@example.com"
ip_address = "99.123.12.122" #ip_address can be blank
params = {"email": email, "api_key": api_key, "ip_address":ip_address}
response = requests.get(url, params=params)
# Print the returned json
print json.loads(response.content)
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
let key = "Your Secret Key"
let email = "example@example.com"
let ip = "99.123.12.122" //ip address can be blank
let url = URL(string: String(format: "https://api.zerobounce.net/v2/validate?api_key=%@&email=%@&ip_address=%@", 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()
// Complete API Libraries and Wrappers can be found here:
// https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__IOS
NSString *key = @"Your Secret Key";
NSString *email = @"example@example.com";
NSString *ip = @"99.123.12.122"; //ip address can be blank
NSString *urlString = [NSString stringWithFormat:@"https://api.zerobounce.net/v2/validate?api_key=%@&email=%@&ip_address=%@", key, email, ip];
__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 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"; //ip address can be blank
String url = "https://api.zerobounce.net/v2/validate?api_key="+key+"&email="+email+"&ip_address="+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 + "
");
}
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;
}
}
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",
"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[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, 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].
- 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.
- regionThe region/state of the IP passed in.
- zipcodeThe zipcode of the IP passed in.
- countryThe country of the IP passed in.
- Processed_atThe UTC time the email was validated.
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.
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. The results are 99.999% accurate.
- 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 not responding to mail commands. Most of the time, these emails will end up being invalid.
- mail_server_temporary_error - (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.
- 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 - (do_not_mail) These email addresses are known to be abuse, spam, or bot created emails. If you have valid emails with this flag set to TRUE, you shouldn't email them.
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.
- role_based_catch_all - (do_not_mail) These emails are role-based and also belong to a catch_all domain.
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).
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.