Name: Verifalia
Author: Verifalia

Verifalia — nugetz

Install-Package Verifalia

using Verifalia.Api;

var verifalia = new VerifaliaClient("username", "password");

using Verifalia.Api;
using Verifalia.Api.Security;

var bearerAuthProvider = new BearerAuthenticationProvider("username", "password");
var verifalia = new VerifaliaClient(bearerAuthProvider);

using Verifalia.Api;
using Verifalia.Api.Security;

class MyTotpProvider : ITotpTokenProvider
{
    public Task<string> ProvideTotpTokenAsync(CancellationToken cancellationToken)
    {
        // Prompt the user to enter their TOTP token
        Console.WriteLine("Enter your TOTP token:");
        var totpToken = Console.ReadLine();

        return Task.FromResult(totpToken);
    }
}

// ...

var totpTokenProvider = new MyTotpProvider();
var bearerAuthProvider = new BearerAuthenticationProvider("username", "password", totpTokenProvider);
var verifalia = new VerifaliaClient(bearerAuthProvider);

using System.Security.Cryptography.X509Certificates;
using Verifalia.Api;

var certificate = new X509Certificate2("mycertificate.pem");
var verifalia = new VerifaliaClient(certificate);

var job = await verifalia
    .EmailVerifications
    .RunAsync("batman@gmail.com");

// At this point the address has been verified: let's print its email verification
// result to the console.

var entry = job.Entries[0];

Console.WriteLine($"Classification: {entry.Classification} (status: {entry.Status})");

// Classification: Deliverable (status: Success)

Property	Description
`AsciiEmailAddressDomainPart`	The domain part of the email address, converted to ASCII if needed, with comments and folding white spaces stripped off.
`Classification`	The `VerificationEntryClassification` value for this entry.
`CompletedOn`	The date this entry was completed, if available.
`Custom`	A custom, optional string that is passed back upon verification completion. To pass a custom value back and forth, use the `Custom` property of `VerificationRequestEntry`.
`DuplicateOf`	The zero-based index of the first occurrence of this email address in the parent `Verification`, when the `Status` for this entry is `Duplicate`. Duplicated items only expose this value and any `Custom` values.
`Index`	The index of this entry within its `Verification` container. This property is primarily useful when the API returns a filtered view of the items.
`InputData`	The input string being validated.
`EmailAddress`	The email address without any comments or folding white space. Returns null if the input data is syntactically invalid.
`EmailAddressDomainPart`	The domain part of the email address, without comments and folding white spaces.
`EmailAddressLocalPart`	The local part of the email address, without comments and folding white spaces.
`HasInternationalDomainName`	True if the email address has an international domain name.
`HasInternationalMailboxName`	True if the email address has an international mailbox name.
`IsDisposableEmailAddress`	True if the email address comes from a disposable email address (DEA) provider. <a href="https://verifalia.com/help/email-validations/what-is-a-disposable-email-address-dea">What is a disposable email address?</a>
`IsFreeEmailAddress`	True if the email address comes from a free email address provider (e.g., Gmail, Yahoo, Outlook/Hotmail).
`IsRoleAccount`	True if the local part of the email address is a well-known role account.
`Status`	The `VerificationEntryStatus` value for this entry.
`Suggestions`	Potential corrections for the input data, when Verifalia identifies possible typos during the verification process.
`SyntaxFailureIndex`	The position of the character in the email address that caused syntax validation to fail, if applicable.

var job = await verifalia
    .EmailVerifications
    .RunAsync("bat[man@gmal.com");

var entry = job.Entries[0];

Console.WriteLine($"Classification: {entry.Classification}");
Console.WriteLine($"Status: {entry.Status}");
Console.WriteLine($"Syntax failure index: {entry.SyntaxFailureIndex}");

if (entry.Suggestions != null)
{
    Console.WriteLine("Suggestions:");

    foreach (var suggestion in entry.Suggestions)
    {
        Console.WriteLine($"- {suggestion}");
    }
}

// Classification: Undeliverable
// Status: InvalidCharacterInSequence
// Syntax failure index: 3
// Suggestions:
// - batman@gmail.com

