API Wrappers

.Net

/zerobounce-api-wrappers/v2-dot-net/

You can find the ZeroBounce .NET API Wrapper v2 on our GitHub - .NET API v2 repository.

You can also easily consume and keep it updated within your Visual Studio Project with Nuget Package Manager: https://www.nuget.org/packages/ZeroBounceAPIWrapperV2/

This wrapper class takes all the work out of coding against the API and allows you to easily set properties and get results instantly.

The .NET API Wrapper takes these input parameters.

The ValidateEmail and GetCredit methods return objects from which you can easily retrieve properties the properties below.

Properties and possible values returned by the methods:

NET API Parameters

  • Property
    Possible Values
  • api_key
    The API key found in your account dashboard
  • emailToValidate
    The email address you are validating
  • ip_address
    [optional] - The IP Address the email was captured from
  • requestTimeOut
    Timeout settings in milliseconds, setting this enables you to control how long you are willing to wait for to send the request to the API. When the timeout occurs an "Unknown" result is returned
  • readTimeOut
    Timeout settings in milliseconds, setting this enables you to control how long you are willing to wait for the API to respond to your request. When the timeout occurs an "Unknown" result is returned

The ValidateEmail and GetCredit methods return objects from which you can easily retrieve properties the properties below.

Properties and possible values returned by the methods:

validate method

  • Property
    Possible Values
  • 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
    toxic
    disposable
    role_based_catch_all
  • 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 or [null]
  • 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 or [null]
  • smtp_provider
    The SMTP Provider of the email or [null] (BETA)
  • 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]
  • country
    The country the IP address is from
  • region
    The state/region the IP address is from
  • city
    The city the IP address is from
  • zipcode
    The Zip Code the IP address is from
  • processed_at
    The UTC time the email was validated

GetCredit method

  • Property
    Possible Values
  • credits
    The number of credits left in account for email validation.

C#


  var zeroBounceAPI = new ZeroBounce.ZeroBounceAPI();

  //set input parameters
  zeroBounceAPI.api_key = "Your API Key"; //Required
  zeroBounceAPI.emailToValidate = "Email address you are validating"; //Required
  zeroBounceAPI.ip_address = "IP address the email signed up with"; //Optional
  
  //Depending on how you use the API, you might want it to time out faster, for example on a registration screen. 
  //Normally the API will return results very fast, but a small percentage of mail servers take
  //upwards of 20+ seconds to respond. 
  //If the API times out, it will return a status of "Unknown" and a sub_status of "timeout_exceeded"  
  
  zeroBounceAPI.readTimeOut = 200000;// "Any integer value in milliseconds
  zeroBounceAPI.requestTimeOut = 150000; // "Any integer value in milliseconds
  
  //validate email and assign results to an object
  var apiProperties = zeroBounceAPI.ValidateEmail();
  
  //check credits and assign results to an object
  var apiCredits= zeroBounceAPI.GetCredits();
  
  //use the properties to make decisions on
  switch (apiProperties.status)
    {
        case "invalid":
            Console.WriteLine("invalid");
            break;
        case "valid":
            Console.WriteLine("valid");
            break;
        default:
            Console.WriteLine(apiProperties.status);
            break;
    }
      

VB .NET

      
      Dim zeroBounceAPI = New ZeroBounce.ZeroBounceAPI

      'set input parameters
      zeroBounceAPI.api_key = "Your API Key" 'Required 
      zeroBounceAPI.emailToValidate = "Email address you are validating" 'Required
      zeroBounceAPI.ip_address = "IP address the email signed up with" 'Optional
      
      'Depending on how you use the API, you might want it to time out faster, for example on a registration screen. 
      'Normally the API will return results very fast, but a small percentage of mail servers 
      'take upwards of 20+ seconds to respond. 
      'If the API times out, it will return a status of "Unknown" and a sub_status of "timeout_exceeded"  
      
      zeroBounceAPI.readTimeOut = 200000 'Any integer value in milliseconds
      zeroBounceAPI.requestTimeOut = 150000 'Any integer value in milliseconds 
      
      
      Dim apiProperties = zeroBounceAPI.ValidateEmail
      Dim apiCredits = zeroBounceAPI.GetCredits
      
      'use the properties to make decisions on
      Select Case (apiProperties.status)
          Case "Invalid"
              Console.WriteLine("Invalid")
          Case "Valid"
              Console.WriteLine("Valid")
          Case Else
              Console.WriteLine(apiProperties.status)
      End Select
      

Java

/zerobounce-api-wrappers/v2-java/

You can find the ZeroBounce Java API v2 on our GitHub - Java API v2.

This is a java wrapper class example for the ZeroBounce API v2.

The project has 2 dependencies:

  • Apache HttpClient
  • JSON (org.json)

Either download the dependencies separately and add them to the relevant path or add the following dependencies to your pom.xml file if you're building via Maven (already added if you're cloning this repo):

