VerifyAnyEmail 1.0.0

VerifyAnyEmail .NET SDK

Official .NET client for the VerifyAnyEmail API — real-time and bulk email verification with catch-all, disposable, role, and typo detection, plus signed batch webhooks.

• Multi-targets netstandard2.0 and net8.0 (works on .NET Framework 4.6.1+, .NET Core, .NET 5+, Xamarin, Unity, etc.).
• Async, CancellationToken-aware, HttpClient-based.
• No dependencies on net8.0; only System.Text.Json on netstandard2.0.

Install

dotnet add package VerifyAnyEmail

Quickstart

using VerifyAnyEmail;

using var client = new VerifyAnyEmailClient("vae_your_api_key");

var result = await client.VerifyAsync("name@example.com");

Console.WriteLine(result.Status);      // deliverable | undeliverable | risky | unknown
Console.WriteLine(result.Score);       // 0–100
Console.WriteLine(result.SafeToSend);  // bool
Console.WriteLine(result.SubStatus);   // e.g. valid_mailbox, mailbox_not_found, catch_all
Console.WriteLine(result.Checks.Disposable);
Console.WriteLine(result.Checks.RoleBased);
Console.WriteLine(result.Checks.CatchAll);   // bool? (null when unknown)
Console.WriteLine(result.Suggestion);        // "did you mean" domain correction, or null

Verify options

var result = await client.VerifyAsync("name@example.com", new VerifyOptions
{
    SmtpProbe = false,          // DNS-only, skip the live SMTP probe
    CatchAllDetection = true,
    Source = "signup-form",     // tags the request via the X-VAE-Source header
});

Test mode (0 credits)

Any address at @test.verifyany.email returns a deterministic result without charging a credit or probing a real mailbox:

await client.VerifyAsync("deliverable@test.verifyany.email");   // status = deliverable
await client.VerifyAsync("undeliverable@test.verifyany.email"); // status = undeliverable
await client.VerifyAsync("risky@test.verifyany.email");         // status = risky
await client.VerifyAsync("unknown@test.verifyany.email");       // status = unknown

Batches

var batch = await client.VerifyBatchAsync(
    new[] { "a@example.com", "b@example.com" },
    new BatchOptions
    {
        Name = "newsletter-2026-07",
        WebhookUrl = "https://yourapp.com/hooks/vae", // optional signed batch.completed callback
    });

Console.WriteLine(batch.Id);      // poll with this
Console.WriteLine(batch.Status);  // queued
Console.WriteLine(batch.Total);

// Poll until finished
Batch status;
do
{
    await Task.Delay(TimeSpan.FromSeconds(2));
    status = await client.GetBatchAsync(batch.Id);
    Console.WriteLine($"{status.Processed}/{status.Total}");
}
while (status.Status is not ("completed" or "failed"));

// Page through results
var page = await client.GetBatchResultsAsync(batch.Id, page: 1, pageSize: 100);
Console.WriteLine(page.Total);
foreach (var row in page.Results)
    Console.WriteLine($"{row.Email}: {row.Status} ({row.Score})");

Webhooks

When a batch finishes, VerifyAnyEmail POSTs a batch.completed event to your webhookUrl with an X-VAE-Signature: sha256=<HMAC-SHA256(rawBody, yourWebhookSecret)> header. Verify it against the exact raw request body (do not re-serialize the parsed JSON), using your webhook secret from dashboard Settings.

The check is a length-safe, constant-time comparison and tolerates the sha256= prefix.

ASP.NET Core (minimal API)

app.MapPost("/hooks/vae", async (HttpRequest req) =>
{
    using var reader = new StreamReader(req.Body);
    var rawBody = await reader.ReadToEndAsync();

    var signature = req.Headers["X-VAE-Signature"].ToString();
    var secret = Environment.GetEnvironmentVariable("VAE_WEBHOOK_SECRET")!;

    if (!VerifyAnyEmailClient.VerifyWebhookSignature(rawBody, signature, secret))
        return Results.Unauthorized();

    // ... handle the event, return 2xx to acknowledge ...
    return Results.Ok();
});

There is also a byte[] overload if you already have the raw bytes:

bool ok = VerifyAnyEmailClient.VerifyWebhookSignature(rawBodyBytes, signatureHeader, secret);

Configuration

var client = new VerifyAnyEmailClient("vae_your_api_key", new VerifyAnyEmailOptions
{
    BaseUrl = "https://api.verifyany.email", // default
    Timeout = TimeSpan.FromSeconds(30),      // default 60s (ignored when HttpClient is injected)
    HttpClient = myHttpClient,               // optional; if set, the SDK does NOT dispose it
});

When the client creates its own HttpClient, it owns it — call Dispose() (or use using) when done. When you inject an HttpClient (e.g. from IHttpClientFactory), the SDK never disposes it.

Errors

Any non-success HTTP status throws VerifyAnyEmailException:

try
{
    await client.VerifyAsync("name@example.com");
}
catch (VerifyAnyEmailException ex)
{
    Console.WriteLine(ex.StatusCode);   // e.g. 402
    Console.WriteLine(ex.Code);         // machine-readable "error" from the JSON body
    Console.WriteLine(ex.Message);      // human-readable "message" from the JSON body
}

Server-side only

Your API key is a secret. Use this SDK from server-side code only — never ship your API key in a browser, mobile app, or any client that end users control. Store it in an environment variable or secret manager.

Reference

License

MIT © 2026 VerifyAnyEmail