EmailVerify LogoEmailVerify
SDK

Java SDK

Java email checker SDK. Maven/Gradle setup, verify emails with Java. Code examples included.

Официальный EmailVerify SDK для Java предоставляет надёжный интерфейс для проверки email с поддержкой интеграции Spring Boot.

Установка

Maven

<dependency>
    <groupId>com.emailverify</groupId>
    <artifactId>emailverify-java</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'com.emailverify:emailverify-java:1.0.0'

Требования

  • Java 11 или выше
  • Maven или Gradle

Быстрый старт

import com.emailverify.Client;
import com.emailverify.model.VerificationResult;

public class Main {
    public static void main(String[] args) {
        Client client = new Client(System.getenv("EMAILVERIFY_API_KEY"));

        VerificationResult result = client.verify("user@example.com");
        System.out.println("Статус: " + result.getStatus());
        System.out.println("Оценка: " + result.getScore());
    }
}

Конфигурация

Построитель клиента

import com.emailverify.Client;
import java.time.Duration;

Client client = Client.builder()
    .apiKey(System.getenv("EMAILVERIFY_API_KEY"))
    .timeout(Duration.ofSeconds(30))
    .retries(3)
    .baseUrl("https://api.emailverify.ai")
    .build();

Свойства конфигурации

СвойствоТипПо умолчаниюОписание
apiKeyStringОбязательноВаш API-ключ
timeoutDuration30 секТаймаут запроса
retriesint3Количество повторных попыток
baseUrlStringURL APIПользовательская конечная точка API

Типы

VerificationResult

public class VerificationResult {
    private String email;
    private String status;        // "valid", "invalid", "unknown", "accept_all"
    private ResultDetails result;
    private double score;
    private String reason;

    // Геттеры...
}

public class ResultDetails {
    private Boolean deliverable;
    private boolean validFormat;
    private boolean validDomain;
    private boolean validMx;
    private boolean disposable;
    private boolean role;
    private boolean catchall;
    private boolean free;
    private Boolean smtpValid;

    // Геттеры...
}

BulkJob

public class BulkJob {
    private String id;
    private String status;        // "pending", "processing", "completed", "failed"
    private int total;
    private int processed;
    private int valid;
    private int invalid;
    private int unknown;
    private Instant createdAt;
    private Instant completedAt;

    // Геттеры...
}

Единичная проверка

Базовая проверка

VerificationResult result = client.verify("user@example.com");

System.out.println("Email: " + result.getEmail());
System.out.println("Статус: " + result.getStatus());
System.out.println("Оценка: " + result.getScore());
System.out.println("Доставляемый: " + result.getResult().getDeliverable());
System.out.println("Одноразовый: " + result.getResult().isDisposable());

Проверка с параметрами

import com.emailverify.model.VerifyOptions;

VerifyOptions options = VerifyOptions.builder()
    .smtpCheck(true)
    .timeout(Duration.ofSeconds(5))
    .build();

VerificationResult result = client.verify("user@example.com", options);

Асинхронная проверка

import java.util.concurrent.CompletableFuture;

CompletableFuture<VerificationResult> future = client.verifyAsync("user@example.com");

future.thenAccept(result -> {
    System.out.println("Статус: " + result.getStatus());
}).exceptionally(ex -> {
    System.err.println("Ошибка: " + ex.getMessage());
    return null;
});

Массовая проверка

Отправка задачи

import java.util.Arrays;
import java.util.List;

List<String> emails = Arrays.asList(
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
);

BulkJob job = client.verifyBulk(emails);
System.out.println("ID задачи: " + job.getId());

Проверка статуса

BulkJob status = client.getBulkJobStatus(job.getId());

System.out.println("Статус: " + status.getStatus());
System.out.println("Прогресс: " + status.getProcessed() + "/" + status.getTotal());
System.out.println("Действительных: " + status.getValid());
System.out.println("Недействительных: " + status.getInvalid());

Получение результатов

List<VerificationResult> results = client.getBulkJobResults(job.getId());

for (VerificationResult result : results) {
    System.out.println(result.getEmail() + ": " + result.getStatus());
}

С вебхуком

import com.emailverify.model.BulkOptions;

BulkOptions options = BulkOptions.builder()
    .webhookUrl("https://your-domain.com/webhooks/emailverify")
    .build();

BulkJob job = client.verifyBulk(emails, options);

Управление кредитами

import com.emailverify.model.Credits;

Credits credits = client.getCredits();

System.out.println("Доступно: " + credits.getAvailable());
System.out.println("Использовано: " + credits.getUsed());
System.out.println("Всего: " + credits.getTotal());

Обработка ошибок

Типы исключений

import com.emailverify.exception.*;

