franciscbalint · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026
diff --git a/.github/workflows/sdk_ci.yml b/.github/workflows/sdk_ci.yml
@@ -25,10 +25,13 @@ jobs:
           java-version: 21
           distribution: 'temurin'
 
-      # Execute unit tests.
+      - name: Typecheck
+        run: cd zero-bounce-sdk && mvn -B -DskipTests compile
+
+      # Execute unit tests. This includes the offline fake-API suite.
       - name: Run unit tests
-        run: cd zero-bounce-sdk && mvn test
+        run: cd zero-bounce-sdk && mvn -B test
 
       # Compile the project to check for errors.
       - name: Compile project
-        run: cd zero-bounce-sdk && mvn clean install
+        run: cd zero-bounce-sdk && mvn -B clean install
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project
+
+`zero-bounce-java-sdk-setup` is the ZeroBounce Java SDK plus a small JavaFX sample. The library that ships is `zero-bounce-sdk` (`com.zerobounce.java:zerobouncesdk` on Maven Central). Callers construct a `ZeroBounceSDK` or use `getInstance()`, call `initialize`, and receive results through success and error callbacks.
+
+## Layout
+
+- `zero-bounce-sdk/src/main/java/com/zerobounce/ZeroBounceSDK.java`: public client.
+- `zero-bounce-sdk/src/main/java/com/zerobounce/Priority3Api.java`: bulk email finder, domain search, list evaluator, filters, S3.
+- `zero-bounce-sdk/src/main/java/com/zerobounce/HttpMessages.java`: turns HTTP failures, HTML pages, and empty or non-JSON bodies into a short `ErrorResponse`.
+- `zero-bounce-sdk/src/main/java/com/zerobounce/SdkHttp.java`: per-client HTTP seam. Production leaves `transport` null.
+- `zero-bounce-sdk/src/test/java/com/zerobounce/OfflineApiTest.java`: offline suite. `FakeApi` records every request and answers without the network.
+- `zero-bounce-sdk/pom.xml`: SDK build. The version is `<sdk.version>` inside `<properties>`.
+- `pom.xml`: the JavaFX sample. Its `<version>` is `1.0-SNAPSHOT` and is not the SDK version.
+- `.github/workflows/sdk_ci.yml`: typecheck, `mvn test`, then `mvn clean install`.
+- `.github/workflows/publish.yml`: manual Publish workflow. It deploys the tag to Maven Central.
+
+## Commands
+
+From `zero-bounce-sdk`:
+
+```bash
+mvn -B -DskipTests compile   # typecheck; there is no separate style linter
+mvn -B test                  # unit tests, including OfflineApiTest
+```
+
+CI runs the same compile and `mvn test`. `mvn test` is the default test command.
+
+## Conventions
+
+- **One `ZeroBounceSDK` per API key.** `getInstance()` is a process-wide singleton. Do not reuse it across users or requests. Construct `new ZeroBounceSDK()` per key. The offline concurrency test does this. Do not share one instance across threads: `apiKey` is mutable and `SimpleDateFormat` is not thread-safe.
+- **The SDK version is `<sdk.version>`.** Never edit the first `<version>` tag in `zero-bounce-sdk/pom.xml`; that tag is `${sdk.version}`. Plugin and dependency versions must not be copied from `<sdk.version>`.
+- **Column indexes are 1-based for file uploads.** `sendFile`'s email column must be at least 1. Optional name, gender, and IP columns default to `0`, and `0` means the field is left out. `ValidateS3FileOptions.emailAddressColumn` is an `Integer`: when it is set, `0` is sent.
+- **Optional parameters are omitted when unset.** `timeout`, `activityData`, `verifyPlus`, `allowPhase2`, `downloadType`, and `hasHeaderRow` are not sent until the caller sets them. Explicit `false` is sent as `false`. `timeout` `0` is sent.
+- **`allow_phase_2` is validation `sendFile` and `validateS3File` only.** Scoring uploads ignore it. `activity_data` on get-file is validation only.
+- **`validateBatch` uses `api.zerobounce.net`**, not `bulkapi.zerobounce.net`.
+- **Booleans are the strings `true` and `false` on form and multipart fields, and JSON booleans in a JSON body.**
+- **Failures use the error callback**, not thrown server errors. `ZBException` is only for invalid arguments such as an email column below 1. The message must be short: no raw HTML, no megabyte body, and no `Error: Error:` prefix. An account-level `validateBatch` error (`email_address` `all`) is an error callback. A per-address error stays on the success result.
+- **Tests replace `transport`.** It is package-visible. Assign a `FakeApi` (or another `SdkHttp.Transport`) on that instance. Do not call the live API from the default test run.
+- There is no runtime version constant and no User-Agent. Do not add one that can drift from `<sdk.version>`.
+- Match the surrounding style. Do not reformat unrelated code.
+
+## Changelog
+
+`CHANGELOG.md` follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+- Add every user-visible change to `## [Unreleased]` in the same commit as the change.
+- Group entries under these headings, in this order, omitting empty ones: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+- Write for SDK users: name the method, option, or behaviour, and say what changed. Leave out CI-only changes, internal refactors, and fixes to code that was never released.
+- At 2.y.z, a breaking change bumps the major version, a new method or option bumps the minor version, and fixes alone bump the patch version.
+
+## Releasing
+
+Publishing and pushing tags need a maintainer's explicit approval. Do not bump the version, tag, or publish unless they asked.
+
+1. Move `[Unreleased]` entries under `## [x.y.z] - YYYY-MM-DD`, leave an empty `[Unreleased]` section, and update the compare links at the bottom of `CHANGELOG.md`.
+2. Set the same version in `<sdk.version>` in `zero-bounce-sdk/pom.xml`. Do not edit the first `<version>` tag. The sample `pom.xml` dependency on `com.zerobounce.java:zerobouncesdk` is a separate pin; update it only when the sample should depend on the new release.
+3. `mvn -B -DskipTests compile` and `mvn -B test` in `zero-bounce-sdk`.
+4. Tag `vx.y.z` on that commit and run the Publish workflow with that tag. It deploys to Maven Central and creates the GitHub release.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `validateWithOptions` takes `ZBValidateRequestOptions`: `timeout`, `activityData`, `verifyPlus`, and `usePost` (form-encoded `POST /v2/validate`).
+- `validateBatchWithOptions` sends `timeout`, `activityData`, and `verifyPlus` on `POST /v2/validatebatch`.
+- `ZBValidateResponse` reads `active_in_days` and `active_first_seen`.
+- `scoreEmail` (`GET /v2/scoring`) and `scoreEmailPost` (form-encoded `POST /v2/scoring`).
+- Bulk email finder (`sendEmailFinderFile`, `emailFinderFileStatus`, `emailFinderGetFile`, `emailFinderDeleteFile`). `has_header_row` is sent as `true` or `false` when it is set.
+- Bulk domain search (`sendDomainSearchFile`, `domainSearchFileStatus`, `domainSearchGetFile`, `domainSearchDeleteFile`). `has_header_row` is sent as `true` or `false` when it is set.
+- List evaluator (`sendListEvaluatorFile`, `getListEvaluatorResult`, `sendEvaluatedFile`).
+- Filters (`addFilter`, `listFilters`, `deleteFilter`).
+- S3 bulk (`validateS3File`, `scoreS3File`, `exportS3File`, `listS3Files`). `email_address_column` is sent when it is set, including `0`.
+- `new ZeroBounceSDK()` builds a client for one API key. `getInstance()` remains a process-wide singleton.
+
+### Changed
+
+- A custom API base URL must start with `https://`.
+- API requests time out after 120 seconds by default and do not follow redirects.
+
+### Fixed
+
+- A 403 HTML "Access denied" page is returned as a short error. An HTML page with status 200 is an error as well, including `getFile`, `emailFinderGetFile`, and `domainSearchGetFile`, instead of a saved file.
+- Empty and non-JSON bodies are a short error. The message is no longer a Gson parser exception, and a repeated `Error:` / `[Error]:` prefix is removed.
+- A Cloudflare JSON 403 (`error_code` 1020) is the title "Error 1020: Access denied", not the raw body.
+- `validateBatch` reports an account-level failure (HTTP 200, error for address `all`, such as an invalid API key or no credits) through the error callback. An error for one address stays on the successful result.
+- An empty API key, a blank email, a blank file id, and a blank filter rule, target, or value are rejected before a request is sent.
+- `findEmail` and `findDomain` treat a blank domain or company name as unset.
+
+### Security
+
+- Redirects are disabled, and query values are percent-encoded, so a parameter cannot rewrite the request URL or send the client to another host.
+- Error callbacks and exception messages no longer include the raw HTML access-denied page. Exception text replaces the API key with `***`.
+
+## [2.1.4] - 2026-06-09
+
+### Added
+
+- `ZBValidateResponse.catchallDomain`, read from `catchall_domain`.
+
+## [2.1.0] - 2026-04-05
+
+### Added
+
+- `getFile` and `scoringGetFile` accept `ZBGetFileOptions`, with `downloadType` (`phase_1`, `phase_2`, `combined`) and `activityData` (validation `getFile` only).
+- `SendFileOptions.setAllowPhase2`, sent as `allow_phase_2` on validation `sendFile` only.
+- `ZBFileStatusResponse.filePhase2Status`.
+
+### Fixed
+
+- `getFile` calls the error callback when the body is a JSON error, including HTTP 200 with `"success": false`, instead of saving that body as the results file.
+
+## [2.0.16] - 2026-03-03
+
+### Changed
+
+- License the project under MIT.
+
+## [2.0.0] - 2026-03-03
+
+### Added
+
+- Stream overloads of `sendFile` and `scoringSendFile`.
+- Additional counters on `ZBGetApiUsageResponse`.
+- `ZBValidateStatus.NONE` and further `ZBValidateSubStatus` values, including `ACCEPT_ALL`, `ROLE_BASED_ACCEPT_ALL`, and `GOLD`.
+
+## [1.3.0] - 2025-11-06
+
+### Added
+
+- `findEmail` and `findDomain`.
+
+### Changed
+
+- The SDK builds with Java 21.
+
+### Deprecated
+
+- `guessFormat`. Use `findEmail` or `findDomain`.
+
+## [1.2.0] - 2025-01-13
+
+### Added
+
+- ISO-8601 values in response dates.
+
+### Fixed
+
+- Query values, including the email address, are percent-encoded.
+
+## [1.1.9] - 2024-09-17
+
+### Added
+
+- `initialize(apiKey, timeoutInMillis)`. `0` means no timeout.
+
+## [1.1.7] - 2023-08-25
+
+### Fixed
+
+- `ZBValidateStatus` and `ZBValidateSubStatus` are public.
+
+## [1.0.0] - 2019-12-04
+
+### Added
+
+- Initial release, including validation, bulk file, credits, activity, and AI scoring file methods.
+
+[Unreleased]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v2.1.5...HEAD
+[2.1.4]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v2.1.0...v2.1.4
+[2.1.0]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v2.0.16...v2.1.0
+[2.0.16]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v2.0.0...v2.0.16
+[2.0.0]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v1.3.0...v2.0.0
+[1.3.0]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v1.1.9...v1.2.0
+[1.1.9]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v1.1.7...v1.1.9
+[1.1.7]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/compare/v1.0.0...v1.1.7
+[1.0.0]: https://github.com/zerobounce/zero-bounce-java-sdk-setup/releases/tag/v1.0.0