Email Verification API Client (Version 3.5)

About

This is a .NET package built for easy integration with Email Hippo RESTful (v3) API service editions. For further information on the RESTful server side implementation, please see the Docs and Schema.

How to get the package

From Nuget.

Install-Package EmailHippo.EmailVerify.Api.V3.Client
Install-Package System.Runtime.Serialization.Primitives

Who is the package for?

• .NET developers and system integrators needing a fast start to using Email Hippo technology.

What this package can do

If you're working in the .NET environment, this package can save you hours of work writing your own JSON parsers, message pumping logic, threading and logging code.

Prerequisites

• Visual Studio 2017 or later
• .NET Standard 2.0 or later
• API license key from Email Hippo

Features

• Built for high performance throughput. Will scale for concurrency and performance based on your hardware configuration (i.e. more CPU cores = more throughput).
• Sync and async methods.
• ^new Pass custom data in validation operations. Useful for passing your other data (e.g. CRM) around with email validation operations. For example, inseret a unique identifier (your CRM database ID?) around to save having to match-back data later in processing.
• Parallel batch processing available.
• Progress reporting via event callbacks built in.
• Extensive Logging built in using Microsoft.Extensions.Logging.

Performance

Fast throughput can be achieved by sending lists (IList) of emails for processing. Speed of overall processing depends on your hardware configuration (i.e. number of effective CPU cores and available RAM).

Processing for lists of email is executed in parallel using multiple threads.

Typical Processing Speed Results

Test Hardware Configuration

• CPU : Intel 6850k (6 core + HT = 12 effective cores)
• RAM : 64GB
• Network (WAN) : xDSL (20Mb/sec)

notes on tests :

• tests run on sequence of randomized @gmail email addresses
• caching not a test factor (as using random email addresses)

'more' edition (i.e. everything on) timings:

'basic' edition (i.e. syntax + block lists) timings:

How to use the package

Please note that full example code for all of the snippets below are available in the "EmailHippo.EmailVerify.Api.V3.Client.Tests" project which can be found in the GitHub repository for this project.

Step 1 - license and initialize

This software must be initialized before use. Initializaton is only needed once per app domain. The best place to do this in in the hosting process bootstrap code. For example, a web app use global.asax, a console app use Main() method.

Supply license configuration to the software by providing the license key in code as part of initialization

Invoke static method ApiClientFactoryV3_5.Initialize(string licenseKey = null)... as follows if supplying the license in code:

/*Visit https://www.emailhippo.com to get a license key*/
ApiClientFactoryV3_5.Initialize("{your license key}", {Custom logger factory} [optional]);

The logger factory is of type Microsoft.Extensions.Logging and allows integration with Serilog, console, NLog and many more logging providers.

Step 2 - create

The main client object is created using a static factory as follows:

Example 2 - creating the client

var myService = ApiClientFactoryV3_5.Create();

Step 3 - use

Once you have a reference to the client object, go ahead and use it.

Example 3 - checking one or more email address synchronously

var responses = myService.Process
    (
        new VerificationRequest 
        { 
            VerificationData = new List<VerificationDataRequest> 
            {
                new VerificationDataRequest { EmailAddress = "abuse@hotmail.com", ServiceType = ServiceType.More, OtherData = "d1" },
                new VerificationDataRequest { EmailAddress = "abuse@aol.com", ServiceType = ServiceType.More, OtherData = "d2" }
            }
        }
    );

/*Process responses*/
/*..responses*/

Example 4 - checking more than one email address asynchronously

var responses = await myService.ProcessAsync
    (
       new VerificationRequest 
        { 
            VerificationData = new List<VerificationDataRequest> 
            {
                new VerificationDataRequest { EmailAddress = "abuse@hotmail.com", ServiceType = ServiceType.More, OtherData = "d1" },
                new VerificationDataRequest { EmailAddress = "abuse@aol.com", ServiceType = ServiceType.More, OtherData = "d2" }
            }
        },
        CancellationToken.None
    );

/*Process responses*/
/*..responses*/

Example 5 - progress reporting

Progress can be captured using the built in event delegate "ProgressChanged" as follows

myService.ProgressChanged += (o, args) => Console.WriteLine(JsonConvert.SerializeObject(args));

Example 6 - logging

Logging is provided using Microsoft.Extensions.Logging.

Enable logging using standard Microsoft.Extensions.Logging listeners. e.g.

public class Startup
{
private static readonly ILoggerFactory MyLoggerFactory = new LoggerFactory();

/// <summary>
/// Setup and add serilog listeners to Microsoft logging extensions.
/// </summary>
public Startup(){
    Log.Logger = new LoggerConfiguration()
                    .Enrich
                    .FromLogContext()
                    .WriteTo.LiterateConsole()
                    .CreateLogger();

            MyLoggerFactory
                .AddSerilog();
    }
}

For full details of logging options see Microsoft.Extensions.Logging.