Email Verification in Kotlin: Spring Boot Integration with Coroutines

Why Kotlin for Verification Integrations

Kotlin has become the preferred JVM language for modern backend development, particularly in Spring Boot applications. For email verification integrations, Kotlin offers several advantages over Java: data classes that reduce boilerplate when mapping API responses, null safety that prevents the NullPointerExceptions common in API integration code, and coroutines that provide lightweight concurrency without the overhead of thread-per-request models.

This guide walks through integrating EmailVerifierAPI's v2 endpoint into a Kotlin Spring Boot application, from a single-request service class to a coroutine-powered batch processor.

Testing with cURL

Before writing Kotlin code, verify your API key with a direct request:

curl -X GET "https://www.emailverifierapi.com/v2/verify?email=test@example.com&apikey=YOUR_API_KEY"

The response:

{
  "status": "passed",
  "isDisposable": false,
  "isFreeService": true,
  "isOffensive": false,
  "isRoleAccount": false,
  "isGibberish": false,
  "smtp_check": "success",
  "sub_status": "mailboxExists"
}

Data Classes and Response Mapping

Kotlin's data classes map the API response into a strongly-typed structure with minimal code. Jackson's Kotlin module handles the JSON deserialization automatically:

import com.fasterxml.jackson.annotation.JsonProperty

data class VerificationResult(
    val status: String,
    @JsonProperty("isDisposable") val isDisposable: Boolean,
    @JsonProperty("isFreeService") val isFreeService: Boolean,
    @JsonProperty("isOffensive") val isOffensive: Boolean,
    @JsonProperty("isRoleAccount") val isRoleAccount: Boolean,
    @JsonProperty("isGibberish") val isGibberish: Boolean,
    @JsonProperty("smtp_check") val smtpCheck: String,
    @JsonProperty("sub_status") val subStatus: String
) {
    fun isPassed() = status == "passed"
    fun isSafeToSend() = isPassed()
        && !isDisposable
        && !isRoleAccount
        && !isGibberish
}

The Verification Service

The service class wraps the API call using Spring's WebClient. The suspend keyword integrates with Kotlin coroutines, making the non-blocking HTTP call look like synchronous code:

import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Service
import org.springframework.web.reactive.function.client.WebClient
import org.springframework.web.reactive.function.client.awaitBody
import java.net.URLEncoder

@Service
class EmailVerifierService(
    @Value("${emailverifier.api-key}") private val apiKey: String
) {
    private val client = WebClient.builder()
        .baseUrl("https://www.emailverifierapi.com")
        .build()

    suspend fun verify(email: String): Result<VerificationResult> =
        runCatching {
            client.get()
                .uri("/v2/verify?email={email}&apikey={key}",
                    URLEncoder.encode(email, "UTF-8"), apiKey)
                .retrieve()
                .awaitBody<VerificationResult>()
        }
}

Batch Processing with Coroutines

For processing large lists, Kotlin coroutines combined with a semaphore provide clean, bounded-concurrency batch verification. Each email gets its own coroutine, but the semaphore limits how many are active simultaneously:

import kotlinx.coroutines.*
import kotlinx.coroutines.sync.Semaphore
import kotlinx.coroutines.sync.withPermit

@Service
class BatchVerifierService(
    private val verifier: EmailVerifierService
) {
    suspend fun verifyBatch(
        emails: List<String>,
        concurrency: Int = 15
    ): Map<String, Result<VerificationResult>> = coroutineScope {
        val semaphore = Semaphore(concurrency)

        emails.map { email ->
            async {
                semaphore.withPermit {
                    email to verifier.verify(email)
                }
            }
        }.awaitAll().toMap()
    }
}

// Usage in a controller or service:
// val results = batchVerifier.verifyBatch(emailList, concurrency = 10)
// val passed = results.filter { it.value.getOrNull()?.isPassed() == true }
// val failed = results.filter { it.value.getOrNull()?.status == "failed" }
// val safe = results.filter { it.value.getOrNull()?.isSafeToSend() == true }

Understanding the Response Fields

The "status" field drives your primary logic: "passed" confirms deliverability, "failed" means suppress immediately, "unknown" indicates an inconclusive check (often a catch-all domain), and "transient" signals a temporary server error warranting a retry. The convenience method isSafeToSend() on the data class combines the status check with flag evaluation, giving you a single boolean for the most common routing decision.

The boolean flags add context that the status alone does not capture. An address can be "passed" (the mailbox exists) while also being disposable, role-based, or gibberish. In a Spring Boot application, you might use these flags to drive different downstream behaviors: route disposable addresses to a fraud review queue, send role-based addresses through a different nurture track, or flag gibberish addresses for automatic suppression.

The "sub_status" field provides the most specific diagnostic data. "mailboxExists" confirms full deliverability. "isCatchall" tells you the domain accepts all addresses, so the mailbox-level check is inconclusive. "isGreylisting" means the server temporarily rejected the probe, and a delayed retry is appropriate. "mailboxIsFull" indicates the mailbox exists but cannot accept new messages, which is a transient condition that may resolve on its own.

Spring Boot Configuration

Add your API key to application.yml or application.properties and ensure your project includes the spring-boot-starter-webflux and kotlinx-coroutines-reactor dependencies. The WebClient bean created in the service class uses Spring's connection pooling and event loop by default, so no additional configuration is needed for production-grade HTTP performance. For rate limit handling, the semaphore concurrency value should match your API plan's allowance. Start at 15 and adjust based on observed throughput.

Frequently Asked Questions

Do I need WebFlux for this integration, or does it work with Spring MVC?

The WebClient is part of the WebFlux module, but you can use it in a traditional Spring MVC application by adding the webflux dependency alongside your web dependency. The coroutine-based approach shown here works in both servlet and reactive Spring Boot applications. You do not need to convert your entire application to WebFlux.

How does the Semaphore control rate limiting?

The Semaphore limits the number of coroutines that can execute the API call concurrently. When all permits are in use, additional coroutines suspend (not block) until a permit becomes available. This provides natural backpressure without consuming threads, which is more efficient than thread-based rate limiting approaches.

Can I use this with Spring Boot 2, or is Spring Boot 3 required?

The code works with both Spring Boot 2 and 3. The main difference is the Jakarta namespace change in Boot 3 (javax to jakarta), which does not affect the verification integration code. Ensure you are using kotlinx-coroutines-reactor version 1.6+ for the awaitBody extension function.

How should I handle the Result type in my calling code?

Kotlin's Result type wraps either a success value or an exception. Use getOrNull() for safe access, isSuccess/isFailure for branching, and fold() for transforming both cases. For batch results, filter on getOrNull()?.isPassed() to extract verified addresses, and log any isFailure results for debugging transient API issues.