Email verification in .NET

dotnet add package Microsoft.Extensions.Http

// Program.cs — registration, once.
builder.Services.AddHttpClient<IVerificationClient, VerificationClient>(client =>
{
    client.BaseAddress = new Uri("https://app.zapbounce.com/api/v1/");
    client.DefaultRequestHeaders.Add("X-API-Key", builder.Configuration["ZapBounce:Key"]);
    client.Timeout = TimeSpan.FromSeconds(15);
})
.SetHandlerLifetime(TimeSpan.FromMinutes(5));   // picks up DNS changes on failover

builder.Services.AddSingleton(Channel.CreateBounded<string>(
    new BoundedChannelOptions(10_000) { FullMode = BoundedChannelFullMode.Wait }));
builder.Services.AddHostedService<VerificationWorker>();

// The interface exists so a test can substitute it without an HTTP stub.
public interface IVerificationClient
{
    // POST /verify with { "emails": [email] }; returns results[0] (status, reasonCode, flags, smtpCode, checkedAt).
    Task<VerifyResult> VerifyAsync(string email, CancellationToken ct = default);

    // POST /jobs with { "emails": [...], "source": "api" }; returns the job id to poll.
    Task<string> SubmitJobAsync(IReadOnlyCollection<string> emails, CancellationToken ct = default);
}

public sealed class VerificationWorker(
    Channel<string> channel,
    IVerificationClient client,
    IServiceScopeFactory scopes,
    ILogger<VerificationWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Buffer addresses and submit as jobs: one call of 5,000 beats 5,000 calls (a job takes up to 50,000).
        var buffer = new List<string>(capacity: 5_000);

        await foreach (var email in channel.Reader.ReadAllAsync(stoppingToken))
        {
            buffer.Add(email);
            if (buffer.Count < 5_000) continue;

            await FlushAsync(buffer, stoppingToken);
            buffer.Clear();
        }

        // Shutdown: whatever is buffered still gets submitted.
        if (buffer.Count > 0)
            await FlushAsync(buffer, CancellationToken.None);
    }

    private async Task FlushAsync(List<string> emails, CancellationToken ct)
    {
        try
        {
            var jobId = await client.SubmitJobAsync(emails, ct);
            logger.LogInformation("submitted {Count} addresses as job {JobId}", emails.Count, jobId);
            // No webhook: a separate poller reads GET jobs/{id} until the status is
            // completed, partial, failed or cancelled, then pages GET jobs/{id}/emails.
        }
        catch (ZapBounceException e) when (e.Code == "CREDITS_INSUFFICIENT")
        {
            logger.LogError("out of credits; {Count} addresses returned to the queue", emails.Count);
            foreach (var email in emails) await channel.Writer.WriteAsync(email, ct);
        }
    }
}

// Fail open at the edge, and record why. An unverifiable address is not a bad one.
public sealed class SafeVerificationClient(
    IVerificationClient inner,
    ILogger<SafeVerificationClient> logger) : IVerificationClient
{
    public async Task<VerifyResult> VerifyAsync(string email, CancellationToken ct = default)
    {
        try
        {
            return await inner.VerifyAsync(email, ct);
        }
        catch (TaskCanceledException) when (!ct.IsCancellationRequested)
        {
            // HttpClient surfaces its own timeout as TaskCanceledException. The
            // guard is what separates "we timed out" from "the caller canceled".
            logger.LogWarning("verification timed out for {Email}", email);
            return VerifyResult.Unresolved(email);
        }
        catch (ZapBounceException e) when (e.Retryable)
        {
            logger.LogWarning("transient failure {Code} requestId={RequestId}", e.Code, e.RequestId);
            return VerifyResult.Unresolved(email);
        }
    }

    public Task<string> SubmitJobAsync(IReadOnlyCollection<string> emails, CancellationToken ct = default)
        => inner.SubmitJobAsync(emails, ct);   // jobs are queued; let them throw
}

// Registration order matters: the decorator wraps the typed client.
builder.Services.Decorate<IVerificationClient, SafeVerificationClient>();