ZeroBounce Android SDK

This SDK contains methods for interacting easily with ZeroBounce API. More information about ZeroBounce you can find in the official documentation.
This SDK is built using the Java 11 version.

Installation

You can install ZeroBounceSDK by adding the dependency to your gradle file:

implementation 'com.zerobounce.android:zerobouncesdk:<latest_version>'

USAGE

Import the sdk in your file:

import com.zerobounce.android.ZeroBounceSDK

Initialize the sdk with your api key:

ZeroBounceSDK.initialize("<YOUR_API_KEY>")

Examples

Then you can use any of the SDK methods, for example:

• Validate an email address

  ZeroBounceSDK.validate(
      "<EMAIL_TO_TEST>",
      "<OPTIONAL_IP_ADDRESS>",
      { rsp ->
          Log.d("MainActivity", "validate rsp: $rsp")
          // your implementation
      },
      { error ->
          Log.e("MainActivity", "validate error: $error")
          // your implementation
      }
  )

• Validate batch a list of email addresses

  val emailsData = listOf(
      ZBValidateBatchData(email = "[email protected]", ip = "1.1.1.1"),
      ZBValidateBatchData(email = "[email protected]", ip = "1.1.1.1"),
      ZBValidateBatchData(email = "[email protected]", ip = null)
  )
  ZeroBounceSDK.validateBatch(
      emailsData,
      { rsp ->
          Log.d("MainActivity", "validateBatch rsp: $rsp")
          // your implementation
      },
      { error ->
          Log.e("MainActivity", "validateBatch error: $error")
          // your implementation
      }
  )

• Find the email and other domain formats based on a given domain name

  ZeroBounceSDK.guessFormat(
      domain = "<DOMAIN_TO_TEST>",
      responseCallback = { rsp ->
          Log.d("MainActivity", "guessFormat rsp: $rsp")
          // your implementation
      },
      errorCallback = { error ->
          Log.e("MainActivity", "guessFormat error: $error")
          // your implementation
      }
  )