try {
    VerificationResult result = client.verify("invalid-email");
} catch (AuthenticationException e) {
    System.err.println("Неверный API-ключ");
} catch (RateLimitException e) {
    System.err.println("Превышен лимит запросов. Повторите через " + e.getRetryAfter() + " секунд");
} catch (ValidationException e) {
    System.err.println("Неверные входные данные: " + e.getMessage());
} catch (EmailVerifyException e) {
    System.err.println("Ошибка API: " + e.getMessage());
}

Пользовательский обработчик исключений

public class VerificationService {
    private final Client client;

    public Optional<VerificationResult> safeVerify(String email) {
        try {
            return Optional.of(client.verify(email));
        } catch (RateLimitException e) {
            logger.warn("Превышен лимит, повторите через: {}", e.getRetryAfter());
            return Optional.empty();
        } catch (EmailVerifyException e) {
            logger.error("Ошибка проверки: {}", e.getMessage());
            return Optional.empty();
        }
    }
}

Интеграция с Spring Boot

Зависимость

Добавьте стартер Spring Boot:

<dependency>
    <groupId>com.emailverify</groupId>
    <artifactId>emailverify-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Конфигурация

# application.yml
emailverify:
  api-key: ${EMAILVERIFY_API_KEY}
  timeout: 30s
  retries: 3

Или в application.properties:

emailverify.api-key=${EMAILVERIFY_API_KEY}
emailverify.timeout=30s
emailverify.retries=3

Автоконфигурация

Клиент автоматически настраивается и доступен для внедрения:

import com.emailverify.Client;
import org.springframework.stereotype.Service;

@Service
public class EmailVerificationService {
    private final Client emailVerifyClient;

    public EmailVerificationService(Client emailVerifyClient) {
        this.emailVerifyClient = emailVerifyClient;
    }

    public boolean isValidEmail(String email) {
        VerificationResult result = emailVerifyClient.verify(email);
        return "valid".equals(result.getStatus());
    }
}

REST-контроллер

import com.emailverify.Client;
import com.emailverify.model.VerificationResult;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/verify")
public class VerificationController {
    private final Client client;

    public VerificationController(Client client) {
        this.client = client;
    }

    @PostMapping
    public ResponseEntity<?> verify(@RequestBody VerifyRequest request) {
        try {
            VerificationResult result = client.verify(request.getEmail());
            return ResponseEntity.ok(new VerifyResponse(
                result.getEmail(),
                result.getStatus(),
                result.getScore()
            ));
        } catch (Exception e) {
            return ResponseEntity.internalServerError()
                .body(new ErrorResponse("Ошибка проверки"));
        }
    }
}

record VerifyRequest(String email) {}
record VerifyResponse(String email, String status, double score) {}
record ErrorResponse(String error) {}

Пользовательская аннотация валидатора

// Аннотация
import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;

