// frameworks and platforms
Via APISpring Boot email verification with pingutil
In a Spring Boot API, @Email on a request record checks syntax and nothing else, so disposable and non-existent addresses become accounts. A custom Bean Validation constraint backed by pingutil plugs into the @Valid handling you already have: a throwaway or dead address produces a field error and a 400 before your controller method runs.
Where it connects: Jakarta Bean Validation custom constraint (ConstraintValidator) with a Spring RestClient
What goes wrong without it
- @Email accepts any address with an @ and a dot, including every temp-mail service.
- Our registration service creates accounts that never confirm, and the confirmation emails bounce.
- We want the check in one annotation, not copied into every controller.
What you can do with Spring Boot and pingutil
Annotate the request record
Put @DeliverableEmail(checkMailbox = true) on the email component of your signup record. Spring validates it on @Valid and returns 400 with the field error.
Fast-only check for lead endpoints
Use @DeliverableEmail without checkMailbox on high-volume endpoints like newsletter or demo requests, where only the millisecond classification is worth the latency.
Separate timeouts per call
The client builds two RestClients from the auto-configured builder: 2 s for lookups, 5 s for mailbox checks.
Set it up
- 1
Create an API key in the pingutil dashboard and set pingutil.key (for example through the PINGUTIL_KEY environment variable).
- 2
Add spring-boot-starter-validation if it is not already on the classpath.
- 3
Add the PingutilClient component, which builds RestClients with connect and read timeouts and returns Optional.empty() on any failure.
- 4
Create the @DeliverableEmail annotation and its ConstraintValidator; Spring's validator factory injects PingutilClient into it.
- 5
Annotate the email field of your request record and keep @Valid on the controller parameter.
// Spring Boot 3.2+ / 4.x with spring-boot-starter-web and spring-boot-starter-validation.
// pingutil.key=pk_live_... in application.properties or the PINGUTIL_KEY environment variable.
// --- PingutilClient.java
import java.time.Duration;
import java.util.Map;
import java.util.Optional;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.RestClientException;
@Component
public class PingutilClient {
public record Verdict(boolean is_spam, boolean low_trust, String reason) {}
public record Lookup(String domain, String category, Verdict verdict) {}
public record Verification(String status, String reason, String did_you_mean) {}
private final RestClient fast; // /v1/lookup with skip_enrichment
private final RestClient slow; // /v1/verify (SMTP check)
public PingutilClient(RestClient.Builder builder, @Value("${pingutil.key}") String key) {
this.fast = build(builder.clone(), key, Duration.ofSeconds(2));
this.slow = build(builder.clone(), key, Duration.ofSeconds(5));
}
private static RestClient build(RestClient.Builder b, String key, Duration readTimeout) {
var factory = new SimpleClientHttpRequestFactory();
factory.setConnectTimeout(Duration.ofSeconds(1));
factory.setReadTimeout(readTimeout);
return b.baseUrl("https://pingutil.com/v1")
.defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + key)
.requestFactory(factory)
.build();
}
public Optional<Lookup> lookup(String email) {
return call(fast, "/lookup", Map.of("input", email, "skip_enrichment", true), Lookup.class);
}
public Optional<Verification> verify(String email) {
return call(slow, "/verify", Map.of("email", email), Verification.class);
}
// Empty when pingutil times out, is unreachable or answers 4xx/5xx (429 included): fail open.
private static <T> Optional<T> call(RestClient client, String path, Object body, Class<T> type) {
try {
return Optional.ofNullable(client.post().uri(path)
.contentType(MediaType.APPLICATION_JSON).body(body).retrieve().body(type));
} catch (RestClientException e) {
return Optional.empty();
}
}
}
// --- DeliverableEmail.java
import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;
@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.RECORD_COMPONENT})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = DeliverableEmailValidator.class)
public @interface DeliverableEmail {
String message() default "Please use a different email address.";
boolean checkMailbox() default false;
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
// --- DeliverableEmailValidator.java
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
import java.util.Locale;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
// Spring creates constraint validators through its own factory, so constructor injection works.
public class DeliverableEmailValidator implements ConstraintValidator<DeliverableEmail, String> {
// Domain -> category. Swap for a Caffeine or Redis cache with a one-day TTL in production.
private static final Map<String, String> CATEGORIES = new ConcurrentHashMap<>();
private final PingutilClient pingutil;
private boolean checkMailbox;
public DeliverableEmailValidator(PingutilClient pingutil) {
this.pingutil = pingutil;
}
@Override
public void initialize(DeliverableEmail annotation) {
this.checkMailbox = annotation.checkMailbox();
}
@Override
public boolean isValid(String value, ConstraintValidatorContext ctx) {
if (value == null || value.indexOf('@') < 1) return true; // format is @Email's job
String email = value.trim().toLowerCase(Locale.ROOT);
String domain = email.substring(email.lastIndexOf('@') + 1);
if ("disposable".equals(CATEGORIES.get(domain))) return false;
var lookup = pingutil.lookup(email);
if (lookup.isPresent()) {
CATEGORIES.put(lookup.get().domain(), lookup.get().category());
if (lookup.get().verdict().is_spam()) return false;
}
if (checkMailbox) {
var check = pingutil.verify(email);
if (check.isPresent() && "invalid".equals(check.get().status())) {
// Static template on purpose: never put user input (or did_you_mean) into a
// constraint message template, it is interpolated as an expression.
ctx.disableDefaultConstraintViolation();
ctx.buildConstraintViolationWithTemplate("That mailbox does not exist. Check the spelling.")
.addConstraintViolation();
return false;
}
}
return true; // pingutil unavailable lands here: fail open
}
}
// --- SignupController.java
import jakarta.validation.Valid;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
public class SignupController {
public record SignupRequest(
@NotBlank @Email @DeliverableEmail(checkMailbox = true) String email,
@NotBlank @Size(min = 12) String password) {}
@PostMapping("/signup")
public ResponseEntity<Void> signup(@Valid @RequestBody SignupRequest request) {
// Invalid input never reaches here: Spring answers 400 with the field errors.
return ResponseEntity.status(201).build();
}
}What to do with each result
| pingutil result | Action in Spring Boot |
|---|---|
| verdict.is_spam: true | isValid returns false; Spring answers 400 with the field error. |
| status: invalid | Return false with a static "mailbox does not exist" message. |
| status: risky or unknown | Return true; mark the account unconfirmed until the user clicks the link. |
| Optional.empty() (timeout, 429, 5xx) | Return true and log, so an outage never blocks registration. |
Limits to plan for
- Bean Validation is synchronous: the request thread waits for pingutil. Keep the timeouts short, or run the mailbox check asynchronously after signup.
- Do not interpolate did_you_mean or any user input into a constraint message template; send the suggestion in a separate response field if you want to show it.
- Per-account defaults: 60 requests a minute, 300 verified addresses and 2,000 lookups a day (3,000 and 30,000 a month). Catch-all domains are risky, never valid. Those are Free plan limits; Enterprise has custom limits.
Spring Boot documentation
- docs.spring.io/spring-framework/reference/core/validation/beanvalidation.html
- docs.spring.io/spring-framework/reference/integration/rest-clients.html
- docs.spring.io/spring-boot/reference/io/rest-client.html
Spring Boot is a trademark of its owner. This integration uses Spring Boot's documented extension points; it is not an official Spring Boot app.
Common questions
- Can a ConstraintValidator use Spring beans?
- Yes. When Spring bootstraps the validator, it uses a ConstraintValidatorFactory that creates validators through the application context, so constructor injection works as it does for other beans.
- Why does the example use records with snake_case component names?
- pingutil returns snake_case JSON (is_spam, did_you_mean). Matching the record components keeps the mapping explicit without a global naming strategy; @JsonProperty on camelCase components works too.
Stop bad addresses in Spring Boot today
Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Spring Boot setup will receive.