• Check how many credits you have left on your account

  ZeroBounceSDK.getCredits(
      { rsp -> 
          Log.d("MainActivity", "getCredits rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "getCredits error: $error") 
          // your implementation
      }
  )

• Check your API usage for a given period of time

  // import java.time.LocalDate
  val startDate = LocalDate.now()    // The start date of when you want to view API usage
  val endDate = LocalDate.now()      // The end date of when you want to view API usage
  
  ZeroBounceSDK.getApiUsage(
      startDate, 
      endDate,
      { rsp -> 
          Log.d("MainActivity", "getApiUsage rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "getApiUsage error: $error") 
          // your implementation
      }
  )

• The sendFile API allows user to send a file for bulk email validation

  // import java.io.File
  val myFile = File("<FILE_PATH>")  // The csv or txt file
  val emailAddressColumn = 3        // The column index of email address in the file. Index starts at 1
  val firstNameColumn = 4           // The column index of first name in the file
  val lastNameColumn = 5            // The column index of last name in the file
  val genderColumn = 6              // The column index of gender in the file
  val ipAddressColumn = 7           // The column index of IP address in the file
  val hasHeaderRow = true           // If this is `true` the first row is considered as table headers 
  val returnUrl = "https://domain.com/called/after/processing/request"
  
  ZeroBounceSDK.sendFile(
      context,
      file,
      returnUrl, 
      firstNameColumn, 
      lastNameColumn,
      genderColumn, 
      ipAddressColumn, 
      hasHeaderRow,
      { rsp ->
          Log.d("MainActivity", "sendFile rsp: $rsp")
          // your implementation
      },
      { error ->
          Log.e("MainActivity", "sendFile error: $error")
          // your implementation
      },
  )

• The getFile API allows users to get the validation results file for the file been submitted using sendFile API

  val fileId = "<FILE_ID>"    // The returned file ID when calling sendfile API
  
  ZeroBounceSDK.getFile(
      context, 
      fileId,
      { rsp -> 
          Log.d("MainActivity", "getfile rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "getfile error: $error") 
          // your implementation
      }
  )

• Check the status of a file uploaded via sendFile method

  val fileId = "<FILE_ID>"    // The returned file ID when calling sendfile API
  
  ZeroBounceSDK.fileStatus(
      context, 
      fileId,
      { rsp -> 
          Log.d("MainActivity", "fileStatus rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "fileStatus error: $error") 
          // your implementation
      }
  )

• Delete the file that was submitted using sendFile API. File can be deleted only when its status is Complete

  val fileId = "<FILE_ID>"   // The returned file ID when calling sendfile API
  
  ZeroBounceSDK.deleteFile(
      context,
      fileId,
      { rsp -> 
          Log.d("MainActivity", "deleteFile rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "deleteFile error: $error") 
          // your implementation
      }
  )

• Gather insights into your subscribers’ overall email engagement. The request returns data regarding opens, clicks, forwards and unsubscribes that have taken place in the past 30, 90, 180 or 365 days.

  ZeroBounceSDK.getActivityData(
      "<EMAIL_TO_TEST>",
      { rsp -> 
          Log.d("MainActivity", "validate rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "validate error: $error") 
          // your implementation
      }
  )

AI Scoring API

• The scoringSendFile API allows user to send a file for bulk email validation

  // import java.io.File
  val myFile = File("<FILE_PATH>")  // The csv or txt file
  val emailAddressColumn = 3        // The column index of email address in the file. Index starts at 1
  val hasHeaderRow = true           // If this is `true` the first row is considered as table headers 
  val returnUrl = "https://domain.com/called/after/processing/request"
  
  ZeroBounceSDK.scoringSendFile(
      context,
      file,
      emailAddressColumn,
      returnUrl, 
      hasHeaderRow,
      { rsp ->
          Log.d("MainActivity", "scoringSendFile rsp: $rsp")
          // your implementation
      },
      { error ->
          Log.e("MainActivity", "scoringSendFile error: $error")
          // your implementation
      }
  )

• The scoringGetFile API allows users to get the validation results file for the file been submitted using scoringSendFile API

  val fileId = "<FILE_ID>"    // The returned file ID when calling scoringSendFile API
  
  ZeroBounceSDK.scoringGetFile(
      context, 
      fileId,
      { rsp -> 
          Log.d("MainActivity", "scoringGetFile rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "scoringGetFile error: $error")
          // your implementation
      }
  )

• Check the status of a file uploaded via scoringSendFile method

  val fileId = "<FILE_ID>"    // The returned file ID when calling scoringSendFile API
  
  ZeroBounceSDK.scoringFileStatus(
      context, 
      fileId,
      { rsp -> 
          Log.d("MainActivity", "scoringFileStatus rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "scoringFileStatus error: $error") 
          // your implementation
      }
  )

• Delete the file that was submitted using scoring scoringSendFile API. File can be deleted only when its status is Complete

  val fileId = "<FILE_ID>"   // The returned file ID when calling scoringSendFile API
  
  ZeroBounceSDK.scoringDeleteFile(
      context, 
      fileId,
      { rsp -> 
          Log.d("MainActivity", "scoringDeleteFile rsp: $rsp")
          // your implementation
      },
      { error -> 
          Log.e("MainActivity", "scoringDeleteFile error: $error") 
          // your implementation
      }
  )

• Find the email formats based on a given first name and domain

  ZeroBounceSDK.findEmail(
      firstName = "<FIRST_NAME_TO_TEST>",
      domain = "<DOMAIN_TO_TEST>",
      responseCallback = { rsp ->
          Log.d("MainActivity", "findEmail rsp: $rsp")
          // your implementation
      },
      errorCallback = { error ->
          Log.e("MainActivity", "findEmail error: $error")
          // your implementation
      }
  )

• Find the email formats based on a given first name and company name

  ZeroBounceSDK.findEmail(
      firstName = "<FIRST_NAME_TO_TEST>",
      companyName = "<COMPANY_NAME_TO_TEST>",
      responseCallback = { rsp ->
          Log.d("MainActivity", "findEmail rsp: $rsp")
          // your implementation
      },
      errorCallback = { error ->
          Log.e("MainActivity", "findEmail error: $error")
          // your implementation
      }
  )

• Find other domain formats based on a given domain

  ZeroBounceSDK.findDomain(
      domain = "<DOMAIN_TO_TEST>",
      responseCallback = { rsp ->
          Log.d("MainActivity", "findDomain rsp: $rsp")
          // your implementation
      },
      errorCallback = { error ->
          Log.e("MainActivity", "findDomain error: $error")
          // your implementation
      }
  )

• Find other domain formats based on a given company name

  ZeroBounceSDK.findDomain(
      companyName = "COMPANY_NAME_TO_TEST",
      responseCallback = { rsp ->
          Log.d("MainActivity", "findDomain rsp: $rsp")
          // your implementation
      },
      errorCallback = { error ->
          Log.e("MainActivity", "findDomain error: $error")
          // your implementation
      }
  )

Documentation

The documentation of the SDK can be generated through a Gradle task. Open the Gradle tab (on the default layout, it should be at the right side of the Android Studio), then go to zero_bounce_sdk > Tasks > documentation and double click on the dokkaHtml task. After it is generated, you can find it in zero_bounce_sdk/build/dokka/html. From there you only have to open the index.html file.

Publication

Every time a new release is created, the CI/CD pipeline will execute and a new artifact will be released on Maven Central. The pipeline updates the version automatically! If you ever change the OSSRH login credentials, you'll need to also update the repository variables on Github.

Local setup for manual release

In order to be able to publish to the Nexus repository from you local machine, you'll need to do a few steps:

1. Create a/Update the local.properties file, in the project root, like this:

   ## This file must *NOT* be checked into Version Control Systems,
   # as it contains information specific to your local configuration.
   #
   # Location of the SDK. This is only used by Gradle.
   # For customization when using a Version Control System, please read the
   # header note.
   #Mon Mar 20 10:30:40 EET 2023
   sdk.dir=<YOUR_ANDROID_SDK_DIR>
   signing.keyId=<THE_LAST_8_DIGITS_OF_YOUR_GPG_KEY>
   signing.password=<YOUR_GPG_PASSWORD>
   signing.key=<YOUR_GPG_PRIVATE_KEY>  # newlines must be replaced with the newline character '\n'
   centralTokenUsername=<YOUR_SONATYPE_CENTRAL_TOKEN_USERNAME>
   centralTokenPassword=<YOUR_SONATYPE_CENTRAL_TOKEN_PASSWORD>
   sonatypeStagingProfileId=<YOUR_SONATYPE_STAGING_PROFILE_ID>

2. Import the GPG key to your local machine (see below)

If you want to manually publish to the Nexus repository (and then release it to Maven Central), you can use the following commands:

# For publishing to the staging repository
./gradlew publishReleasePublicationToSonatypeRepository

# For closing and releasing the artifact.
./gradlew closeAndReleaseSonatypeStagingRepository

Alternatively, you can only execute the first command, then then go to the [Nexus Sonatype] (https://s01.oss.sonatype.org/), login and then open Staging Repositories and click on Refresh. Here you'll see the artifact you just uploaded. In order to publish it, you have to close it and then release it. These actions will take a few minutes to complete. After * releasing* the artifact, it will take:

• a few hours before you can see it on the Maven Repository and on the Sonatype Search
• 1-3 days before you can see it on the MVN Repository

Exporting and importing PGP keys

1. Export the keys:

   gpg --list-keys  # In order to obtain the key hash for the next step
   gpg --export -a <LAST_8_DIGITS> > public.key
   gpg --export-secret-key -a <LAST_8_DIGITS> > private key

2. Import the keys:

   gpg --import public.key
   gpg --import private.key

3. Check that the new keys are imported:

   gpg --list-keys
   gpg --list-secret-keys

Breaking Changes:

guessFormat has been deprecated. To continue using your existing code, you must migrate to findEmail or findDomain . The change is not a simple one-to-one replacement, as the functionality has been split:

• If you were finding a person's email format, use the new findEmail() method.
• If you were only determining the domain's general email pattern, use the new findDomain() method.

Migration Example:

• Old (Deprecated)

  ZeroBounceSDK.guessFormat(
      domain = "<DOMAIN_TO_TEST>",
      responseCallback = { rsp ->
          Log.d("MainActivity", "guessFormat rsp: $rsp")
          // your implementation
      },
      errorCallback = { error ->
          Log.e("MainActivity", "guessFormat error: $error")
          // your implementation
      }
  )

• New Methods

  • Find the email formats based on a given first name and domain

    ZeroBounceSDK.findEmail(
        firstName = "<FIRST_NAME_TO_TEST>",
        domain = "<DOMAIN_TO_TEST>",
        responseCallback = { rsp ->
            Log.d("MainActivity", "findEmail rsp: $rsp")
            // your implementation
        },
        errorCallback = { error ->
            Log.e("MainActivity", "findEmail error: $error")
            // your implementation
        }
    )

  • Find the email formats based on a given first name and company name

    ZeroBounceSDK.findEmail(
        firstName = "<FIRST_NAME_TO_TEST>",
        companyName = "<COMPANY_NAME_TO_TEST>",
        responseCallback = { rsp ->
            Log.d("MainActivity", "findEmail rsp: $rsp")
            // your implementation
        },
        errorCallback = { error ->
            Log.e("MainActivity", "findEmail error: $error")
            // your implementation
        }
    )

  • Find other domain formats based on a given domain

    ZeroBounceSDK.findDomain(
        domain = "<DOMAIN_TO_TEST>",
        responseCallback = { rsp ->
            Log.d("MainActivity", "findDomain rsp: $rsp")
            // your implementation
        },
        errorCallback = { error ->
            Log.e("MainActivity", "findDomain error: $error")
            // your implementation
        }
    )

  • Find other domain formats based on a given company name

    ZeroBounceSDK.findDomain(
        companyName = "COMPANY_NAME_TO_TEST",
        responseCallback = { rsp ->
            Log.d("MainActivity", "findDomain rsp: $rsp")
            // your implementation
        },
        errorCallback = { error ->
            Log.e("MainActivity", "findDomain error: $error")
            // your implementation
        }
    )

New Features and Enhancements

Custom API URL Support

The ZeroBounceSDK.initialize() method now accepts an optional apiBaseUrl parameter. This allows you to specify a custom base URL for the ZeroBounce API.

Migration / Usage

The existing way of initializing the SDK is still valid.

• Default Usage (No Change Required). If you don't provide a URL, the SDK will continue to use the standard ZeroBounce API endpoint:

  ZeroBounceSDK.initialize("<YOUR_API_KEY>")

• Initialize the SDK with your API key and URL:

  ZeroBounceSDK.initialize(apiKey = "<YOUR_API_KEY>", apiBaseUrl = "<YOUR_URL>")

The SDK now exposes a set of predefined constants for different geographical API endpoints, allowing for more precise network routing.

Available API Endpoints

You can specify a custom API base URL during initialization by using the new optional apiBaseUrl parameter in initialize(). For convenience, the following constants are available in the ZBConstants class:

Constant	URL Value	Description
API_DEFAULT_URL	https://api.zerobounce.net/v2/	The global default endpoint.
API_USA_URL	https://api-us.zerobounce.net/v2/	The US-specific endpoint for lower latency in the Americas.
API_EU_URL	https://api-eu.zerobounce.net/v2/	The EU-specific endpoint for compliance and lower latency in Europe.

Usage Example:

To use the EU endpoint for initialization:

ZeroBounceSDK.initialize(apiKey = "<YOUR_API_KEY>", apiBaseUrl = ZBConstants.API_EU_URL)