API Quickstart

Version 2: Getting Started

/email-validation-api-quickstart/v2-getting-started/

Postman Collection

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

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

Postman Collection JSON file:

{
  "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": []
    }
  ]
}

Get Credit Balance (v2)

/email-validation-api-quickstart/v2-credit-balance/

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

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

Get Credit Balance Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
      
    ' Complete API Libraries and Wrappers can be found here: 
    ' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_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}
    

Delete File (v2)

/email-validation-api-quickstart/v2-delete-file/

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

  • Parameter
    Description
  • api_key
    Your API Key, found in your account.
  • file_id
    The returned file ID when calling sendfile API.

Delete File Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
      
' 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."
}
    

File Status (v2)

/email-validation-api-quickstart/v2-file-status/

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

  • Parameter
    Description
  • api_key
    Your API Key, found in your account.
  • file_id
    The 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

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
      

' Complete API Libraries and Wrappers can be found here: 
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_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];
    

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

Get API Usage (v2)

/email-validation-api-quickstart/v2-get-api-usage/

GET /v2/getapiusage

API URL: https://bulkapi.zerobounce.net/v2/getapiusage

URL Parameters

  • Parameter
    Description
  • api_key
    Your API Key, found in your account.
  • start_date
    The start date of when you want to view API usage
  • end_date
    The 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.

  • Parameter
    Description
  • total
    Total number of times the API has been called
  • status_valid
    Total valid email addresses returned by the API
  • status_invalid
    Total invalid email addresses returned by the API
  • status_catch_all
    Total catch-all email addresses returned by the API
  • status_do_not_mail
    Total do not mail email addresses returned by the API
  • status_spamtrap
    Total spamtrap email addresses returned by the API
  • status_unknown
    Total unknown email addresses returned by the API
  • sub_status_toxic
    Total number of times the API has a sub status of "toxic"
  • sub_status_disposable
    Total number of times the API has a sub status of "disposable"
  • sub_status_role_based
    Total number of times the API has a sub status of "role_based"
  • sub_status_possible_trap
    Total number of times the API has a sub status of "possible_trap"
  • sub_status_global_suppression
    Total number of times the API has a sub status of "global_suppression"
  • sub_status_timeout_exceeded
    Total number of times the API has a sub status of "timeout_exceeded"
  • sub_status_mail_server_temporary_error
    Total number of times the API has a sub status of "mail_server_temporary_error"
  • sub_status_mail_server_did_not_respond
    Total number of times the API has a sub status of "mail_server_did_not_respond"
  • sub_status_greylisted
    Total number of times the API has a sub status of "greylisted"
  • sub_status_antispam_system
    Total number of times the API has a sub status of "antispam_system"
  • sub_status_does_not_accept_mail
    Total number of times the API has a sub status of "does_not_accept_mail"
  • sub_status_exception_occurred
    Total number of times the API has a sub status of "exception_occurred"
  • sub_status_failed_syntax_check
    Total number of times the API has a sub status of "failed_syntax_check"
  • sub_status_mailbox_not_found
    Total number of times the API has a sub status of "mailbox_not_found"
  • sub_status_unroutable_ip_address
    Total number of times the API has a sub status of "unroutable_ip_address"
  • sub_status_possible_typo
    Total number of times the API has a sub status of "possible_typo"
  • sub_status_no_dns_entries
    Total number of times the API has a sub status of "no_dns_entries"
  • sub_status_role_based_catch_all
    Total role based catch alls the API has a sub status of "role_based_catch_all"
  • sub_status_mailbox_quota_exceeded
    Total number of times the API has a sub status of "mailbox_quota_exceeded"
  • sub_status_forcible_disconnect
    Total forcible disconnects the API has a sub status of "forcible_disconnect"
  • sub_status_failed_smtp_connection
    Total failed SMTP connections the API has a sub status of "failed_smtp_connection"
  • start_date
    Start date of query
  • end_date
    End date of query

Get API Usage Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
      
' Complete API Libraries and Wrappers can be found here: 
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_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"}

    

Get File (v2)

/email-validation-api-quickstart/v2-get-file/

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

  • Parameter
    Description
  • api_key
    Your API Key, found in your account.
  • file_id
    The 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=replacewithyours

GetFile Code Samples

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
      
' 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"
  }
    

Send File (v2)

/email-validation-api-quickstart/v2-send-file/

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

  • Parameter
    Description
  • file
    csv or txt file. Byte array contents for the submitted file. The content's header is type of "text/csv".
  • api_keypi_key
    Your API Key, found in your account. (Required)
  • return_url
    The URL will be used to call back when the validation is completed. (Optional)
  • email_address_column
    The column index of the email address in the file. Index starts from 1. (Required)
  • first_name_column
    The column index of the first name column. (Optional)
  • last_name_column
    The column index of the last name column. (Optional)
  • gender_column
    The column index of the gender column. (Optional)
  • ip_address_column
    The IP Address the email signed up from. (Optional)
  • has_header_row
    If 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

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java
      
