verifalia csharp sdk
v4.2.1
Verifalia 提供了一个简单的基于 HTTPS 的 API，用于实时验证电子邮件地址并检查它们是否可送达；该 SDK 库与 Verifalia 集成，并允许在以下平台下验证电子邮件地址：
要了解有关 Verifalia 的更多信息，请访问 https://verifalia.com
将 Verifalia 电子邮件验证 SDK 库添加到 .NET 项目的最佳、最简单的方法是使用 NuGet 包管理器。
在 Visual Studio 中，您可以使用 NuGet GUI 搜索并安装 Verifalia NuGet 包。或者，作为快捷方式，只需在包管理器控制台中键入以下命令：
Install-Package Verifalia
作为将 Verifalia SDK 添加到 .NET 解决方案的另一种方法，您可以从 github 下载 SDK 源项目，将其解压到您选择的文件夹，然后将您自己的项目的引用添加到 Verifalia SDK 项目。 SDK 项目是一个 C# 项目，也可以引用和与任何其他 .NET 语言一起使用，包括 Visual Basic (VB.NET)、C++/CLI、J#、IronPython、IronRuby、F# 和 PowerShell。
了解更多信息，请访问 https://verifalia.com
首先，对 Verifalia API 的身份验证是通过根 Verifalia 帐户或其用户之一（以前称为子帐户）的凭据执行的：如果您没有 Verifalia 帐户，只需注册一个免费的。出于安全原因，始终建议创建并使用专用用户来访问 API，因为这样做将允许仅向其分配所需的特定权限。
了解有关 Verifalia API 身份验证的更多信息，请访问 https://verifalia.com/developers#authentication
手头拥有 Verifalia 凭据后，请在创建VerifaliaRestClient类型的新实例时使用它们，这将是针对 Verifalia API 的所有其他操作的起点：所提供的凭据将使用 HTTP Basic 自动提供给 API验证方法。
using Verifalia . Api ;
var verifalia = new VerifaliaRestClient ( "username" , "password" ) ;除了 HTTP 基本身份验证方法之外，此 SDK 还支持其他不同的方式对 Verifalia API 进行身份验证，如后续部分所述。
承载身份验证比 HTTP 基本身份验证提供更高的安全性，因为后者需要在每个 API 调用上发送实际凭据，而前者仅在第一个专用身份验证请求上需要它。另一方面，承载身份验证所需的第一个身份验证请求需要花费不可忽略的时间：如果您只需要执行单个请求，那么使用 HTTP Basic Auth 可提供相同程度的安全性，并且速度更快。
using Verifalia . Api ;
using Verifalia . Api . Security ;
var verifalia = new VerifaliaRestClient ( new BearerAuthenticationProvider ( "username" , "password" ) ) ;还可以通过定义ITotpTokenProvider接口的自定义实现来处理多重身份验证 (MFA)，该接口应用于从外部身份验证器应用程序或设备获取基于时间的一次性密码：将多重身份验证添加到您的根 Verifalia 帐户，配置您的安全设置。
using Verifalia . Api ;
using Verifalia . Api . Security ;
class MyTotpProvider : ITotpTokenProvider
{
public Task < string > ProvideTotpTokenAsync ( CancellationToken cancellationToken )
{
// Ask the user to type his or her TOTP token
Console . WriteLine ( "Acquire your TOTP token and type it here:" ) ;
var totpToken = Console . ReadLine ( ) ;
return Task . FromResult ( totpToken ) ;
}
}
// ...
var verifalia = new VerifaliaRestClient ( new BearerAuthenticationProvider ( "username" , "password" , new MyTotpProvider ( ) ) ) ; 此身份验证方法使用加密 X.509 客户端证书通过 TLS 协议针对 Verifalia API 进行身份验证。此方法也称为相互 TLS 身份验证 (mTLS) 或双向身份验证，提供最高程度的安全性，因为每次请求时仅通过线路发送加密派生密钥（而不是实际凭据）。
using Verifalia . Api ;
using Verifalia . Api . Security ;
var verifalia = new VerifaliaRestClient ( new X509Certificate2 ( "mycertificate.pem" ) ) ; 与验证/验证电子邮件地址相关的每个操作都是通过您在上面创建的VerifaliaRestClient实例公开的EmailValidations属性执行的。该属性充满了有用的方法，每个方法都有很多重载：在接下来的几段中，我们将讨论最常用的方法，因此强烈建议探索该库并查看嵌入式 xmldoc 帮助以寻找其他机会。
该库自动等待电子邮件验证作业的完成：如果需要，可以调整等待选项并对整个底层轮询过程进行更多控制。请参阅下面的等待选项部分了解更多详细信息。
要从 .NET 应用程序验证电子邮件地址，您可以调用SubmitAsync()方法：它接受一个或多个电子邮件地址以及您希望传递给 Verifalia 的任何最终验证选项，包括预期结果质量、重复数据删除首选项、处理优先级。
注意：如果您需要验证电子邮件地址列表，建议通过一个专用的
SubmitAsync()方法重载（请参阅下一节）一次提交所有电子邮件地址，而不是迭代源集并提交一一地址。一次性方法不仅会更快，而且还允许检测和标记重复的项目——这一功能在逐一验证电子邮件地址时不可用。
在以下示例中，我们使用默认选项通过此库验证电子邮件地址：
var job = await verifalia
. EmailValidations
. SubmitAsync ( "[email protected]" ) ;
// At this point the address has been validated: let's print its email validation
// result to the console.
var entry = job . Entries [ 0 ] ;
Console . WriteLine ( $ "Classification: { entry . Classification } (status: { entry . Status } )" ) ;
// Classification: Deliverable (status: Success)正如您所期望的，每个条目可能包含有关已验证电子邮件地址的各种附加详细信息：
| 财产 | 描述 |
|---|---|
AsciiEmailAddressDomainPart | 获取电子邮件地址的域部分，根据需要转换为 ASCII，并删除注释和折叠空格。 |
Classification | 此条目的ValidationEntryClassification值。 |
CompletedOn | 此条目完成的日期（如果有）。 |
Custom | 完成验证后传回的自定义可选字符串。要来回传递自定义值，请使用ValidationRequestEntry的Custom属性。 |
DuplicateOf | 如果此条目的Status为Duplicate ，则此电子邮件地址在父Validation中第一次出现的从零开始的索引；除了此值和最终的Custom值之外，重复的项目不会公开任何结果详细信息。 |
Index | 该条目在其Validation容器中的索引；当 API 返回项目的过滤视图时，此属性最有用。 |
InputData | 正在验证的输入字符串。 |
EmailAddress | 获取电子邮件地址，没有任何最终注释或折叠空格。如果输入数据不是语法上无效的电子邮件地址，则返回 null。 |
EmailAddressDomainPart | 获取电子邮件地址的域部分，不带注释和折叠空格。 |
EmailAddressLocalPart | 获取电子邮件地址的本地部分，不带注释和折叠空格。 |
HasInternationalDomainName | 如果为真，则该电子邮件地址具有国际域名。 |
HasInternationalMailboxName | 如果为 true，则电子邮件地址具有国际邮箱名称。 |
IsDisposableEmailAddress | 如果属实，则电子邮件地址来自一次性电子邮件地址 (DEA) 提供商。什么是一次性电子邮件地址？ |
IsFreeEmailAddress | 如果为真，则电子邮件地址来自免费电子邮件地址提供商（例如 gmail、yahoo、outlook / hotmail...）。 |
IsRoleAccount | 如果为 true，则电子邮件地址的本地部分是众所周知的角色帐户。 |
Status | 该条目的ValidationEntryStatus值。 |
Suggestions | 如果 Verifalia 在验证过程中发现了潜在的拼写错误，则可能对输入数据进行更正。 |
SyntaxFailureIndex | 最终导致语法验证失败的字符在电子邮件地址中的位置。 |
这是另一个示例，显示了 Verifalia 提供的一些附加结果详细信息：
var job = await verifalia
. EmailValidations
. SubmitAsync ( "bat[[email protected]" ) ;
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:
// - [email protected]要验证电子邮件地址列表（而不是单个地址），可以使用接受IEnumerable<string>的SubmitAsync()方法重载；如果要验证的电子邮件地址最初存储在文件中，也可以简单地上传文件并让 Verifalia 自动导入并验证它 - 有关详细信息，请参阅下一节。
以下示例展示了如何使用某些电子邮件地址验证数组：
var job = await verifalia
. EmailValidations
. SubmitAsync ( new [ ] {
"[email protected]" ,
"[email protected]" ,
"[email protected]"
} ) ;
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
// - [email protected] => Deliverable (Success)
// - [email protected] => Undeliverable (DomainIsMisconfigured)
// - [email protected] => Deliverable (Success)该库支持使用电子邮件地址提交和验证文件，包括：
要提交和验证文件，仍然可以使用上面提到的SubmitAsync()方法，传递Stream或FileInfo实例或仅传递带有文件内容的byte[] 。除此之外，还可以指定要处理的最终开始和结束行、列、工作表索引、行结束符和分隔符 - 当然取决于提交文件的性质（请参阅源代码中的FileValidationRequest了解更多）。
以下是提交和验证 Excel 文件的方法，例如：
var job = await verifalia
. EmailValidations
. SubmitAsync ( new FileInfo ( "that-file.xslx" ) ) ;对于更高级的选项，只需将FileValidationRequest实例传递给SubmitAsync()方法：
var job = await verifalia
. EmailValidations
. SubmitAsync ( new FileValidationRequest ( new FileInfo ( "that-file.xslx" ) )
{
Sheet = 3 ,
StartingRow = 1 ,
Column = 5
} ,
quality : QualityLevelName . High ) ;这是另一个示例，展示如何提交Stream实例并指定文件的 MIME 内容类型，在您传递FileInfo实例时，该类型会根据文件扩展名自动确定：
Stream inputStream = .. . ; // TODO: Acquire the input data somehow
var job = await verifalia
. EmailValidations
. SubmitAsync ( inputStream ,
MediaTypeHeaderValue . Parse ( WellKnownMimeContentTypes . TextPlain ) ) ; // text/plain在提交一个或多个电子邮件地址进行验证时，可以指定多个选项，这些选项会影响 Verifalia 处理引擎的行为以及从 API 使用者的角度来看的验证流程。
Verifalia 提供三种不同的质量级别 - 即标准、高和极端- 这些级别排除了电子邮件验证引擎应如何处理临时无法送达问题、较慢的邮件交换器和其他可能影响验证结果质量的潜在暂时性问题。 SubmitAsync()方法重载接受一个quality参数，该参数允许指定所需的质量级别；以下示例展示了如何使用高质量级别验证电子邮件地址：
var job = await verifalia
. EmailValidations
. SubmitAsync ( "[email protected]" , quality : QualityLevelName . High ) ; SubmitAsync()方法重载，一次接受多个电子邮件地址，允许指定如何处理属于同一输入集的重复条目； Verifalia 支持安全重复数据删除模式（严格遵守旧的 IETF 标准）和宽松模式（更符合当今大多数邮件交换器配置中的模式）。
在下一个示例中，我们将展示如何导入和验证电子邮件地址列表以及如何使用宽松重复数据删除模式标记重复条目：
var job = await verifalia
. EmailValidations
. SubmitAsync ( new FileInfo ( "that-file.xslx" ) , deduplication : DeduplicationMode . Relaxed ) ; Verifalia 会根据帐户级别定义的数据保留策略自动删除已完成的电子邮件验证作业，该策略最终可以在用户级别覆盖：可以使用 Verifalia 客户端区域来配置这些设置。
还可以指定每个作业的数据保留策略，该策略控制已提交的电子邮件验证作业的生存时间；为此，请使用SubmitAsync()方法重载，该方法重载接受ValidationRequest或FileValidationRequest实例并相应地初始化其Retention属性。
例如，在验证电子邮件地址时，可以设置 10 分钟的数据保留策略：
var job = await verifalia
. EmailValidations
. SubmitAsync ( new ValidationRequest ( new [ ]
{
"[email protected]"
} )
{
Retention = TimeSpan . FromMinutes ( 10 )
} ) ;默认情况下， SubmitAsync()方法重载向 Verifalia 提交电子邮件验证作业并等待其完成；整个过程可能需要一些时间才能完成，具体取决于 Verifalia 帐户的计划、提交的电子邮件地址数量、指定的质量级别以及其他网络因素（包括测试中的邮件交换器的延迟）。
在等待给定电子邮件验证作业完成时，该库会自动轮询底层 Verifalia API，直到结果准备就绪；默认情况下，它尝试利用 Verifalia API v2.4 引入的长轮询模式，该模式可以最大限度地减少请求数量并更快地获得验证结果。
然而，在某些情况下（例如，在微服务架构中），最好避免等待作业完成，而是请求 Verifalia API 将其排队：在这种情况下，库将只返回作业概述（而不是其验证结果），并且需要使用GetAsync()方法检索验证结果。
为此，可以将WaitOptions.NoWait指定为SubmitAsync()方法重载的waitOptions参数的值，如下例所示：
var job = await verifalia
. EmailValidations
. SubmitAsync ( new FileInfo ( "that-file.xslx" ) ,
waitOptions : WaitOptions . NoWait ) ;
Console . WriteLine ( $ "Status: { job . Overview . Status } " ) ;
// Status: InProgress 对于具有大量电子邮件地址的作业，在 Verifalia 电子邮件验证引擎处理这些作业时跟踪进度可能会很有用；为此，可以创建WaitOptions类的实例并提供最终通过Progress属性接收进度通知的处理程序。
以下是如何定义一个进度通知处理程序，该处理程序将已提交作业的进度百分比显示到控制台窗口：
var job = await verifalia
. EmailValidations
. SubmitAsync ( new FileInfo ( "that-other-file.csv" ) ,
waitOptions : new WaitOptions
{
Progress = new Progress < ValidationOverview > ( overview =>
{
Console . WriteLine ( overview . Progress ? . Percentage ) ;
} )
} ) ;与每个电子邮件验证作业一起，可以指定 Verifalia 在作业完成后调用 (POST) 的 URL：此 URL 必须使用 HTTPS 或 HTTP 方案，并且可以通过 Internet 公开访问。要了解有关完成回调的更多信息，请参阅 https://verifalia.com/developers#email-validations-completion-callback
要指定完成回调 URL，请将ValidationRequest或FileValidationRequest传递给SubmitAsync()方法，并相应地设置其CompletionCallback属性，如下例所示：
await verifalia
. EmailValidations
. SubmitAsync ( new ValidationRequest ( new [ ] { "[email protected]" } )
{
CompletionCallback = new CompletionCallback ( "https://your-website-here/foo/bar" )
} ) ;请注意，完成回调是异步调用的，调用回调 URL 可能需要几秒钟的时间。
可以通过GetAsync()和GetOverviewAsync()方法检索作业，这两个方法分别返回所需电子邮件验证作业的Validation实例或ValidationOverview实例。在执行此操作时，库会自动等待作业完成，并且可以通过向上述方法传递waitOptions参数来调整此行为，其方式与SubmitAsync()方法重载所描述的方式完全相同；请参阅等待选项部分了解更多详细信息。
以下示例展示了如何在给定标识符的情况下检索作业：
var jobId = Guid . Parse ( "ec415ecd-0d0b-49c4-a5f0-f35c182e40ea" ) ;
var job = await verifalia . EmailValidations . GetAsync ( jobId ) ;该库还允许通过ExportEntriesAsync()方法以不同的输出格式导出已完成的电子邮件验证作业的条目，目的是生成验证结果的人类可读表示。
警告：虽然输出架构（列/标签/数据格式）相当完整，但您应该始终将其视为可能会更改：如果您需要依赖稳定的输出架构，请使用
GetAsync()/GetEntriesAsync()方法。
以下示例展示了如何将给定电子邮件验证作业导出为逗号分隔值 (CSV) 文件：
// Exports the validated entries for the job in the CSV format
var exportedStream = await verifalia
. EmailValidations
. ExportEntriesAsync ( new Guid ( "722c2fd8-8837-449f-ad24-0330c597c993" ) ,
ExportedEntriesFormat . Csv ) ;
// Creates the output file stream
var fileStream = new FileStream ( "my-list.csv" , FileMode . Create ) ;
// Copies the exported stream into the output file stream
await exportedStream . CopyToAsync ( fileStream ) ;Verifalia 会在可配置的数据保留策略后自动删除已完成的作业（请参阅相关部分），但出于隐私和安全原因，强烈建议您尽快删除已完成的作业。为此，您可以调用DeleteAsync()方法并传递您希望删除的作业 Id：
await verifalia
. EmailValidations
. DeleteAsync ( job . Id ) ;一旦删除，作业就会消失，并且无法检索其电子邮件验证结果。
出于管理和报告目的，您可能需要获取过去电子邮件验证作业的详细列表。此 SDK 库允许通过ListAsync()方法执行此操作，该方法允许异步迭代ValidationOverview实例的集合（与SubmitAsync()和GetAsync()返回的结果的Overview属性的类型相同）。
以下是如何迭代您的作业（从最新到最旧的作业）：
var jobOverviews = verifalia
. EmailValidations
. ListAsync ( new ValidationOverviewListingOptions
{
Direction = Direction . Backward
} ) ;
await foreach ( var jobOverview in jobOverviews )
{
Console . WriteLine ( "Id: {0}, status: {2}, entries: {3}" ,
jobOverview . Id ,
jobOverview . Status ,
jobOverview . 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
// ...
ListAsync()方法使用C# 8.0 异步可枚举功能；对于以前的语言支持，请检查ListSegmentedAsync()方法组。
ListAsync()方法还能够通过相同的options参数来过滤 Verifalia API 返回的电子邮件验证作业：可以按提交日期、所有者和作业状态进行过滤。
以下是如何重复上面示例中显示的列表操作，这次仅返回给定用户和给定日期范围内的作业：
var jobOverviews = verifalia
. EmailValidations
. ListAsync ( new ValidationOverviewListingOptions
{
Direction = Direction . Backward ,
CreatedOn = new DateBetweenPredicate ( new DateTime ( 2024 , 1 , 3 ) ,
new DateTime ( 2024 , 1 , 7 ) ) ,
Owner = new StringEqualityPredicate ( "50173acd-9ed2-4298-ba7f-8ccaeed48deb" )
} ) ;
await foreach ( var jobOverview in jobOverviews )
{
// ...
} 要管理您帐户的 Verifalia 积分，您可以使用上面创建的VerifaliaRestClient实例公开的Credits属性。与上一个主题一样，在接下来的几段中，我们将讨论最常用的操作，因此强烈建议探索该库并查看嵌入式 xmldoc 帮助以寻找其他机会。
您可能需要在帐户上执行的最常见任务之一是检索可用的每日免费积分和积分包数量。为此，您可以使用GetBalanceAsync()方法，该方法返回Balance对象，如下例所示：
var balance = await verifalia
. Credits
. GetBalanceAsync ( ) ;
Console . WriteLine ( "Credit packs: {0}, free daily credits: {1} (will reset in {2})" ,
balance . CreditPacks ,
balance . FreeCredits ,
balance . FreeCreditsResetIn ) ;
// Prints out something like:
// Credit packs: 956.332, free daily credits: 128.66 (will reset in 09:08:23)要将积分包添加到您的 Verifalia 帐户，请访问 https://verifalia.com/client-area#/credits/add。
作为监视和预测帐户积分消耗的一种方法，方法ListDailyUsagesAsync()允许检索有关历史积分使用情况的统计信息，返回DailyUsage实例的异步可迭代集合。该方法还允许通过传递DailyUsageListingOptions实例来限制感兴趣的时间段。仅返回发生消费（免费积分、积分包或两者）的日期的元素。
以下是检索最近三十天的每日积分消耗的方法：
var dailyUsages = verifalia
. Credits
. ListDailyUsagesAsync ( new DailyUsageListingOptions
{
DateFilter = new DateBetweenPredicate
{
Since = DateTime . Now . AddDays ( - 30 )
}
} ) ;
await foreach ( var dailyUsage in dailyUsages )
{
Console . WriteLine ( "{0:yyyyMMdd} - credit packs: {1}, free daily credits: {2}" ,
dailyUsage . Date ,
dailyUsage . CreditPacks ,
dailyUsage . FreeCredits ) ;
}
// Prints out something like:
// 20240201 - credit packs: 1965.68, free daily credits: 200
// 20240126 - credit packs: 0, free daily credits: 185.628
// 20240125 - credit packs: 15.32, free daily credits: 200
// ...
ListDailyUsagesAsync()方法使用C# 8.0 异步可枚举功能；有关以前的语言支持，请检查ListDailyUsagesSegmentedAsync()方法组。
本节列出了该库当前主要版本的变更日志：对于旧版本，请参阅项目版本。为了清楚起见，排除了构建和修订更新的日志。
发布于 2024 年 1 月 11日
发布于 2023 年 5 月 26日
ToAsyncEnumerableAsync()方法的问题发布于 2023 年 2 月 27日
WaitingStrategy重命名为WaitOptions并重构后者，以便现在允许调整基础轮询等待时间WaitOptions类进行更改）ValidationRequest和FileValidationRequest类的CompletionCallback属性现在指向完整的CompletionCallback类，而不是简单的Uri
