Skip to content
Switch branches/tags
Go to file



NeverBounce Logo

Build Status Code Climate

Welcome to NeverBounce's Java SDK! We hope that it will aid you in consuming our service. Please report any bugs to the github issue tracker and make sure you read the documentation before use.



You can use NeverBounce's Java SDK with Maven by adding the following to your pom.xml:



You can use NeverBounce's Java SDK with Ivy by adding the following to your ivy.xml:

<dependency org="com.neverbounce" name="neverbounce-api-java" rev="4.0.13" />


You can use NeverBounce's Java SDK with Gradle by adding the following to your build.gradle in the dependencies block:

compile "com.neverbounce:neverbounce-api-java:4.0.13"


The NeverBounce Java SDK provides a simple interface by which to interact with NeverBounce's email verification API version 4.x. To get up and running, make sure you have your API token on hand:

String token = "my secret API token";
NeverbounceClient neverbounceClient = NeverbounceClientFactory.create(token);

You can also specify API version (v4 is default):

String token = "my secret API token";
String version = "v4.1";
NeverbounceClient neverbounceClient = NeverbounceClientFactory.create(token, version);


And now you're ready to use the client. You can check your account information:

AccountInfoResponse accountInfoResponse = neverbounceClient

You can verify single emails:

SingleCheckResponse singleCheckResponse = neverbounceClient
        .withEmail("") // address to verify
        .withAddressInfo(true)  // return address info with response
        .withCreditsInfo(true)  // return account credits info with response
        .withTimeout(20)  // only wait on slow email servers for 20 seconds max

And you can create, query the status of, and control email verification bulk jobs:

// Note: having an "email" field is mandatory, everything else is optional
Map<String, Object> customData = new LinkedHashMap<String, Object>();
customData.put("email", "");
customData.put("customerId", 1234);
customData.put("name", "Person 1");

Map<String, Object> customData2 = new LinkedHashMap<String, Object>();
customData2.put("email", "");
customData2.put("customerId", 1235);
customData2.put("name", "Person 2");

JobsCreateWithSuppliedJsonRequest.Builder builder = neverbounceClient

JobsCreateResponse jobsCreateResponse = builder

long jobId = jobsCreateResponse.getJobId();

// Job parse
JobsParseResponse jobsParseResponse = neverbounceClient

// Job start
JobsStartResponse jobsStartResponse = neverbounceClient

// Job status
JobsStatusResponse jobsStatusResponse = neverbounceClient


All API operations return a response object with information about the execution of the operation and/or the results of the operation, whichever is more appropriate.

The only exceptions are the JobsResultsResponse and JobsSearchResponse classes. The response generated by these API endpoints is paginated; therefore these functions return custom iterators that allow you to iterate across the API's pagination:

// Paginated job search
int page = 1;
for(;;) {
  JobsSearchResponse jobsSearchResponse = neverbounceClient

  // Handle results here

  if (!jobsSearchResponse.hasNext()) {



NeverbounceClient isn't a concrete class, but it's an interface, which makes it easy to work with in conjunction with 3rd party frameworks like Spring.

XML configuration:

<bean id="neverbounceClient" class="com.neverbounce.api.client.NeverbounceClientFactory" factory-method="create">
  <constructor-arg name="apiKey" type="java.lang.String" value="my secret API token"/>

Java configuration:

public class NeverbounceClientConfig {

  public NeverbounceClient neverbounceClient() {
    return NeverbounceClientFactory.create("my secret API token");



As NeverbounceClient is an interface, so that it can be easily mocked out with test frameworks like Mockito or Spock.

See Also

Documentation for all of the classes of NeverBounce's Java SDK is available through its Javadoc.

Many of the inputs and outputs of the client object's functions map fairly closely to NeverBounce's raw v4 API, reading through the `official API docs<>`_ will be valuable in conjunction with using the Javadoc.