Tutorial · Java

Verify Email Addresses with Java

Real-time email verification using the modern java.net.http.HttpClient introduced in Java 11.

GET https://api.validemail.net/ 1 credit per verification Java 11+

1

Add a JSON dependency

This tutorial parses the response with org.json. Any JSON library (Jackson, Gson) works the same way.

Maven

<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20240303</version>
</dependency>

2

Verify an email address

Send a GET request with the email and your API token. The helper below also handles interim Unknown results by waiting RetryAfterSeconds and retrying automatically.

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

import org.json.JSONObject;

public class EmailVerifier {

    private static final String API_URL = "https://api.validemail.net/";
    private static final String API_KEY = "YOUR_API_KEY"; // find it in your ValidEmail dashboard

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

    public static void main(String[] args) throws Exception {
        JSONObject result = verifyEmail("someone@example.com", 3);

        System.out.println("Valid:  " + result.getBoolean("IsValid"));
        System.out.println("Score:  " + result.getInt("Score"));
        System.out.println("State:  " + result.getString("State"));
        System.out.println("Reason: " + result.getString("Reason"));

        if (result.getBoolean("IsValid") && result.getInt("Score") >= 80) {
            System.out.println("Safe to send.");
        }
    }

    static JSONObject verifyEmail(String email, int maxRetries) throws Exception {
        JSONObject result = null;

        for (int attempt = 0; attempt < maxRetries; attempt++) {
            String url = API_URL + "?email=" + URLEncoder.encode(email, StandardCharsets.UTF_8)
                    + "&token=" + API_KEY;

            HttpRequest request = HttpRequest.newBuilder(URI.create(url))
                    .timeout(Duration.ofSeconds(90))
                    .GET()
                    .build();

            HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() != 200) {
                throw new RuntimeException("Request failed with HTTP " + response.statusCode() + ": " + response.body());
            }

            result = new JSONObject(response.body());

            // "Unknown" means the verification is still in progress (e.g. greylisting).
            int retryAfter = result.optInt("RetryAfterSeconds", 0);
            if ("Unknown".equals(result.getString("State")) && retryAfter > 0) {
                Thread.sleep(retryAfter * 1000L);
                continue;
            }

            return result;
        }

        return result; // still pending after maxRetries — treat as risky
    }
}

Handling interim results (`State = "Unknown"`)

Some mail servers greylist first-time senders or respond slowly. Instead of failing, the API returns an interim 200 OK result with State = "Unknown", a Reason of PENDING or GREYLISTED, and a RetryAfterSeconds hint while the verification finishes in the background.

Wait RetryAfterSeconds seconds, then repeat the same request to get the final verdict.
Definitive results are cached for about 10 minutes, so the retry is answered instantly once the verification completes.
Treat Unknown as "not yet decided" — never as a delivery failure.

3

Check your credits balance

The balance endpoint is free to call and never consumes a credit — perfect for a pre-flight check before verifying a large list.

Java

HttpRequest balanceRequest = HttpRequest.newBuilder(
        URI.create("https://api.validemail.net/balance?token=" + API_KEY))
        .GET()
        .build();

HttpResponse<String> balanceResponse = CLIENT.send(balanceRequest, HttpResponse.BodyHandlers.ofString());
int balance = new JSONObject(balanceResponse.body()).getInt("balance");

System.out.println("Credits remaining: " + balance);

HTTP status codes

HTTP Status	Meaning	What to do
200 OK	The request was processed. Check `State` — a result with `State = "Unknown"` and a `RetryAfterSeconds` value is an interim answer, not a final verdict.	Use the result. If `State` is `Unknown`, retry the same request after `RetryAfterSeconds`.
400 Bad Request	Missing `email`/`token` parameter, no credits remaining, or a transient processing failure.	Check the response text. If you are out of credits, top up your balance before retrying.
401 Unauthorized	The API key is invalid or unknown.	Verify the `token` value against the API key shown in your dashboard.
403 Forbidden	The account attached to this API key is inactive.	Contact info@validemail.net to reactivate the account.
429 Too Many Requests	You exceeded your per-second request limit. The response body includes the configured limit.	Slow down and retry with backoff, or contact us to raise your rate limit.

Next steps

Explore every response field and status code in the full API reference.

API Reference