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.

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-java</artifactId>
    <version>4.0.13</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-java" rev="4.0.13" />

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-java:4.0.13"

Usage

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

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("[email protected]") // 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
        .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", "[email protected]");
customData.put("customerId", 1234);
customData.put("name", "Person 1");

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


JobsCreateWithSuppliedJsonRequest.Builder builder = neverbounceClient
        .prepareJobsCreateWithSuppliedJsonRequest();

builder.addInput(customData);
builder.addInput(customData2);
JobsCreateResponse jobsCreateResponse = builder
        .withAutoStart(true)
        .withAutoParse(true)
        .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.

dp-ua / neverbounceapi-java Goto Github PK