' Complete API Libraries and Wrappers can be found here: 
' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_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];
    

//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"
      ]
  }
    

Validate Emails (v2)

/email-validation-api-quickstart/v2-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 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

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

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

  • https://api.zerobounce.net/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:

  • Visual Basic
  • C#
  • PHP
  • Java
  • Python
  • Swift
  • Objective C
  • Android Java

        
  ' Complete API Libraries and Wrappers can be found here: 
  ' https://www.zerobounce.net/docs/zerobounce-api-wrappers/#api_wrappers__v2__dot_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

  • Properties
    Description
  • address
    The email address you are validating.
  • status
    [valid, invalid, catch-all, unknown, spamtrap, abuse, do_not_mail]
  • sub_status
    [antispam_system,
    greylisted, mail_server_temporary_error, forcible_disconnect, mail_server_did_not_respond, timeout_exceeded, failed_smtp_connection, mailbox_quota_exceeded, exception_occurred, possible_traps, role_based, global_suppression, mailbox_not_found, no_dns_entries, failed_syntax_check, possible_typo, unroutable_ip_address, leading_period_removed, does_not_accept_mail, alias_address, role_based_catch_all, disposable, toxic]
  • account
    The portion of the email address before the "@" symbol.
  • domain
    The portion of the email address after the "@" symbol.
  • did_you_mean
    Suggestive Fix for an email typo
  • domain_age_days
    Age 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_record
    The preferred MX record of the domain
  • smtp_provider
    The SMTP Provider of the email or [null] [BETA].
  • 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].
  • 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.
  • Processed_at
    The UTC time the email was validated.

Sandbox Mode (v2)

/email-validation-api-quickstart/v2-sandbox-mode/

To help you test every scenario of status and sub_status codes with the API, we put together a list of emails that will return specific results when used with the API for testing purposes. Testing with these emails will not use any of your credits.

In addition, we also provide an IP address to test with to get GEO-Location results.

You will still need to use your API KEY with these test email addresses.

  • disposable@example.com

  • invalid@example.com

  • valid@example.com

  • toxic@example.com

  • donotmail@example.com

  • spamtrap@example.com

  • abuse@example.com

  • unknown@example.com

  • catch_all@example.com

  • antispam_system@example.com

  • does_not_accept_mail@example.com

  • exception_occurred@example.com

  • failed_smtp_connection@example.com

  • failed_syntax_check@example.com

  • forcible_disconnect@example.com

  • global_suppression@example.com

  • greylisted@example.com

  • leading_period_removed@example.com

  • mail_server_did_not_respond@example.com

  • mail_server_temporary_error@example.com

  • mailbox_quota_exceeded@example.com

  • mailbox_not_found@example.com

  • no_dns_entries@example.com

  • possible_trap@example.com

  • possible_typo@example.com

  • role_based@example.com

  • timeout_exceeded@example.com

  • unroutable_ip_address@example.com

  • free_email@example.com

  • role_based_catch_all@example.com

You can use this IP to test the GEO Location in the API.

99.110.204.1

Please view our status codes documentation to learn more about each status.

Status Codes (v2)

/email-validation-api-quickstart/v2-status-codes/

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).

V2 Changes

/email-validation-api-quickstart/v2-changes/

These are the items that changed between v1 and v2.

  1. Disposable and Toxic emails have been moved under the do_not_mail status with the appropriate sub_status (toxic, disposable)

  2. The "DoNotMail" status was changed to "do_not_mail"

  3. All statuses are now lowercase, instead of mixed case.

  4. We added a free_email property to indicate if the email domain is a free email provider can be used for [fraud prevention].

  5. We added a domain_age_days property, to let you know how old the domain is [fraud prevention].

  6. We added the smtp_provider property for the email domain, this feature is in beta.

  7. We added the mx_found property, to let you know if the domain has an MX record

  8. We added the mx_record property, to tell you the preferred MX record of the domain.

  9. We added the did_you_mean property, which will be populated if a typo is detected with a suggested correction.

  10. apiKey property was changed to api_key

  11. IPAddress property was changed to ip_address

  12. The validatewithip method was removed, it's now part of the validate method

  13. The location property was removed (wasn't being used)

  14. The creation_date property was removed (wasn't being used)

  15. processedat property is now processed_at

  16. We added a new sub_status called "role_based_catch_all"

  17. We added three new API, sendfile, filestatus, and getfile for bulk email validation.