Email verification in Java

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.17.0</version>
</dependency>

public final class ZapBounce {
    private static final HttpClient CLIENT = HttpClient.newBuilder()
            .version(HttpClient.Version.HTTP_2)
            .connectTimeout(Duration.ofSeconds(3))
            .build();

    private static final ObjectMapper MAPPER = new ObjectMapper()
            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

    private final String key;

    public ZapBounce(String key) { this.key = key; }

    public VerifyResult verify(String email) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://app.zapbounce.com/api/v1/verify"))
                .header("X-API-Key", key)
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(12))   // per request, not on the client
                .POST(HttpRequest.BodyPublishers.ofString(
                        MAPPER.writeValueAsString(Map.of("emails", List.of(email)))))
                .build();

        HttpResponse<String> response =
                CLIENT.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw ZapBounceException.from(response);
        }
        // The answer is {"node": "...", "results": [ ... ]}. One email in, one result out.
        JsonNode first = MAPPER.readTree(response.body()).path("results").get(0);
        return MAPPER.treeToValue(first, VerifyResult.class);
    }
}

// FAIL_ON_UNKNOWN_PROPERTIES off is deliberate: new response fields are additive
// and must not break a client that has not been redeployed.
public record VerifyResult(String id, String email, String status, String reasonCode,
                           String provider, List<String> flags, Integer smtpCode,
                           String checkedAt) {}

/** Concurrent single verifications. On Java 21, a virtual-thread executor
 *  lets you raise the pool without paying for platform threads. */
public List<VerifyResult> verifyAll(List<String> emails) {
    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
        List<CompletableFuture<VerifyResult>> futures = emails.stream()
                .map(email -> CompletableFuture.supplyAsync(() -> {
                    try {
                        return verify(email);
                    } catch (IOException | InterruptedException e) {
                        // A failure here is not a verdict. Do not record it as invalid.
                        return VerifyResult.unresolved(email);
                    }
                }, executor))
                .toList();
        return futures.stream().map(CompletableFuture::join).toList();
    }
}

/** For a real list, submit a job (up to 50,000 emails) and let the server pace probes per mail host. */
public String submitJob(List<String> emails) throws IOException, InterruptedException {
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.zapbounce.com/api/v1/jobs"))
            .header("X-API-Key", key)
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", UUID.randomUUID().toString())
            .POST(HttpRequest.BodyPublishers.ofString(
                    MAPPER.writeValueAsString(Map.of("emails", emails, "source", "api"))))
            .build();

    HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
    return MAPPER.readTree(response.body()).get("id").asText();
}

/** No webhook: poll until the job is completed, partial, failed or cancelled. */
public JsonNode waitForJob(String id) throws IOException, InterruptedException {
    while (true) {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://app.zapbounce.com/api/v1/jobs/" + id))
                .header("X-API-Key", key)
                .timeout(Duration.ofSeconds(30))
                .build();
        JsonNode job = MAPPER.readTree(CLIENT.send(request, HttpResponse.BodyHandlers.ofString()).body());
        if (Set.of("completed", "partial", "failed", "cancelled").contains(job.path("status").asText())) {
            return job;
        }
        Thread.sleep(5_000);
    }
}
// Then page GET /v1/jobs/{id}/emails?page=N&pageSize=100 until meta.totalPages,
// or stream GET /v1/jobs/{id}/export as CSV.

public class ZapBounceException extends RuntimeException {
    private final String code;
    private final String requestId;
    private final int status;
    private final int windowSeconds;   // X-RateLimit-Window-Seconds, 0 when absent

    public boolean retryable() { return status == 429 || status >= 500; }

    public static ZapBounceException from(HttpResponse<String> response) {
        int window = response.headers().firstValue("X-RateLimit-Window-Seconds")
                .map(Integer::parseInt).orElse(0);
        try {
            JsonNode error = MAPPER.readTree(response.body());   // statusCode, code, message, requestId
            return new ZapBounceException(
                    error.path("code").asText("unknown"),
                    error.path("message").asText(response.body()),
                    error.path("requestId").asText(""),
                    response.statusCode(), window);
        } catch (JsonProcessingException e) {
            return new ZapBounceException("unparseable", response.body(), "", response.statusCode(), window);
        }
    }
}

public VerifyResult verifyWithRetry(String email) throws InterruptedException {
    ZapBounceException last = null;
    for (int attempt = 0; attempt < 5; attempt++) {
        long floorMs = 500;
        try {
            return verify(email);
        } catch (ZapBounceException e) {
            if (!e.retryable()) throw e;    // CREDITS_INSUFFICIENT (422) will not improve
            last = e;
            // There is no Retry-After header: a 429 backs off from the window length.
            if (e.status == 429) floorMs = Math.max(1, e.windowSeconds) * 1000L;
        } catch (HttpTimeoutException e) {
            // A timeout is not a bad address. Fail open.
            return VerifyResult.unresolved(email);   // status "unknown", reasonCode "TIMEOUT"
        } catch (IOException e) {
            last = new ZapBounceException("io", e.getMessage(), "", 0, 0);
        }
        Thread.sleep((long) (Math.pow(2, attempt) * floorMs * (0.5 + Math.random())));
    }
    throw last;
}