@Documented
@Constraint(validatedBy = ValidEmailValidator.class)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidEmail {
    String message() default "Недействительный email-адрес";
    boolean rejectDisposable() default true;
    double minScore() default 0.5;
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// Валидатор
import com.emailverify.Client;
import com.emailverify.model.VerificationResult;
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

public class ValidEmailValidator implements ConstraintValidator<ValidEmail, String> {
    private final Client client;
    private boolean rejectDisposable;
    private double minScore;

    public ValidEmailValidator(Client client) {
        this.client = client;
    }

    @Override
    public void initialize(ValidEmail annotation) {
        this.rejectDisposable = annotation.rejectDisposable();
        this.minScore = annotation.minScore();
    }

    @Override
    public boolean isValid(String email, ConstraintValidatorContext context) {
        if (email == null || email.isBlank()) {
            return false;
        }

        try {
            VerificationResult result = client.verify(email);

            if (!"valid".equals(result.getStatus())) {
                return false;
            }

            if (rejectDisposable && result.getResult().isDisposable()) {
                return false;
            }

            return result.getScore() >= minScore;
        } catch (Exception e) {
            return false;
        }
    }
}

// Использование
public class RegisterRequest {
    @ValidEmail(rejectDisposable = true, minScore = 0.7)
    private String email;

    // геттеры, сеттеры...
}

Асинхронный сервис

import com.emailverify.Client;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
import java.util.concurrent.CompletableFuture;

@Service
public class AsyncVerificationService {
    private final Client client;

    public AsyncVerificationService(Client client) {
        this.client = client;
    }

    @Async
    public CompletableFuture<VerificationResult> verifyAsync(String email) {
        return client.verifyAsync(email);
    }

    @Async
    public CompletableFuture<List<VerificationResult>> verifyBatchAsync(List<String> emails) {
        return CompletableFuture.supplyAsync(() -> {
            BulkJob job = client.verifyBulk(emails);

            // Опрос до завершения
            while (true) {
                BulkJob status = client.getBulkJobStatus(job.getId());
                if ("completed".equals(status.getStatus())) {
                    break;
                }
                if ("failed".equals(status.getStatus())) {
                    throw new RuntimeException("Массовая задача не выполнена");
                }
                try {
                    Thread.sleep(5000);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException(e);
                }
            }

            return client.getBulkJobResults(job.getId());
        });
    }
}

Полные примеры

Сервис регистрации

import com.emailverify.Client;
import com.emailverify.model.VerificationResult;

public class RegistrationService {
    private final Client client;

    public RegistrationService(Client client) {
        this.client = client;
    }

    public ValidationResult validateEmail(String email) {
        VerificationResult result = client.verify(email);

        // Отклонить недействительные email
        if ("invalid".equals(result.getStatus())) {
            return ValidationResult.invalid("invalid_email",
                "Этот email-адрес недействителен");
        }

        // Отклонить одноразовые email
        if (result.getResult().isDisposable()) {
            return ValidationResult.invalid("disposable",
                "Пожалуйста, используйте постоянный email-адрес");
        }

        // Предупреждение о ролевых email
        if (result.getResult().isRole()) {
            return ValidationResult.warning("role_based",
                "Рекомендуется использовать личный email",
                result.getScore());
        }

        return ValidationResult.valid(result.getScore());
    }
}

class ValidationResult {
    private final boolean valid;
    private final String reason;
    private final String message;
    private final Double score;

    private ValidationResult(boolean valid, String reason, String message, Double score) {
        this.valid = valid;
        this.reason = reason;
        this.message = message;
        this.score = score;
    }

    public static ValidationResult valid(double score) {
        return new ValidationResult(true, null, null, score);
    }

    public static ValidationResult invalid(String reason, String message) {
        return new ValidationResult(false, reason, message, null);
    }

    public static ValidationResult warning(String reason, String message, double score) {
        return new ValidationResult(true, reason, message, score);
    }

    // Геттеры...
}

Конкурентная проверка

import com.emailverify.Client;
import java.util.List;
import java.util.concurrent.*;
import java.util.stream.Collectors;

public class ConcurrentVerifier {
    private final Client client;
    private final ExecutorService executor;

    public ConcurrentVerifier(Client client, int threads) {
        this.client = client;
        this.executor = Executors.newFixedThreadPool(threads);
    }

    public List<VerificationResult> verifyAll(List<String> emails) {
        List<CompletableFuture<VerificationResult>> futures = emails.stream()
            .map(email -> CompletableFuture.supplyAsync(
                () -> client.verify(email), executor))
            .collect(Collectors.toList());

        return futures.stream()
            .map(CompletableFuture::join)
            .collect(Collectors.toList());
    }

    public void shutdown() {
        executor.shutdown();
    }
}

// Использование
ConcurrentVerifier verifier = new ConcurrentVerifier(client, 10);
try {
    List<String> emails = Arrays.asList("user1@example.com", "user2@example.com");
    List<VerificationResult> results = verifier.verifyAll(emails);
    results.forEach(r -> System.out.println(r.getEmail() + ": " + r.getStatus()));
} finally {
    verifier.shutdown();
}

Лучшие практики

1. Используйте пул соединений

// Клиент использует пул соединений по умолчанию
// Для высоконагруженных приложений настройте размер пула
Client client = Client.builder()
    .apiKey(apiKey)
    .maxConnections(100)
    .build();

2. Обрабатывайте nullable-поля

VerificationResult result = client.verify(email);

// Используйте Optional для nullable-полей
Optional.ofNullable(result.getResult().getDeliverable())
    .ifPresent(deliverable -> System.out.println("Доставляемый: " + deliverable));

3. Управление ресурсами

// Клиент реализует AutoCloseable
try (Client client = new Client(apiKey)) {
    VerificationResult result = client.verify(email);
    // Обработка результата
}

Следующие шаги

Справочник API

Подробная документация API

Руководства по интеграции

Интеграция с платформами

PHP SDK

PHP email checker SDK. Composer install, verify emails with PHP. Code examples included.

AI Guides

Email checker for AI agents. MCP Server, Claude Code, AI SDKs integration. Automated email verification.

On this page

УстановкаMavenGradleТребованияБыстрый стартКонфигурацияПостроитель клиентаСвойства конфигурацииТипыVerificationResultBulkJobЕдиничная проверкаБазовая проверкаПроверка с параметрамиАсинхронная проверкаМассовая проверкаОтправка задачиПроверка статусаПолучение результатовС вебхукомУправление кредитамиОбработка ошибокТипы исключенийПользовательский обработчик исключенийИнтеграция с Spring BootЗависимостьКонфигурацияАвтоконфигурацияREST-контроллерПользовательская аннотация валидатораАсинхронный сервисПолные примерыСервис регистрацииКонкурентная проверкаЛучшие практики1. Используйте пул соединений2. Обрабатывайте nullable-поля3. Управление ресурсамиСледующие шаги