Java SDK

Official Java SDK for the Truelist email validation API. Thread-safe with automatic retries and exponential backoff.

Installation

Gradle (Kotlin DSL)

dependencies {
    implementation("io.truelist:truelist-java:0.1.0")
}

Maven

<dependency>
    <groupId>io.truelist</groupId>
    <artifactId>truelist-java</artifactId>
    <version>0.1.0</version>
</dependency>

Requires Java 11+.

Quick start

import io.truelist.Truelist;
import io.truelist.ValidationResult;

Truelist client = Truelist.builder("your-api-key").build();
ValidationResult result = client.validate("user@example.com");

if (result.isValid()) {
    System.out.println("Email is valid!");
}

Configuration

Truelist client = Truelist.builder("your-api-key")
    .baseUrl("https://api.truelist.io")
    .timeout(Duration.ofSeconds(10))
    .maxRetries(2)
    .build();

The client is thread-safe — create once and reuse across your application.

Result methods

result.getEmail();      // "user@example.com"
result.getDomain();     // "example.com"
result.getState();      // "ok", "email_invalid", "accept_all", "unknown"
result.getSubState();   // "email_ok", "is_disposable", "is_role", ...
result.getSuggestion(); // null or correction
result.isValid();       // true
result.isDisposable();  // false
result.isRole();        // false

Error handling

import io.truelist.exceptions.*;

try {
    ValidationResult result = client.validate("user@example.com");
} catch (AuthenticationException e) {
    // 401 — never retried
} catch (RateLimitException e) {
    // 429
} catch (ApiException e) {
    System.err.println(e.getStatusCode());
}

401 errors are never retried. 429 and 5xx are retried with exponential backoff up to maxRetries.

Account info

AccountInfo account = client.getAccount();
account.getEmail();
account.getAccount().getPaymentPlan();

Package link