GitHub - zerobounce/zero-bounce-java-sdk-setup: ZeroBounce Java SDK Setup

ZeroBounce Java SDK

Security

Keep API keys on a trusted server. Do not embed them in mobile apps or browser JavaScript that untrusted users can inspect.
Custom API base URLs (when supported) must use https://. Do not pass end-user-controlled hosts into those settings.
Request URLs include api_key as a query parameter (ZeroBounce API contract). Do not log full request URLs or enable payload debug logging in production.

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 21 version.

Installation

You can install ZeroBounceSDK by adding the dependency to your pom.xml file:

<dependency>
    <groupId>com.zerobounce.java</groupId>
    <artifactId>zerobouncesdk</artifactId>
    <version><latest_version></version>
</dependency>

How to use the sample project

Build the JAR file for the SDK project.
Make sure there's no other JAR located in the maven cache file. On my machine, it is located here: ~/.m2/repository/com/zerobounce/java/zerobouncesdk/

Run the following command from the root of the project:

mvn org.apache.maven.plugins:maven-install-plugin:2.3.1:install-file \
    -Dfile=zero-bounce-sdk/out/artifacts/zerobouncesdk_jar/zerobouncesdk.jar \
    -DgroupId=com.zerobounce.java \
    -DartifactId=zerobouncesdk \
    -Dversion=<latest_version> \
    -Dpackaging=jar \
    -DlocalRepositoryPath=local-libs

Run mvn clean dependency:purge-local-repository in the Sample project.
Run mvn compile in the Sample project.
Rebuild the Sample project.
Run & enjoy!

How to use the SDK from this repository in your project

We highly recommend you use the latest version available on Maven. However, if you plan on bundling the repository version of the SDK in your project, then here's what you need to do:

Create a folder named local-libs in the root of your project, that will act as a "local" repository.

In your pom.xml file paste the following code that will use a "local" repository:

<repositories>
    <repository>
        <id>local-repo</id>
        <name>Local Repo</name>
        <url>file://${project.basedir}/local-libs</url>
    </repository>
</repositories>

Inside the <dependencies></dependencies> block, paste the following code:

<dependency>
    <groupId>com.zerobounce.java</groupId>
    <artifactId>zerobouncesdk</artifactId>
    <version><latest_version></version>
</dependency>

Follow steps 1-5 from the How to use the sample project above.
Rebuild the project.
Enjoy!

How to deploy the SDK

Be sure to set the autoReleaseAfterClose field to false in the pom.xml file of the zero-bounce-sdk if you don't want the artifact to be automatically deployed on Maven Central.
Use the command: mvn --no-transfer-progress --batch-mode -Dgpg.passphrase=<YOUR_PASSPHRASE> clean deploy -Prelease from the zero-bounce-sdk folder.

Sample app vs. published SDK

The JavaFX sample at the repository root (pom.xml, com.zerobounceexample:zero-bounce-java-sdk-setup-master) depends on com.zerobounce.java:zerobouncesdk from Maven Central with a pinned <version>, not on the zero-bounce-sdk submodule. After you publish a new SDK release, bump that version in the root pom.xml so the demo matches what users install from Central. Dependabot may open a pull request for that bump; if not, update the version manually so we do not forget.

USAGE

Initialize the sdk with your api key:

ZeroBounceSDK.getInstance().initialize("<YOUR_API_KEY>");

ZeroBounceSDK.getInstance().initialize("<YOUR_API_KEY>", timeoutInMillis);

ZeroBounceSDK.getInstance().initialize("<YOUR_API_KEY>", "<YOUR_API_BASE_URL>");

Controlling SDK logging

The SDK is silent by default so it never emits Personally Identifiable Information (PII) unless you explicitly opt in. To integrate the SDK with your application's logging framework, register a ZBLogger implementation before issuing any API calls. The helper class ZBLoggers adapts java.util.logging (JUL) out of the box:

import com.zerobounce.ZBLoggers;

ZeroBounceSDK.setLogger(
    ZBLoggers.jul(java.util.logging.Logger.getLogger("ZeroBounceSDK"))
);

// Optional: enable verbose payload logging for troubleshooting only.
ZeroBounceSDK.setLogPayloads(true);