Validate(email) method:

  • Properties
    Possible Values
  • getEmailAddress()
    The email address you are validating.
  • getStatus()
    Valid
    Invalid
    Catch-All
    Unknown
    Spamtrap
    Abuse
    DoNotMail
  • getSubStatus()
    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
  • getAccount()
    The portion of the email address before the "@" symbol.
  • getDomain()
    The portion of the email address after the "@" symbol.
  • getDidYouMean()
    Suggestive Fix for an email typo or [null]
  • getDomainAgeDays()
    Age of the email domain in days or [null].
  • isFreeEmail()
    [true/false] If the email comes from a free provider.
  • isMXFound()
    [true/false] Does the domain have an MX record.
  • getMXRecord()
    The preferred MX record of the domain or [null].
  • getSMTPProvider()
    The SMTP Provider of the email or [null] (BETA).
  • getFirstName()
    The first name of the owner of the email when available or [null].
  • getLastName()
    The last name of the owner of the email when available or [null].
  • getGender()
    The gender of the owner of the email when available or [null].
  • getCountry()
    The country the IP address is from.
  • getCity()
    The city the IP address is from.
  • getZipcode()
    The zip code the IP address is from.
  • getRegion()
    The region/state the IP address is from.
  • getProcessedAt()
    The UTC time the email was validated.

getCredit() method

  • Properties
    Possible Values
  • getCredits()
    The number of credits left in account for email validation
      
      Dim zeroBounceAPI = New ZeroBounce.ZeroBounceAPI

      'set input parameters
      zeroBounceAPI.api_key = "Your API Key" 'Required 
      zeroBounceAPI.emailToValidate = "Email address you are validating" 'Required
      zeroBounceAPI.ip_address = "IP address the email signed up with" 'Optional
      
      'Depending on how you use the API, you might want it to time out faster, for example on a registration screen. 
      'Normally the API will return results very fast, but a small percentage of mail servers 
      'take upwards of 20+ seconds to respond. 
      'If the API times out, it will return a status of "Unknown" and a sub_status of "timeout_exceeded"  
      
      zeroBounceAPI.readTimeOut = 200000 'Any integer value in milliseconds
      zeroBounceAPI.requestTimeOut = 150000 'Any integer value in milliseconds 
      
      
      Dim apiProperties = zeroBounceAPI.ValidateEmail
      Dim apiCredits = zeroBounceAPI.GetCredits
      
      'use the properties to make decisions on
      Select Case (apiProperties.status)
          Case "Invalid"
              Console.WriteLine("Invalid")
          Case "Valid"
              Console.WriteLine("Valid")
          Case Else
              Console.WriteLine(apiProperties.status)
      End Select
      

Javascript

/zerobounce-api-wrappers/v2-javascript/

You can find the ZeroBounce JavaScript API v2 on our GitHub - JavaScript API v2.

The validate and getCredits methods return objects from which you can easily retrieve properties the properties below.

Properties and possible values returned by the methods:

validate method

  • Property
    Possible Values
  • 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
    toxic
    disposable
    role_based_catch_all
  • 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 or [null]
  • 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 or [null]
  • smtp_provider
    The SMTP Provider of the email or [null] (BETA)
  • 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]
  • country
    The country the IP address is from
  • region
    The state/region the IP address is from
  • city
    The city the IP address is from
  • zipcode
    The Zip Code the IP address is from
  • processed_at
    The UTC time the email was validated

GetCredit method

  • Property
    Possible Values
  • credits
    The number of credits left in account for email validation.

  var ZeroBounceApi = new ZeroBounceApi(apiKey)
  ZeroBounceApi.apiKey
  ZeroBounceApi.getCredits()
  ZeroBounceApi.validate("some@email.com", "some.ip.address can be blank")
      

Python

/zerobounce-api-wrappers/v2-python/

You can find the ZeroBounce Python API v2 on our GitHub - Python API v2

Example usage

The validate and get_credit methods return objects from which you can easily retrieve properties the properties below.

Properties and possible values returned by the methods:

validate method

  • Property
    Possible Values
  • 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
    toxic
    disposable
    role_based_catch_all
  • 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 or [null]
  • 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 or [null]
  • smtp_provider
    The SMTP Provider of the email or [null] (BETA)
  • 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]
  • country
    The country the IP address is from
  • region
    The state/region the IP address is from
  • city
    The city the IP address is from
  • zipcode
    The Zip Code the IP address is from
  • processed_at
    The UTC time the email was validated

GetCredit method

  • Property
    Possible Values
  • credits
    The number of credits left in account for email validation.

  from zerobounce import ZeroBounceAPI

  zba = ZeroBounceAPI('yourapikey____________')
  print zba.get_credits()
  resp1 = zba.validate('flowerjill@aol.com','123.145.124.12')
  
  print resp1
  {
  "address":"flowerjill@aol.com",
  "status":"valid",
  "sub_status":"",
  "free_email":True,
  "did_you_mean":None,
  "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"
  }
  
  print resp.firstname
  Jill
  
  print resp2.status
  valid
      
      

