NeverBounceApi-Java

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.

This library is for use with NeverBounce's V4 API which is currently in beta

Installation

Maven

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

<dependencies>
  <dependency>
    <groupId>com.neverbounce</groupId>
    <artifactId>neverbounce-api-client</artifactId>
    <version>4.0.0-RELEASE</version>
  </dependency>
</dependencies>

Ivy

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

<dependency org="com.neverbounce" name="neverbounce-api-client" rev="4.0.0-RELEASE" />

Gradle

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-client:4.0.0-RELEASE"

Usage

The NeverBounce Java SDK provides a simple interface by which to interact with NeverBounce's email verification API version 4. 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);

Examples

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

AccountInfoResponse accountInfoResponse = neverbounceClient
    .createAccountInfoRequest()
    .execute();

You can verify single emails:

SingleCheckResponse singleCheckResponse = neverbounceClient
        .prepareSingleCheckRequest()
        .withEmail("github@laszlocsontos.com")
        .withAddressInfo(true)
        .withCreditsInfo(true)
        .withTimeout(300)
        .build()
        .execute();

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", "carrot@veggies.com");
customData.put("customerId", 1234);
customData.put("subscriptionType", "PAID");

JobsCreateResponse jobsCreateResponse = neverbounceClient
    .prepareJobsCreateWithSuppliedJsonRequest()
    .addInput("tomato@veggies.com", "Tomato")
    .addInput("id-1234", "cucumber@veggies.com", "Cucumber")
    .addInput(customData)
    .withFilename("test.csv")
    .build()
    .execute();

long jobId = jobsCreateResponse.getJobId();

// Job parse
JobsParseResponse jobsParseResponse = neverbounceClient
    .prepareJobsParseRequest()
    .withJobId(jobId)
    .withAutoStart(false)
    .build()
    .execute();

// Job start
JobsStartResponse jobsStartResponse = neverbounceClient
    .prepareJobsStartRequest()
    .withJobId(jobId)
    .build()
    .execute();

// Job status
JobsStatusResponse jobsStatusResponse = neverbounceClient
    .prepareJobsStatusRequest()
    .withJobId(jobId)
    .build()
    .execute();

System.out.println(jobsStatusResponse.getPercentComplete());

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
      .prepareJobsSearchRequest()
      .withJobId(jobId)
      .withPage(page)
      .build()
      .execute();

  // Handle results here
  processResults(jobsSearchResponse.getResults());

  if (!jobsSearchResponse.hasNext()) {
    break;
  }

  page++;
}

Integration

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

Java configuration:

@Configuration
public class NeverbounceClientConfig {

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

}

Testing

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<https://developers.neverbounce.com/v4.0/reference#account>`_ will be valuable in conjunction with using the Javadoc.