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