PHP

/zerobounce-api-wrappers/v2-php/

You can find the ZeroBounce PHP API on our GitHub - PHP API v2.

This is a PHP wrapper class example for the ZeroBounce API.

  • TLS V1.2 is required - This is available from PHP 5.5.19 and up.

Example usage:

The validation methods return objects on which you call get methods which return the relevant information. Please see the sample code on the right:

The validate and getCredits methods return objects from which you can easily retrieve properties the properties below.

Properties and possible values returned by the methods:

validate method

  • Property
    Possible Values
  • 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
    toxic
    disposable
    role_based_catch_all
  • 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 or [null]
  • 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 or [null]
  • smtp_provider
    The SMTP Provider of the email or [null] (BETA)
  • 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]
  • country
    The country the IP address is from
  • region
    The state/region the IP address is from
  • city
    The city the IP address is from
  • zipcode
    The Zip Code the IP address is from
  • processed_at
    The UTC time the email was validated

GetCredit method

  • Property
    Possible Values
  • credits
    The number of credits left in account for email validation.

  <?php
  require_once("zerobounce.php");
  
  $zba = new ZeroBounceAPI('YOUR_API_KEY');
  
  //print the credit balance
  print_r($zba->get_credits());
  
  //instantiate a validation object following a call to 
  //validate and print individual elements
  $validation = $zba->validate('email@address.com', 'IP can be blank');
  echo $validation['address'];
  echo $validation['status'];
  print_r($zba->validate('email@address.com', 'IP'));
  ?>
      

PHP 7

/zerobounce-api-wrappers/v2-php7/

You can find this User Contributed PHP7 wrapper at https://github.com/nickdnk/zerobounce-php

Prerequisites You need an active account at https://zerobounce.net to use this library. From there, grab your API Key under API - Keys & Info.

Installation To include this in your project, install it using Composer.

As we use return types and type hints, this library requires PHP 7.1.

composer require nickdnk/zerobounce-php

Tests Enter your API key into the ZeroBounceTest file and run it. This uses the test-emails supplied by ZeroBounce and will not cost you credit.


  use nickdnkZeroBounceEmail;
  use nickdnkZeroBounceResult;
  use nickdnkZeroBounceZeroBounce;
  
  // You can modify the timeout using the second parameter. Default is 15.
  $handler = new ZeroBounce('my_api_key', 30);
  
  $email = new Email(
  
      // The email address you want to check
      'some-email@domain.com',
  
      // and if you have it, the IP address - otherwise null or omitted
      '123.123.123.123'
  
  );
  
  try {
  
      // Validate the email
      $result = $handler->validateEmail($email);
  
      if ($result->getStatus() === Result::STATUS_VALID) {
  
          // All good
  
          if ($result->isFreeEmail()) {
  
              // Email address is free, such as @gmail.com, @hotmail.com.
  
          }
  
          /**
          * The user object contains metadata about the email address
          * supplied by ZeroBounce. All of these may be null or empty
          * strings, so remember to check for that. 
          */
          $user = $result->getUser();
  
          $user->getCountry();
          $user->getRegion();
          $user->getZipCode();
          $user->getCity();
          $user->getGender();
          $user->getFirstName();
          $user->getLastName();
  
      } else if ($result->getStatus() === Result::STATUS_DO_NOT_MAIL) {
  
          // The substatus code will help you determine the exact issue:
  
          switch ($result->getSubStatus()) {
  
              case Result::SUBSTATUS_DISPOSABLE:
              case Result::SUBSTATUS_TOXIC:
                  // Toxic or disposable.
                  break;
  
  
              case Result::SUBSTATUS_ROLE_BASED:
                  // admin@, helpdesk@, info@ etc; not a personal email
                  break;
  
              // ... and so on.
  
          }
  
      } else if ($result->getStatus() === Result::STATUS_INVALID) {
  
          // Invalid email.
  
      } else if ($result->getStatus() === Result::STATUS_SPAMTRAP) {
  
          // Spam-trap.
  
      } else if ($result->getStatus() === Result::STATUS_ABUSE) {
  
          // Abuse.
  
      } else if ($result->getStatus() === Result::STATUS_CATCH_ALL) {
  
          // Address is catch-all; not necessarily a private email.
  
      } else if ($result->getStatus() === Result::STATUS_UNKNOWN) {
  
          // Unknown email status.
  
      }
  
      /*
      * To find out how to use and react to different status and
      * substatus codes, see the ZeroBounce documentation at:
      * https://www.zerobounce.net/docs/?swift#version-2__v2__
      */
  
  } catch (
ickdnkZeroBounceAPIError $exception) {
  
    // Something happened. Perhaps a bad API key or insufficient credit.
  
  }