var job = await verifalia
    .EmailVerifications
    .RunAsync(new[] {
        "batman@gmail.com",
        "steve.vai@best.music",
        "samantha42@yahoo.it"
    });

Console.WriteLine($"Job ID: {job.Overview.Id}");

foreach (var entry in job.Entries)
{
    Console.WriteLine($"- {entry.InputData} => {entry.Classification} ({entry.Status})");
}

// Job Id: 290b5146-eeac-4a2b-a9c1-61c7e715f2e9
// - batman@gmail.com => Deliverable (Success)
// - steve.vai@best.music => Undeliverable (DomainIsMisconfigured)
// - samantha42@yahoo.it => Deliverable (Success)

var job = await verifalia
    .EmailVerifications
    .RunAsync(new FileInfo("emails.txt"));

var job = await verifalia
    .EmailVerifications
    .RunAsync(new FileVerificationRequest(new FileInfo("that-file.xlsx"))
        {
            Sheet = 3,
            StartingRow = 1,
            Column = 5
        },
        quality: QualityLevelName.High);

Stream inputStream = ...; // TODO: Acquire the input data somehow

var job = await verifalia
    .EmailVerifications
    .RunAsync(inputStream,
        MediaTypeHeaderValue.Parse(WellKnownMimeContentTypes.TextPlain)); // text/plain

var job = await verifalia
    .EmailVerifications
    .RunAsync("batman@gmail.com", quality: QualityLevelName.High);

var job = await verifalia
    .EmailVerifications
    .RunAsync(new FileInfo("that-file.xlsx"), deduplication: DeduplicationMode.Relaxed);

var job = await verifalia
    .EmailVerifications
    .RunAsync(new VerificationRequest(new[]
    {
        "batman@gmail.com"
    })
    {
        Retention = TimeSpan.FromMinutes(10)
    });

var job = await verifalia
    .EmailVerifications
    .RunAsync(new FileInfo("that-file.xlsx"),
        waitOptions: WaitOptions.NoWait);

Console.WriteLine($"Status: {job.Overview.Status}");
// Status: InProgress

var job = await verifalia
    .EmailVerifications
    .RunAsync(new FileInfo("that-other-file.csv"),
        waitOptions: new WaitOptions
        {
            Progress = new Progress<VerificationOverview>(overview =>
            {
                Console.WriteLine(overview.Progress?.Percentage);
            })
        });

await verifalia
    .EmailVerifications
    .RunAsync(new VerificationRequest(new[] { "batman@gmail.com" })
    {
        CompletionCallback = new CompletionCallback("https://your-website-here/foo/bar")
    });

var job = await verifalia
    .EmailVerifications
    .GetAsync("ec415ecd-0d0b-49c4-a5f0-f35c182e40ea");

// Export the validated entries for the job in CSV format
var exportedStream = await verifalia
    .EmailVerifications
    .ExportEntriesAsync("722c2fd8-8837-449f-ad24-0330c597c993",
        ExportedEntriesFormat.Csv);

// Create the output file stream
var fileStream = new FileStream("my-list.csv", FileMode.Create);

// Copy the exported stream into the output file stream
await exportedStream.CopyToAsync(fileStream);

await verifalia
    .EmailVerifications
    .DeleteAsync(job.Overview.Id);

var jobs = verifalia
    .EmailVerifications
    .ListAsync(new VerificationOverviewListingOptions
    {
        Direction = Direction.Backward
    });

await foreach (var job in jobs)
{
    Console.WriteLine($"Id: {job.Id}, status: {job.Status}, entries: {job.NoOfEntries}");
}

// Prints out something like:
//
// Id: a7784f9a-86d4-436c-b8e4-f72f2bd377ac, status: InProgress, entries: 9886
// Id: 86d57c00-147a-4736-88cc-c918260c67c6, status: Completed, entries: 1
// Id: 594bbb0f-6f12-481c-926f-606cfefc1cd5, status: Completed, entries: 1
// Id: a5c1cd5b-39cc-43bc-9a3a-ee4a0f80ee6d, status: InProgress, entries: 226
// Id: b6f69e30-60dd-4c21-b2cb-e73ba75fb278, status: Completed, entries: 12077
// Id: 5e5a97dc-459f-4edf-a607-47371c32aa94, status: Deleted, entries: 1009
// ...

