Email verification in Rust

[dependencies]
reqwest = { version = "0.12", features = ["json"] }
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
thiserror = "1"
futures = "0.3"

use serde::Deserialize;
use std::time::Duration;

#[derive(Debug, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum Verdict {
    Valid,
    Invalid,
    CatchAll,
    Unknown,
}

#[derive(Debug, Deserialize)]
pub struct VerifyResult {
    pub email: String,
    pub result: Verdict,
    pub reason: String,          // keep it a String: the list of reasons can grow
    pub smtp_code: Option<String>,
    pub role: bool,              // flags sit beside the result, never inside it
    pub disposable: bool,
    pub billed: bool,
}

#[derive(Clone)]
pub struct ZapBounce {
    http: reqwest::Client,
    key: String,
}

impl ZapBounce {
    pub fn new(key: impl Into<String>) -> Result<Self, Error> {
        let http = reqwest::Client::builder()
            .timeout(Duration::from_secs(15))
            .connect_timeout(Duration::from_secs(3))
            .pool_max_idle_per_host(20)
            .build()?;
        Ok(Self { http, key: key.into() })
    }

    pub async fn verify(&self, email: &str) -> Result<VerifyResult, Error> {
        let response = self
            .http
            .post("https://api.zapbounce.com/v1/verify")
            .bearer_auth(&self.key)
            .json(&serde_json::json!({ "email": email }))
            .send()
            .await?;

        if !response.status().is_success() {
            return Err(Error::from_response(response).await);
        }
        Ok(response.json().await?)
    }
}

// Exhaustive. Add a variant to Verdict and every match in the codebase fails to build.
match result.result {
    _ if result.disposable => suppression.add(&result.email),
    Verdict::Valid if result.role => segments.push("shared-mailbox", &result.email),
    Verdict::Valid => mailer.send(&result.email).await?,
    Verdict::CatchAll => segments.push("accepts-everything", &result.email),
    Verdict::Unknown => recheck_queue.push(&result.email),
    Verdict::Invalid => suppression.add(&result.email),
}

use futures::stream::{self, StreamExt};

/// Bounded concurrency. buffer_unordered caps in-flight requests, which keeps
/// you inside the rate limit instead of discovering it as a wall of 429s.
pub async fn verify_many(client: &ZapBounce, emails: Vec<String>) -> Vec<Outcome> {
    stream::iter(emails)
        .map(|email| {
            let client = client.clone();   // cheap: the pool is shared, not copied
            async move {
                let result = client.verify(&email).await;
                Outcome { email, result }
            }
        })
        .buffer_unordered(16)
        .collect()
        .await
}

/// For a list, submit a batch and let the server pace probes per mail host.
impl ZapBounce {
    pub async fn submit_batch(&self, name: &str, emails: &[String]) -> Result<String, Error> {
        #[derive(Deserialize)]
        struct Created { batch_id: String }

        let created: Created = self
            .http
            .post("https://api.zapbounce.com/v1/batches")
            .bearer_auth(&self.key)
            .header("Idempotency-Key", uuid::Uuid::new_v4().to_string())
            .json(&serde_json::json!({ "name": name, "emails": emails }))
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;

        Ok(created.batch_id)
    }
}

use thiserror::Error;

#[derive(Debug, Error)]
pub enum Error {
    #[error("zapbounce api: {message} ({code}, request_id={request_id})")]
    Api { code: String, message: String, request_id: String, status: u16 },

    #[error("transport: {0}")]
    Transport(#[from] reqwest::Error),
}

impl Error {
    /// A 402 fails identically forever. Retrying it only wastes the budget.
    pub fn retryable(&self) -> bool {
        match self {
            Error::Api { status, .. } => *status == 429 || *status >= 500,
            Error::Transport(e) => e.is_timeout() || e.is_connect(),
        }
    }
}

pub async fn verify_with_retry(client: &ZapBounce, email: &str) -> Result<VerifyResult, Error> {
    let mut attempt = 0;
    loop {
        match client.verify(email).await {
            Ok(result) => return Ok(result),
            Err(e) if !e.retryable() || attempt >= 4 => return Err(e),
            Err(_) => {
                let base = 500u64 << attempt;
                let jitter = rand::random::<u64>() % base.max(1);
                tokio::time::sleep(Duration::from_millis(base + jitter)).await;
                attempt += 1;
            }
        }
    }
}