Java SDK

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

EmailVerify 官方 Java SDK 提供强大的邮箱验证接口,支持 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();

配置 Properties

Property	Type	默认值	描述
`apiKey`	String	必需	您的 API 密钥
`timeout`	Duration	30s	请求超时
`retries`	int	3	重试次数
`baseUrl`	String	API URL	自定义 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;

    // Getters...
}

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;

    // Getters...
}

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;

    // Getters...
}

单个验证

基本验证

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

System.out.println("邮箱: " + 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());
}

使用 Webhook

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 starter：

<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 "邮箱地址无效";
    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;

    // getters, setters...
}

异步服务

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);

        // 拒绝无效邮箱
        if ("invalid".equals(result.getStatus())) {
            return ValidationResult.invalid("invalid_email",
                "此邮箱地址无效");
        }

        // 拒绝一次性邮箱
        if (result.getResult().isDisposable()) {
            return ValidationResult.invalid("disposable",
                "请使用永久邮箱地址");
        }

        // 警告角色邮箱
        if (result.getResult().isRole()) {
            return ValidationResult.warning("role_based",
                "建议使用个人邮箱",
                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);
    }

    // Getters...
}

并发验证

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. 处理可空字段

VerificationResult result = client.verify(email);

// 对可空字段使用 Optional
Optional.ofNullable(result.getResult().getDeliverable())
    .ifPresent(deliverable -> System.out.println("可递送: " + deliverable));

3. 资源管理

// 客户端实现 AutoCloseable
try (Client client = new Client(apiKey)) {
    VerificationResult result = client.verify(email);
    // 处理结果
}

Java SDK

API 参考

集成指南

On this page