var jobs = verifalia
    .EmailVerifications
    .ListAsync(new VerificationOverviewListingOptions
    {
        Direction = Direction.Backward,
        CreatedOn = new DateBetweenPredicate(new DateTime(2025, 7, 1),
            new DateTime(2025, 7, 9)),
        Owner = new StringEqualityPredicate("50173acd-9ed2-4298-ba7f-8ccaeed48deb")
    });

await foreach (var job in jobs)
{
    // ...
}

var balance = await verifalia
    .Credits
    .GetBalanceAsync();

Console.WriteLine($"Credit packs: {balance.CreditPacks}");
Console.WriteLine($"Free daily credits: {balance.FreeCredits} (will reset in {balance.FreeCreditsResetIn})");

// Prints out something like:
//
// Credit packs: 956.332
// Free daily credits: 128.66 (will reset in 09:08:23)

var dailyUsages = verifalia
    .Credits
    .ListDailyUsagesAsync(new DailyUsageListingOptions
	{
        DateFilter = new DateBetweenPredicate
        {
            Since = DateTime.Now.AddDays(-30)
        }
    });

await foreach (var usage in dailyUsages)
{
    Console.WriteLine($"{usage.Date:yyyyMMdd}");
    Console.WriteLine($" - credit packs: {usage.CreditPacks}");
    Console.WriteLine($" - free daily credits: {usage.FreeCredits}");
}

// Prints out something like:
//
// 20250623
// - credit packs: 1965.68
// - free daily credits: 200
// 20260621
// - credit packs: 0
// - free daily credits: 185.628
// 20250620
// - credit packs: 15.32
// - free daily credits: 200
// ...

await foreach (var user in verifalia.Users.ListAsync())
{
    Console.WriteLine($"User ID: {user.Id}");
    Console.WriteLine($"- display name: {user.DisplayName}");
    Console.WriteLine($"- type: {user.Type}");
}

// Prints out something like:
//
// User ID: ed49bbce-77d1-4af3-8a15-f25e20fff123
// - display name: Walter White
// - type: Administrator
// User ID: 8eaadc82-6bf5-46b2-8ac3-f62dddfeb47e
// - display name: Alvaro Vitali
// - type: Standard

var user = await verifalia.Users.GetAsync("8eaadc82-6bf5-46b2-8ac3-f62dddfeb47e");

// Active / Inactive status
Console.WriteLine($"IsActive: {user.IsActive}");

// Default settings
Console.WriteLine($"Default data retention period: {user.Defaults?.Retention}");

// Throttling rules
Console.WriteLine("Throttling rules:");

foreach (var throttlingRule in user.Throttling?.Rules ?? [])
{
    Console.WriteLine($"- {throttlingRule.Limit} per {throttlingRule.Period}, scope: {throttlingRule.Scope}");
}

// Prints out something like:
//
// IsActive: true
// Default data retention period: 05:30:00
// Throttling rules:
// - 3 per Minute, scope: IPAddress
// - 100 per Day, scope: Global

var user = await verifalia
    .Users
    .CreateAsync(new User
    {
        Type = UserType.Standard,
        DisplayName = "James McGill",
        Authentication = new AuthenticationSettings
        {
            UsernamePasswordAuthentication = new  UsernamePasswordAuthentication
            {
                IsEnabled = true,
                Username = "jimmy",
                Password = "5058425662"
            }
        },
        Authorization = new AuthorizationSettings
        {
            Rules =
            [
                "credits:read-balance",
                "email-verifications:*:own" 
            ]
        }
    });

await verifalia
    .Users
    .UpdateAsync(user.Id,
        _ => new User
        {
            DisplayName = "Saul Goodman"
        });

await verifalia
    .Users
    .UpdateAsync(user.Id,
        _ => new User
        {
            Defaults = new DefaultSettings
            {
                Retention = TimeSpan.FromMinutes(30),
            }
        },
        user.Etag);

await verifalia
    .Users
    .DeleteAsync(user.Id);

await foreach (var certificate in verifalia.ClientCertificates.ListAsync(user.Id))
{
    Console.WriteLine($"{certificate.Subject} - {certificate.Thumbprint}");
    Console.WriteLine($"\tValidity: {certificate.NotBefore} - {certificate.NotAfter}");
}

