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.
From Nuget.
Install-Package EmailHippo.EmailVerify.Api.V3.Client
Install-Package System.Runtime.Serialization.Primitives
- .NET developers and system integrators needing a fast start to using Email Hippo technology.
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.
- Visual Studio 2017 or later
- .NET Standard 2.0 or later
- API license key from Email Hippo
- 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.
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.
- 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:
# Emails | Run Time to Completion (ms) | Processing Rate (emails /sec) |
---|---|---|
20 | 1,583 | 12.63 |
50 | 1,607 | 31.13 |
100 | 4,609 | 21.69 |
'basic' edition (i.e. syntax + block lists) timings:
# Emails | Run Time to Completion (ms) | Processing Rate (emails /sec) |
---|---|---|
20 | 1,419 | 14.09 |
50 | 3,743 | 13.36 |
100 | 4,888 | 20.45 |
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.
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.
The main client object is created using a static factory as follows:
Example 2 - creating the client
var myService = ApiClientFactoryV3_5.Create();
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.