Passing null to ZeroBounceSDK.setLogger(...) resets the logger to a no-op implementation, which disables SDK logging again.

Bulk API v2 types

ZBFileStatusResponse – Includes errorReason when present, and filePhase2Status (file_phase_2_status) when the bulk API returns it (for example after optional phase 2 processing).
ZBDownloadType – PHASE_1, PHASE_2, or COMBINED for bulk getfile query parameter download_type (validation and scoring).
ZBGetFileOptions – Optional downloadType and activityData for validation getFile; scoringGetFile uses downloadType only (activityData is not sent).

Examples

Note: The snippets below print responses for demonstration purposes. Avoid logging raw API data that may contain PII in production systems.

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

Validate an email address

ZeroBounceSDK.getInstance().validate(
    "<ANY_EMAIL_ADDRESS>",
    "<OPTIONAL_IP_ADDRESS>",
    new ZeroBounceSDK.OnSuccessCallback<ZBValidateResponse>() {
        @Override
        public void onSuccess(ZBValidateResponse response) {
            System.out.println("validate response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("validate error=" + errorMessage);
        }
    });
);

Validate batch a list of email addresses

List<ZBValidateBatchData> emailsData = new ArrayList<ZBValidateBatchData>();
emailsData.add(new ZBValidateBatchData("valid@example.com", "1.1.1.1"));
emailsData.add(new ZBValidateBatchData("invalid@example.com", "1.1.1.1"));
emailsData.add(new ZBValidateBatchData("disposable@example.com", null));

ZeroBounceSDK.getInstance().validateBatch(
    emailsData,
    new ZeroBounceSDK.OnSuccessCallback<ZBValidateBatchResponse>() {
        @Override
        public void onSuccess(ZBValidateBatchResponse response) {
            System.out.println("validateBatch response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("validateBatch error=" + errorMessage);
        }
    });
);

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

ZeroBounceSDK.getInstance().guessFormat(
    "<DOMAIN_TO_TEST>",
    null,
    null,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBEmailFinderResponse>() {
        @Override
        public void onSuccess(ZBEmailFinderResponse response) {
            System.out.println("guessFormat response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("guessFormat error=" + errorMessage);
        }
    });
);

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

ZeroBounceSDK.getInstance().findEmail(
    "<FIRST_NAME_TO_TEST>"
    "<DOMAIN_TO_TEST>",
    null,
    null,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBFindEmailResponse>() {
        @Override
        public void onSuccess(ZBFindEmailResponse response) {
            System.out.println("findEmail response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findEmail error=" + errorMessage);
        }
    });
);

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

ZeroBounceSDK.getInstance().findEmail(
    "<FIRST_NAME_TO_TEST>"
    null,
    "<COMPANY_NAME_TO_TEST>",
    null,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBFindEmailResponse>() {
        @Override
        public void onSuccess(ZBFindEmailResponse response) {
            System.out.println("findEmail response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findEmail error=" + errorMessage);
        }
    });
);

Find other domain formats based on a given domain

ZeroBounceSDK.getInstance().findDomain(
    "<DOMAIN_TO_TEST>",
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBFindDomainResponse>() {
        @Override
        public void onSuccess(ZBFindDomainResponse response) {
            System.out.println("findDomain response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findDomain error=" + errorMessage);
        }
    });
);

Find other domain formats based on a given company name

ZeroBounceSDK.getInstance().findDomain(
    null,
    "COMPANY_NAME_TO_TEST",
    new ZeroBounceSDK.OnSuccessCallback<ZBFindDomainResponse>() {
        @Override
        public void onSuccess(ZBFindDomainResponse response) {
            System.out.println("findDomain response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findDomain error=" + errorMessage);
        }
    });
);

Check how many credits you have left on your account

