Email Verification API
Java Integration Guide 2026

// BounceZeroClient.java  (JSON via com.fasterxml.jackson.core:jackson-databind 2.12+)
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;

public class BounceZeroClient {

    private static final String BASE_URL = "https://api.bouncezero.io/api/v1/verify";
    private static final String API_KEY  = System.getenv("BOUNCEZERO_API_KEY");
    private static final ObjectMapper MAPPER = new ObjectMapper();

    private final HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    public VerifyResult verify(String email) throws Exception {
        String body = MAPPER.writeValueAsString(Map.of("email", email));
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL))
            .header("X-API-Key", API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .timeout(Duration.ofSeconds(15))
            .build();

        HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());

        if (res.statusCode() != 200) {
            throw new RuntimeException("BounceZero API error: " + res.statusCode());
        }
        return MAPPER.readValue(res.body(), VerifyResult.class);
    }
}

// VerifyResult.java
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;

@JsonIgnoreProperties(ignoreUnknown = true)
public record VerifyResult(
    String email,
    String classification,                        // "valid" | "invalid"
    int    score,                                 // 0-100
    @JsonProperty("is_deliverable") boolean isDeliverable,
    @JsonProperty("risk_level") String riskLevel, // "low" | "medium" | "high"
    Metadata metadata
) {
    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Metadata(
        @JsonProperty("internal_classification") String internalClassification, // verified, catch_all, disposable, unknown, ...
        Boolean refunded,                                                       // true = could not verify, credit refunded
        @JsonProperty("catch_all_unresolved") Boolean catchAllUnresolved
    ) {}

    public String detail()     { return metadata == null ? null : metadata.internalClassification(); }
    public boolean isRefunded() { return metadata != null && Boolean.TRUE.equals(metadata.refunded()); }
}

import java.util.*;
import java.util.concurrent.*;

public class BulkVerifier {

    private static final int THREADS = 5; // adjust to your rate limit

    public Map<String, VerifyResult> verifyAll(List<String> emails) throws Exception {
        BounceZeroClient client = new BounceZeroClient();
        ExecutorService pool = Executors.newFixedThreadPool(THREADS);
        Map<String, Future<VerifyResult>> futures = new LinkedHashMap<>();

        for (String email : emails) {
            futures.put(email, pool.submit(() -> client.verify(email)));
        }

        pool.shutdown();
        pool.awaitTermination(10, TimeUnit.MINUTES);

        Map<String, VerifyResult> results = new LinkedHashMap<>();
        for (Map.Entry<String, Future<VerifyResult>> entry : futures.entrySet()) {
            try {
                results.put(entry.getKey(), entry.getValue().get());
            } catch (ExecutionException e) {
                // leave it out of the results and retry it later
                System.err.println("Error verifying " + entry.getKey() + ": " + e.getCause().getMessage());
            }
        }
        return results;
    }
}

// BounceZeroConfig.java
@Configuration
public class BounceZeroConfig {
    @Bean
    public BounceZeroClient bounceZeroClient() {
        return new BounceZeroClient(); // singleton - shares HttpClient connection pool
    }
}

// RegistrationService.java
@Service
public class RegistrationService {

    private final BounceZeroClient emailVerifier;

    public RegistrationService(BounceZeroClient emailVerifier) {
        this.emailVerifier = emailVerifier;
    }

    public RegistrationResult register(String email, String password) {
        VerifyResult vr;
        try {
            vr = emailVerifier.verify(email);
        } catch (Exception e) {
            // fail-open: don't block signup if verification service is unreachable
            return createAccount(email, password);
        }

        if ("disposable".equals(vr.detail())) {
            return RegistrationResult.rejected("Disposable email addresses are not allowed.");
        }
        if ("invalid".equals(vr.classification()) && !vr.isRefunded()) {
            return RegistrationResult.rejected("Email address is invalid or does not exist.");
        }
        if (vr.isRefunded() || "medium".equals(vr.riskLevel())) {
            // unverifiable or unresolved catch-all: flag for review rather than hard block
            return createAccountWithRiskyFlag(email, password);
        }

        return createAccount(email, password);
    }
}