JarCastingNeverBounceApi-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.
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.
