Verifalia 2.0.1

Verifalia RESTful API - .NET SDK and helper library

Verifalia provides a simple HTTPS-based API for validating email addresses in real-time and checking whether they are deliverable or not; this SDK library integrates with Verifalia and allows to verify email addresses under the following platforms:

• .NET Framework 4.5 (and higher)
• .NET Core 1.0 (and higher, including .NET Core 3.0)
• .NET Standard 1.3 (and higher)
  • Mono 4.6+
  • Xamarin.iOS 10.0+
  • Xamarin.Mac 3.0+
  • Xamarin.Android 7.0+
  • Universal Windows Platform 10.0+

To learn more about Verifalia please see https://verifalia.com

Adding Verifalia REST API support to your .NET solution

The best and easiest way to add the Verifalia email verification SDK library to your .NET project is to use the NuGet package manager.

With Visual Studio IDE

From within Visual Studio, you can use the NuGet GUI to search for and install the Verifalia NuGet package. Or, as a shortcut, simply type the following command into the Package Manager Console:

Install-Package Verifalia

Manual download and compilation

As an alternative way to add the Verifalia SDK to your .NET solution, you can download the SDK source project from github, extract it to a folder of your choice and add a reference from your own project to the Verifalia SDK project. The SDK project is a C# project with support for Visual Studio 2019, which can be referenced and used with any other .NET language too, including Visual Basic (VB.NET), C++/CLI, J#, IronPython, IronRuby, F# and PowerShell.

Learn more at https://verifalia.com.

Authentication

First things first: authentication to the Verifalia API is performed by way of either the credentials of your root Verifalia account or of one of its users (previously known as sub-accounts): if you don't have a Verifalia account, just register for a free one. For security reasons, it is always advisable to create and use a dedicated user for accessing the API, as doing so will allow to assign only the specific needed permissions to it.

Learn more about authenticating to the Verifalia API at https://verifalia.com/developers#authentication

Once you have your Verifalia credentials at hand, use them while creating a new instantance of the VerifaliaRestClient type, which will be the starting point to every other operation against the Verifalia API:

using Verifalia.Api;

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

Validating email addresses

Every operation related to verifying / validating email addresses is performed through the EmailValidations property exposed by the VerifaliaRestClient instance you created above. The property is filled with useful methods, each one having lots of overloads: in the next few paragraphs we are looking at the most used ones, so it is strongly advisable to explore the library and look at the embedded xmldoc help for other opportunities.

How to validate an email address

To validate an email address from a .NET application you can invoke the SubmitAsync() method: it accepts one or more email addresses and any eventual verification options you wish to pass to Verifalia, including the expected results quality, deduplication preferences and processing priority.

In the next example, we are showing how to verify a single email address using this library; as the entire process is asynchronous, we are passing a WaitingStrategy value, asking SubmitAsync() to automatically wait for the job completion:

var validation = await verifalia
    .EmailValidations
    .SubmitAsync("batman@gmail.com", new WaitingStrategy(true));

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

var entry = validation.Entries[0];

Console.WriteLine("{0} => Classification: {1}, Status: {1}",
	entry.InputData,
	entry.Classification,
	entry.Status);

// Prints out something like:
// batman@gmail.com => Classification: Deliverable, Status: Success

How to validate a list of email addresses

As an alternative to method above, you can avoid automatically waiting and retrieve the email validation results at a later time; this is preferred in the event you are verifying a list of email addresses, which could take minutes or even hours to complete.

Here is how to do that:

var validation = await verifalia
    .EmailValidations
    .SubmitAsync(new[] {
		"batman@gmail.com",
		"steve.vai@best.music",
		"samantha42@yahoo.de"
	});

Console.WriteLine("Job Id: {validation.Overview.Id}");
Console.WriteLine("Status: {validation.Overview.Status}");

// Prints out something like:
// Job Id: 290b5146-eeac-4a2b-a9c1-61c7e715f2e9
// Status: InProgress

Once you have an email validation job Id, which is always returned by SubmitAsync() as part of the validation's Overview property, you can retrieve the job data using the GetAsync() method. Similarly to the submission process, you can either wait for the completion of the job or just retrieve the current job snapshot to get its progress, using an instance of the same WaitingStrategy type mentioned above. Only completed jobs have their Entries filled with the email validation results, however.

In the following example, we are requesting the current snapshot of a given email validation job back from Verifalia:

var validation = await verifalia
    .EmailValidations
    .GetAsync(Guid.Parse("290b5146-eeac-4a2b-a9c1-61c7e715f2e9"));

if (validation.Overview.Status == ValidationStatus.Completed)
{
	// validation.Entries will have the validation results!
}
else
{
	// What about having a coffee?
}

And here is how to request the same job, asking the SDK to automatically wait for us until the job is completed (that is, joining the job):

var validation = await verifalia
    .EmailValidations
    .GetAsync(Guid.Parse("290b5146-eeac-4a2b-a9c1-61c7e715f2e9"),
		new WaitingStrategy(true));

Don't forget to clean up, when you are done

Verifalia automatically deletes completed jobs after 30 days since their completion: deleting completed jobs is a best practice, for privacy and security reasons. To do that, you can invoke the DeleteAsync() method passing the job Id you wish to get rid of:

await verifalia
    .EmailValidations
    .DeleteAsync(validation.Id);

Once deleted, a job is gone and there is no way to retrieve its email validation(s).

Full documentation and examples

Documenting this library within Nuget is hard because of the limited maximum content length. Please see our project page for additional help and updated examples:

https://github.com/verifalia/verifalia-csharp-sdk