Get API Usage (v2)

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

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
  //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);
  ?>
    

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();
            }
        }

    }
}
    

  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)
    
    

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

  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);
      });
  });
    

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