ZeroBounceSDK.getInstance().getCredits(
    new ZeroBounceSDK.OnSuccessCallback<ZBCreditsResponse>() {
        @Override
        public void onSuccess(ZBCreditsResponse response) {
            System.out.println("getCredits response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("getCredits error=" + errorMessage);
        }
    });

Check your API usage for a given period of time

Date startDate = new Date();    // The start date of when you want to view API usage
Date endDate = new Date();      // The end date of when you want to view API usage

ZeroBounceSDK.getInstance().getApiUsage(
    startDate, 
    endDate, 
    new ZeroBounceSDK.OnSuccessCallback<ZBGetApiUsageResponse>() {
        @Override
        public void onSuccess(ZBGetApiUsageResponse response) {
            System.out.println("getApiUsage response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("getApiUsage error=" + errorMessage);
        }
    });

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

File myFile = new File("<FILE_PATH>");  // The csv or txt file
int emailAddressColumn = 3;             // The column index of the email address in the file. Index starts at 1

ZeroBounceSDK.getInstance().sendFile(
    myFile,
    emailAddressColumn,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBSendFileResponse>() {
        @Override
        public void onSuccess(ZBSendFileResponse response) {
            System.out.println("sendFile response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("sendFile error=" + errorMessage);
        }
    });

Bulk validation uses https://bulkapi.zerobounce.net/v2. See v2 send file, v2 file status, and v2 get file.

Optional multipart field allow_phase_2 (validation bulk only): use ZeroBounceSDK.SendFileOptions and setAllowPhase2(Boolean):

ZeroBounceSDK.SendFileOptions opts = new ZeroBounceSDK.SendFileOptions()
        .setAllowPhase2(true);

ZeroBounceSDK.getInstance().sendFile(
    myFile,
    emailAddressColumn,
    opts,
    successCallback,
    errorCallback);

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

String fileId = "<FILE_ID>";                    // The returned file ID when calling sendfile API
String downloadPath = "<FILE_DOWNLOAD_PATH>";   // The path where the file will be downloaded

ZeroBounceSDK.getInstance().getFile(
    fileId,
    downloadPath,
    new ZeroBounceSDK.OnSuccessCallback<ZBGetFileResponse>() {
        @Override
        public void onSuccess(ZBGetFileResponse response) {
            System.out.println("getfile response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("getfile error=" + errorMessage);
        }
    });

Optional query parameters (validation getFile only for activity data; scoringGetFile does not send activity_data):

import com.zerobounce.ZBDownloadType;
import com.zerobounce.ZBGetFileOptions;

ZBGetFileOptions getOpts = new ZBGetFileOptions()
        .setDownloadType(ZBDownloadType.COMBINED)
        .setActivityData(true);

ZeroBounceSDK.getInstance().getFile(
    fileId,
    downloadPath,
    getOpts,
    successCallback,
    errorCallback);

ZeroBounceSDK.getInstance().scoringGetFile(
    fileId,
    downloadPath,
    new ZBGetFileOptions().setDownloadType(ZBDownloadType.PHASE_2),
    successCallback,
    errorCallback);

phase_2 / combined downloads apply when phase 2 was enabled for the file and file_phase_2_status is Complete. JSON error bodies may still use HTTP 200; the SDK surfaces them via the failure callback.

Check the status of a file uploaded via sendFile API

String fileId = "<FILE_ID>";    // The returned file ID when calling sendfile API

ZeroBounceSDK.getInstance().fileStatus(
    fileId,
    new ZeroBounceSDK.OnSuccessCallback<ZBFileStatusResponse>() {
        @Override
        public void onSuccess(ZBFileStatusResponse response) {
            System.out.println("fileStatus response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("fileStatus error=" + errorMessage);
        }
    });

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

String fileId = "<FILE_ID>";    // The returned file ID when calling sendfile API

ZeroBounceSDK.getInstance().deleteFile(
    fileId,
    new ZeroBounceSDK.OnSuccessCallback<ZBDeleteFileResponse>() {
        @Override
        public void onSuccess(ZBDeleteFileResponse response) {
            System.out.println("deleteFile response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("deleteFile error=" + errorMessage);
        }
    });

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.getInstance().getActivityData(
    "<ANY_EMAIL_ADDRESS>",
    new ZeroBounceSDK.OnSuccessCallback<ZBActivityDataResponse>() {
        @Override
        public void onSuccess(ZBActivityDataResponse response) {
            System.out.println("getActivityData response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("getActivityData error=" + errorMessage);
        }
    });

AI Scoring API

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

File myFile = new File("<FILE_PATH>");  // The csv or txt file
int emailAddressColumn = 3;             // The column index of the email address in the file. Index starts at 1

ZeroBounceSDK.getInstance().scoringSendFile(
    myFile,
    emailAddressColumn,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBSendFileResponse>() {
        @Override
        public void onSuccess(ZBSendFileResponse response) {
            System.out.println("scoringSendFile response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("scoringSendFile error=" + errorMessage);
        }
    });

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

String fileId = "<FILE_ID>";                    // The returned file ID when calling scoringSendfile API
String downloadPath = "<FILE_DOWNLOAD_PATH>";   // The path where the file will be downloaded

ZeroBounceSDK.getInstance().scoringGetFile(
    fileId,
    downloadPath,
    new ZeroBounceSDK.OnSuccessCallback<ZBGetFileResponse>() {
        @Override
        public void onSuccess(ZBGetFileResponse response) {
            System.out.println("scoringGetfile response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("scoringGetfile error=" + errorMessage);
        }
    });

Check the status of a file uploaded via scoringSendFile API

String fileId = "<FILE_ID>";    // The returned file ID when calling scoringSendfile API

ZeroBounceSDK.getInstance().scoringFileStatus(
    fileId,
    new ZeroBounceSDK.OnSuccessCallback<ZBFileStatusResponse>() {
        @Override
        public void onSuccess(ZBFileStatusResponse response) {
            System.out.println("scoringFileStatus response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("scoringFileStatus error=" + errorMessage);
        }
    });

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

String fileId = "<FILE_ID>";    // The returned file ID when calling scoringSendfile API

ZeroBounceSDK.getInstance().scoringDeleteFile(
    fileId,
    new ZeroBounceSDK.OnSuccessCallback<ZBDeleteFileResponse>() {
        @Override
        public void onSuccess(ZBDeleteFileResponse response) {
            System.out.println("scoringDeleteFile response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("scoringDeleteFile error=" + errorMessage);
        }
    });

Validate options

validate has an overload that takes ZBValidateOptions. An option left unset is not sent, and booleans go on the wire as the strings "true"/"false".

ZBValidateOptions options = new ZBValidateOptions()
        .setTimeout(30)                 // 3-60 seconds
        .setActivityData(true)          // fills getActiveInDays() / getActiveFirstSeen()
        .setVerifyPlus(true)
        .setDomainInfo(true)            // fills getDomainWebsiteExists() / getDomainRegistrantCompanyName()
        .setGreylistProcessing(true)
        .setCallbackUrl("https://example.com/greylist")
        .setUsePost(true);              // form-encoded POST /v2/validate instead of GET

ZeroBounceSDK.getInstance().validate("<EMAIL>", null, options,
        response -> System.out.println(response),
        error -> System.out.println(error.getErrors()));

setCallbackUrl is where the greylist retry posts its result, so it is rejected without setGreylistProcessing(true) — before any request is sent. While that retry is still running the API answers with a Message instead of a result, which lands on response.getMessage().

Real-time AI scoring

ZeroBounceSDK.getInstance().scoreEmail("<EMAIL>", onSuccess, onError);        // GET /v2/scoring
ZeroBounceSDK.getInstance().scoreEmail("<EMAIL>", true, onSuccess, onError);  // form-encoded POST

Filters

ZeroBounceSDK.getInstance().addFilter("exclude", "domain", "example.com", onSuccess, onError);
ZeroBounceSDK.getInstance().listFilters(false, onSuccess, onError); // true sends a POST
ZeroBounceSDK.getInstance().deleteFilter("exclude", "domain", "example.com", onSuccess, onError);

S3 and SFTP/FTP bulk

Queue a job on a file that already sits in your Amazon S3 bucket, or on your SFTP/FTP server. See the S3 and SFTP docs. These live on the bulkapi host without the /v2 path.

ZeroBounceSDK zb = ZeroBounceSDK.getInstance();

// Amazon S3. The file name is the full path, as returned by listS3Files.
zb.listS3Files(null, null, onSuccess, onError);   // optional bucket, search

// file_name and return_url are required on every one of these jobs.
ZBBulkFileJobOptions s3 = new ZBBulkFileJobOptions()
        .setFileName("lists/leads.csv")
        .setHasHeaderRow(true)
        .setReturnUrl("https://example.com/zerobounce-done");

zb.validateS3File(s3, onSuccess, onError);
zb.scoreS3File(s3, onSuccess, onError);
zb.emailFinderS3File(s3, onSuccess, onError);
zb.domainSearchS3File(s3, onSuccess, onError);
zb.exportS3File("<FILE_ID>", "my-export-bucket", onSuccess, onError);

// SFTP/FTP. The server, path and protocol come from your ZeroBounce settings.
// The docs list file_name as optional for validateSFTPFile, but the live API
// requires it there too.
ZBBulkFileJobOptions sftp = new ZBBulkFileJobOptions()
        .setFileName("my_file.txt")
        .setReturnUrl("https://example.com/zerobounce-done");

zb.validateSFTPFile(sftp, onSuccess, onError);
zb.scoreSFTPFile(sftp, onSuccess, onError);
zb.emailFinderSFTPFile(sftp, onSuccess, onError);
zb.domainSearchSFTPFile(sftp, onSuccess, onError);

// Note the field: this one takes export_path, not export_bucket.
// Pass null to use the export path from your settings.
zb.exportSFTPFile("<FILE_ID>", "/exports", onSuccess, onError);

List evaluator

The list evaluator has its own base URL, not a path built from the bulk one, and the file id is URL-encoded as a single path segment.

ZeroBounceSDK.getInstance().getListEvaluatorResult("<FILE_ID>", onSuccess, onError);

// Submit a finished evaluation for validation. This takes the evaluator's
// file_id as a form field, not a file upload.
ZeroBounceSDK.getInstance().sendEvaluatedFile("<FILE_ID>", onSuccess, onError);

Inbox Placement Tester

Runs on its own host, authenticates with an Authorization: Bearer header, and sends camelCase JSON bodies. It spends the account's inbox-test credits.

ZeroBounceSDK zb = ZeroBounceSDK.getInstance();

zb.getInboxPlacementProviders(onSuccess, onError);
zb.getInboxPlacementTestTypes(onSuccess, onError);

zb.createInboxPlacementTest("Launch",
        new ZeroBounceSDK.CreateInboxPlacementTestOptions()
                .setTestType(1)
                .setSenderEmail("news@example.com")
                .setWebhookUrl("https://example.com/ipt-webhook"),
        onSuccess, onError);

// Send your campaign to the seeds you got back, then read the results.
zb.getInboxPlacementTest("<TEST_ID>", onSuccess, onError);

zb.listInboxPlacementTests(
        new ZeroBounceSDK.ListInboxPlacementTestsOptions().setStatus("finished").setPage(1),
        onSuccess, onError);
zb.setInboxPlacementWebhook("https://example.com/ipt-webhook", onSuccess, onError);
zb.getInboxPlacementWebhook(onSuccess, onError);
zb.deleteInboxPlacementTest("<TEST_ID>", onSuccess, onError);

Per-API base URLs

The list evaluator and the Inbox Placement Tester are separate hosts, so overriding the main base URL alone leaves them pointing at the live API.

ZeroBounceSDK.getInstance().initialize(
        "<API_KEY>",
        "https://api.zerobounce.net/v2",
        "https://bulkapi.zerobounce.net/v2/listevaluator",
        "https://bulkapi.zerobounce.net/api/ipt");

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.getInstance().guessFormat(
    "<DOMAIN_TO_TEST>",
    null,
    null,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBEmailFinderResponse>() {
        @Override
        public void onSuccess(ZBEmailFinderResponse response) {
            System.out.println("guessFormat response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("guessFormat error=" + errorMessage);
        }
    });
);

New Methods

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

ZeroBounceSDK.getInstance().findEmail(
    "<FIRST_NAME_TO_TEST>"
    "<DOMAIN_TO_TEST>",
    null,
    null,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBFindEmailResponse>() {
        @Override
        public void onSuccess(ZBFindEmailResponse response) {
            System.out.println("findEmail response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findEmail error=" + errorMessage);
        }
    });
);

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

ZeroBounceSDK.getInstance().findEmail(
    "<FIRST_NAME_TO_TEST>"
    null,
    "<COMPANY_NAME_TO_TEST>",
    null,
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBFindEmailResponse>() {
        @Override
        public void onSuccess(ZBFindEmailResponse response) {
            System.out.println("findEmail response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findEmail error=" + errorMessage);
        }
    });
);

Find other domain formats based on a given domain

ZeroBounceSDK.getInstance().findDomain(
    "<DOMAIN_TO_TEST>",
    null,
    new ZeroBounceSDK.OnSuccessCallback<ZBFindDomainResponse>() {
        @Override
        public void onSuccess(ZBFindDomainResponse response) {
            System.out.println("findDomain response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findDomain error=" + errorMessage);
        }
    });
);

Find other domain formats based on a given company name

ZeroBounceSDK.getInstance().findDomain(
    null,
    "COMPANY_NAME_TO_TEST",
    new ZeroBounceSDK.OnSuccessCallback<ZBFindDomainResponse>() {
        @Override
        public void onSuccess(ZBFindDomainResponse response) {
            System.out.println("findDomain response=" + response.toString());
        }
    }, new ZeroBounceSDK.OnErrorCallback() {
        @Override
        public void onError(String errorMessage) {
            System.out.println("findDomain error=" + errorMessage);
        }
    });
);

New Features and Enhancements

Custom API URL Support

The ZeroBounceSDK.initialize() method can now accepts an 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.getInstance().initialize("<YOUR_API_KEY>");

ZeroBounceSDK.getInstance().initialize("<YOUR_API_KEY>", timeoutInMillis);

Initialize the SDK with your API key and URL:

ZeroBounceSDK.getInstance().initialize("<YOUR_API_KEY>", "<YOUR_API_BASE_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.getInstance().initialize("<YOUR_API_KEY>", ZBConstants.getInstance().API_EU_URL);

Testing

Run tests with Docker

From the sdk-docs/ folder in the SDKs monorepo:

cd sdk-docs
docker compose build java
docker compose run --rm java

You can also build from this repository root: docker build -t zerobounce-java-sdk:test . (uses .dockerignore to exclude target/, IDE files, and local-libs).

Run tests (local)

From the zero-bounce-sdk module directory:

cd zero-bounce-sdk
mvn test

Or with the Maven wrapper: ./mvnw test.

Documentation

You can generate the documentation using your desired IDE or using's maven's javadoc command.

Publication

Publishing to Maven Central is done via the GitHub Actions publish workflow, triggered manually per tag. It does not run automatically on release creation.

Version the project and create a git tag (e.g. v1.1.6), then push the tag.
In the repo go to Actions → Publish, click Run workflow, enter the tag (e.g. v1.1.6), and run.
The workflow runs tests and publishes to Maven Central.

If you change the OSSRH/Sonatype or signing credentials, update the repository Secrets 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 the following step: If you want to manually publish to the Nexus repository (and then release it to Maven Central), you should:

Import the GPG key to your local machine (see below)
Set the autoReleaseAfterClose inside the zero-bounce-sdk's pom.xml to false.

Run the following command:

# For publishing to the staging repository
mvn --no-transfer-progress --batch-mode -Dgpg.passphrase=<YOUR_PASSPHRASE> clean deploy -Prelease

You should then go to the Nexus Sonatype, 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

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

Import the keys:

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

Check that the new keys are imported:
```
gpg --list-keys
gpg --list-secret-keys
```

Warmup API

The Warmup API is a separate product. It has its own host, its own team-scoped key, and its own client; your validation key will not work with it.

ZeroBounceWarmup warmup = ZeroBounceWarmup.getInstance();
warmup.initialize("<YOUR_WARMUP_API_KEY>");

warmup.listSendingAccounts(onSuccess, onError);
warmup.getProgressToday(onSuccess, onError);
warmup.downloadSeeds(csv -> { /* CSV text, columns seed,provider */ }, onError);

Add a from-address you run yourself, with one of the five standard engagement rules (0 Default, 1 Slow Pace, 2 Repair, 3 Boost, 4 Protect):

warmup.addSendingAccount("sender@example.com", "self_managed",
        new ZeroBounceWarmup.AddSendingAccountOptions().setEngagementRuleId(0),
        onSuccess, onError);

A custom engagement rule can be changed only once every seven days; inside that window the API answers 429.

warmup.createCustomEngagement("sender@example.com", 20, 20, 35, onSuccess, onError);  // reply, important, click %

checkDomainDmarc takes an email address, not a domain — the live API rejects a bare domain even though the docs describe one:

warmup.checkDomainDmarc("sender@example.com", null, onSuccess, onError);

Every documented empty success (204, or an empty 200) arrives as a null payload. A payload that is not a JSON object — /seeds is an array, /seed-count a bare number — comes back wrapped under data. Failures carry the HTTP status on ErrorResponse.getStatusCode(). Nothing is stored by testSmtpConfiguration, and the credentials you pass it are masked out of any error it raises.

Live API suite

mvn test never touches the network: the live suite lives outside the Maven module's source root, so CI does not even compile it. It needs real keys, which come from the environment and are never written anywhere:

mvn -f zero-bounce-sdk/pom.xml dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt
mvn -f zero-bounce-sdk/pom.xml compile
CP="zero-bounce-sdk/target/classes:$(cat /tmp/cp.txt)"
javac -cp "$CP" -d live/out live/LiveApi.java

export ZEROBOUNCE_API_KEY=...          # validation API
export ZEROBOUNCE_WARMUP_API_KEY=...   # Warmup API
java -cp "$CP:live/out" com.zerobounce.live.LiveApi

By default it only makes free calls: sandbox addresses, reads, and requests that are expected to fail but still prove the API accepts the payload. It checks that the credit balance did not move. Two flags opt in to more:

Flag	What it adds
`ZEROBOUNCE_LIVE_SPEND=1`	billable calls (scoring, activity, email finder) and a bulk round trip that deletes its own job
`ZEROBOUNCE_LIVE_CHANGES=1`	reversible account changes — a test filter and a self-managed Warmup sending account — each undone in cleanup even when a test fails

It never creates an Inbox Placement test, sets the Inbox Placement webhook, or starts ZB-managed Warmup onboarding, because the API cannot undo any of those.

Run it by hand before every release: the offline suite proves the SDK sends what we think it sends, and only the live suite proves the API accepts it.

Publish

Bump sdk.version in zero-bounce-sdk/pom.xml, commit, tag (vX.Y.Z), push tag.
Actions → Publish → Run workflow with that tag.

Registry: com.zerobounce.java:zerobouncesdk on Maven Central

Name		Name	Last commit message	Last commit date
.github		.github
ci		ci
live		live
src/main		src/main
zero-bounce-sdk		zero-bounce-sdk
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
ZeroBounceJavaSDKSetup.iml		ZeroBounceJavaSDKSetup.iml
documentation.md		documentation.md
email_file.csv		email_file.csv
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Latest commit

History

Folders and files

Repository files navigation

ZeroBounce Java SDK

Security

Installation

How to use the sample project

How to use the SDK from this repository in your project

How to deploy the SDK

Sample app vs. published SDK

USAGE

Controlling SDK logging

Bulk API v2 types

Examples

Validate an email address

Validate batch a list of email addresses

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

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

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

Find other domain formats based on a given domain

Find other domain formats based on a given company name

Check how many credits you have left on your account

Check your API usage for a given period of time

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

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

Check the status of a file uploaded via sendFile API

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

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.

AI Scoring API

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

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

Check the status of a file uploaded via scoringSendFile API

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

Validate options

Real-time AI scoring

Filters

S3 and SFTP/FTP bulk

List evaluator

Inbox Placement Tester

Per-API base URLs

Breaking Changes:

Migration Example:

Old (Deprecated)

New Methods

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

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

Find other domain formats based on a given domain

Find other domain formats based on a given company name

New Features and Enhancements

Custom API URL Support

Migration / Usage

Available API Endpoints

Usage Example:

Testing

Run tests with Docker

Run tests (local)

Documentation

Publication

Local setup for manual release

Exporting and importing PGP keys

Warmup API

Live API suite

Publish

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

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

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