// Prints out something like:
//
// O=Gray Matter, S=NM, C=US - 74c0fa6f23e34efc945cb96511487b0764e0e29d
//   Validity: 6/10/2025 5:33:56 PM - 6/10/2026 5:33:56 PM

var certificate = await verifalia
    .ClientCertificates
    .CreateAsync(user.Id, new FileInfo("./certificate.pem"));

Console.WriteLine($"ID: {certificate.Id}");
Console.WriteLine($"\tPublic key: {certificate.PublicKey}");
Console.WriteLine($"\tValidity: {certificate.NotBefore} - {certificate.NotAfter}");

// Prints out something like:
//
// ID: 3997d2fe-69af-43f7-9667-91204a8e7f8c
//   Public key: 87185105bfad934cf445a0f77a41a73b20309e8da9cb417771d488444fed55ec
//   Validity: 1/1/2025 10:00:00 AM - 1/1/2028 10:00:00 AM

await verifalia
    .ClientCertificates
    .DeleteAsync(user.Id, certificate.Id);

await foreach (var contactMethod in verifalia.ContactMethods.ListAsync(user.Id))
{
    Console.WriteLine($"{contactMethod.DisplayName} (ID: {contactMethod.Id})");

    if (contactMethod.Type == ContactMethodType.Email)
    {
        Console.WriteLine($"Email: {contactMethod.EmailAddress}");
    }
}

// Prints out something like:
//
// Walter White (ID: 04715cde-7910-4445-8d87-b85809267928)
// Email: walt@a1acarwash.com

var contactMethod = await verifalia.ContactMethods.GetAsync(userId, contactMethodId);

var contactMethod = await verifalia
    .ContactMethods
    .CreateAsync(user.Id,
        new ContactMethod
        {
            DisplayName = "Luigi Schroeder",
            EmailAddress = "reder28@gmail.com",
            Type = ContactMethodType.Email,
        });

await verifalia
    .ContactMethods
    .ActivateAsync("450478c3-a235-47d9-bfbb-0411d71c93eb",
        "3c4c6f8b-fdd9-4d2a-900c-1373b6e01bda",
        "abcde12345");

await verifalia
    .ContactMethods
    .UpdateAsync(user.Id,
        contactMethod.Id,
        _ => new ContactMethod
        {
            DisplayName = "Gigi Reder"
        });

await verifalia
    .ContactMethods
    .UpdateAsync(user.Id,
        contactMethod.Id,
        _ => new ContactMethod
        {
            DisplayName = "Gigi Reder"
        },
        contactMethod.Etag);

await verifalia
    .ContactMethods
    .DeleteAsync(user.Id, contactMethod.Id);

verifalia/Verifaliav5.0.0

Get Started

Readme

Verifalia API - .NET SDK and Helper Library

⭐️⭐️⭐️ Enjoying This Library? Please Star Our Repo! ⭐️⭐️⭐️

Table of Contents

Adding Verifalia API Support to Your .NET Solution

From an IDE

Rider

Visual Studio

Visual Studio Code

Manual Download and Compilation

Authentication

Basic Authentication

Bearer Token Authentication

X.509 Client Certificate (TLS Mutual Authentication)

Email Verifications

How to Verify an Email Address

How to Verify a List of Email Addresses

How to Import and Verify a File of Email Addresses

Processing Options

Quality Level

Deduplication Mode

Data Retention

Wait Options

Avoid Waiting

Progress Tracking

Completion Callbacks

Retrieving Jobs

Exporting Email Verification Results in Different Output Formats

Don't Forget to Clean Up When You're Done

Iterating Over Your Email Verification Jobs

Filtering Email Verification Jobs

Managing Credits

Getting the Credits Balance

Retrieving Credits Usage Statistics

Users and Team Management

Listing Users

Retrieving User Details

Creating Users

Updating Users

Deleting Users

X.509 Client Certificates

Listing Certificates

Creating Certificates

Deleting Certificates

Contact Methods

Listing Contact Methods

Retrieving Contact Methods

Creating Contact Methods

Activating Contact Methods

Updating Contact Methods

Deleting Contact Methods

Changelog / What's New

v5.0