{"id":24902906,"url":"https://github.com/verifalia/verifalia-csharp-sdk","last_synced_at":"2025-05-08T21:14:07.471Z","repository":{"id":5607542,"uuid":"6814780","full_name":"verifalia/verifalia-csharp-sdk","owner":"verifalia","description":"Verifalia REST API - .NET SDK and helper library","archived":false,"fork":false,"pushed_at":"2024-10-31T11:46:42.000Z","size":805,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-08T21:13:47.728Z","etag":null,"topics":["c-sharp","dotnet","email","email-validation","email-verification","sdk","vb","verifalia"],"latest_commit_sha":null,"homepage":"https://verifalia.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verifalia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-11-22T15:03:35.000Z","updated_at":"2024-10-31T11:45:23.000Z","dependencies_parsed_at":"2023-01-13T13:37:10.597Z","dependency_job_id":null,"html_url":"https://github.com/verifalia/verifalia-csharp-sdk","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-csharp-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-csharp-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-csharp-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-csharp-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verifalia","download_url":"https://codeload.github.com/verifalia/verifalia-csharp-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253149617,"owners_count":21861739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-sharp","dotnet","email","email-validation","email-verification","sdk","vb","verifalia"],"created_at":"2025-02-01T22:17:45.086Z","updated_at":"2025-05-08T21:14:07.425Z","avatar_url":"https://github.com/verifalia.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Verifalia API](https://img.shields.io/badge/Verifalia%20API-v2.5-green)\n[![NuGet](https://img.shields.io/nuget/v/Verifalia.svg)](https://www.nuget.org/packages/Verifalia)\n![License](https://img.shields.io/badge/License-MIT-yellow.svg)\n\nVerifalia RESTful API - .NET SDK and helper library\n===================================================\n\n[Verifalia][0] 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][0] under the following platforms:\n\n- .NET 5.0 and higher, including **.NET 8.0**\n- .NET Core 1.0 (and higher)\n- .NET Framework 4.5 (and higher)\n- .NET Standard 1.3 (and higher)\n  - Mono 4.6+\n  - Xamarin.iOS 10.0+\n  - Xamarin.Mac 3.0+\n  - Xamarin.Android 7.0+\n  - Universal Windows Platform 10.0+\n\nTo learn more about Verifalia please see [https://verifalia.com][0]\n\n## Table of contents\n\n- [Adding Verifalia REST API support to your .NET solution](#adding-verifalia-rest-api-support-to-your-net-solution)\n  + [With Visual Studio IDE](#with-visual-studio-ide)\n  + [Manual download and compilation](#manual-download-and-compilation)\n  * [Authentication](#authentication)\n    + [Authenticating via bearer token](#authenticating-via-bearer-token)\n    + [Authenticating via X.509 client certificate (TLS mutual authentication)](#authenticating-via-x509-client-certificate--tls-mutual-authentication-)\n- [Validating email addresses](#validating-email-addresses)\n  * [How to validate an email address](#how-to-validate-an-email-address)\n  * [How to validate a list of email addresses](#how-to-validate-a-list-of-email-addresses)\n  * [How to import and submit a file for validation](#how-to-import-and-submit-a-file-for-validation)\n  * [Processing options](#processing-options)\n    + [Quality level](#quality-level)\n    + [Deduplication mode](#deduplication-mode)\n    + [Data retention](#data-retention)\n  * [Wait options](#wait-options)\n    + [Avoid waiting](#avoid-waiting)\n    + [Progress tracking](#progress-tracking)\n  * [Completion callbacks](#completion-callbacks)\n  * [Retrieving jobs](#retrieving-jobs)\n  * [Exporting email verification results in different output formats](#exporting-email-verification-results-in-different-output-formats)\n  * [Don't forget to clean up, when you are done](#don-t-forget-to-clean-up--when-you-are-done)\n  * [Iterating over your email validation jobs](#iterating-over-your-email-validation-jobs)\n    * [Filtering email validation jobs](#filtering-email-validation-jobs)\n- [Managing credits](#managing-credits)\n  * [Getting the credits balance](#getting-the-credits-balance)\n  * [Retrieving credits usage statistics](#retrieving-credits-usage-statistics)\n- [Changelog / What's new](#changelog---what-s-new)\n\n---\n\n## Adding Verifalia REST API support to your .NET solution ##\n\nThe best and easiest way to add the Verifalia email verification SDK library to your .NET project is to use the NuGet package manager.\n\n#### With Visual Studio IDE\n\nFrom 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:\n\n    Install-Package Verifalia\n\n#### Manual download and compilation\n\t\nAs an alternative way to add the Verifalia SDK to your .NET solution, you can [download the SDK source project from github][1], 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 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.\n\nLearn more at [https://verifalia.com][0]\n\n### Authentication ###\n\nFirst 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][4]. For security reasons, it is always advisable to [create and use a dedicated user][3] for accessing the API, as doing so will allow to assign only the specific needed permissions to it.\n\nLearn more about authenticating to the Verifalia API at [https://verifalia.com/developers#authentication][2]\n\nOnce you have your Verifalia credentials at hand, use them while creating a new instance of the `VerifaliaRestClient` type, which will be the starting point to every other operation against the Verifalia API: the supplied credentials will be automatically provided to the API using the HTTP Basic Auth method.\n\n```c#\nusing Verifalia.Api;\n\nvar verifalia = new VerifaliaRestClient(\"username\", \"password\");\n```\n\nIn addition to the HTTP Basic Auth method, this SDK also supports other different ways to authenticate to the Verifalia API, as explained in the subsequent sections.\n\n#### Authenticating via bearer token\n\nBearer authentication offers higher security over HTTP Basic Auth, as the latter requires sending the actual credentials on each API call, while the former only requires it on a first, dedicated authentication request. On the other side, the first authentication request needed by Bearer authentication takes a non-negligible time: if you need to perform only a single request, using HTTP Basic Auth provides the same degree of security and is also faster.\n\n```c#\nusing Verifalia.Api;\nusing Verifalia.Api.Security;\n\nvar verifalia = new VerifaliaRestClient(new BearerAuthenticationProvider(\"username\", \"password\"));\n```\n\nHandling multi-factor auth (MFA) is also possible by defining a custom implementation of the `ITotpTokenProvider` interface, which should be used to acquire the time-based one-time password from an external authenticator app or device: to add multi-factor auth to your root Verifalia account, [configure your security settings](https://verifalia.com/client-area#/account/security-settings).\n\n```c#\nusing Verifalia.Api;\nusing Verifalia.Api.Security;\n\nclass MyTotpProvider : ITotpTokenProvider\n{\n\tpublic Task\u003cstring\u003e ProvideTotpTokenAsync(CancellationToken cancellationToken)\n\t{\n\t\t// Ask the user to type his or her TOTP token\n\n\t\tConsole.WriteLine(\"Acquire your TOTP token and type it here:\");\n\t\tvar totpToken = Console.ReadLine();\n\n\t\treturn Task.FromResult(totpToken);\n\t}\n}\n\n// ...\n\nvar verifalia = new VerifaliaRestClient(new BearerAuthenticationProvider(\"username\", \"password\", new MyTotpProvider()));\n```\n\n#### Authenticating via X.509 client certificate (TLS mutual authentication)\n\nThis authentication method uses a cryptographic X.509 client certificate to authenticate against the Verifalia API, through the TLS protocol. This method, also called mutual TLS authentication (mTLS) or two-way authentication, offers the highest degree of security, as only a cryptographically-derived key (and not the actual credentials) is sent over the wire on each request.\n\n```c#\nusing Verifalia.Api;\nusing Verifalia.Api.Security;\n\nvar verifalia = new VerifaliaRestClient(new X509Certificate2(\"mycertificate.pem\"));\n```\n\n## Validating email addresses ##\n\nEvery 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.\n\n**The library automatically waits for the completion of email verification jobs**: if needed, it is possible\nto adjust the wait options and have more control over the entire underlying polling process. Please refer to\nthe [Wait options](#wait-options) section below for additional details. \n\n### How to validate an email address ###\n\nTo 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, processing priority.\n\n\u003e **Note**\n\u003e In the event you need to verify a list of email addresses, it is advisable to submit them all at once through one\n\u003e of the dedicated `SubmitAsync()` method overloads (see the next sections), instead of iterating over the\n\u003e source set and submitting the addresses one by one. Not only the all-at-once method would be faster, it would\n\u003e also allow to detect and mark duplicated items - a feature which is unavailable while verifying the email addresses\n\u003e one by one.\n\nIn the following example, we verify an email address with this library, using the default options:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(\"batman@gmail.com\");\n\n// At this point the address has been validated: let's print its email validation\n// result to the console.\n\nvar entry = job.Entries[0];\n\nConsole.WriteLine($\"Classification: {entry.Classification} (status: {entry.Status})\");\n\n// Classification: Deliverable (status: Success)\n```\n\nAs you may expect, each entry may include various additional details about the verified email address:\n\n| Property                      | Description                                                                                                                                                                                                                                                |\n|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `AsciiEmailAddressDomainPart` | Gets the domain part of the email address, converted to ASCII if needed and with comments and folding white spaces stripped off.                                                                                                                           |\n| `Classification`              | The `ValidationEntryClassification` value for this entry.                                                                                                                                                                                                  |\n| `CompletedOn`                 | The date this entry has been completed, if available.                                                                                                                                                                                                      |\n| `Custom`                      | A custom, optional string which is passed back upon completing the validation. To pass back and forth a custom value, use the `Custom` property of `ValidationRequestEntry`.                                                                               |\n| `DuplicateOf`                 | The zero-based index of the first occurrence of this email address in the parent `Validation`, in the event the `Status` for this entry is `Duplicate`; duplicated items do not expose any result detail apart from this and the eventual `Custom` values. |\n| `Index`                       | The index of this entry within its `Validation` container; this property is mostly useful in the event the API returns a filtered view of the items.                                                                                                       |\n| `InputData`                   | The input string being validated.                                                                                                                                                                                                                          |\n| `EmailAddress`                | Gets the email address, without any eventual comment or folding white space. Returns null if the input data is not a syntactically invalid e-mail address.                                                                                                 |\n| `EmailAddressDomainPart`      | Gets the domain part of the email address, without comments and folding white spaces.                                                                                                                                                                      |\n| `EmailAddressLocalPart`       | Gets the local part of the email address, without comments and folding white spaces.                                                                                                                                                                       |\n| `HasInternationalDomainName`  | If true, the email address has an international domain name.                                                                                                                                                                                               |\n| `HasInternationalMailboxName` | If true, the email address has an international mailbox name.                                                                                                                                                                                              |\n| `IsDisposableEmailAddress`    | If true, the email address comes from a disposable email address (DEA) provider. \u003ca href=\"https://verifalia.com/help/email-validations/what-is-a-disposable-email-address-dea\"\u003eWhat is a disposable email address?\u003c/a\u003e                                     |\n| `IsFreeEmailAddress`          | If true, the email address comes from a free email address provider (e.g. gmail, yahoo, outlook / hotmail, ...).                                                                                                                                           |\n| `IsRoleAccount`               | If true, the local part of the email address is a well-known role account.                                                                                                                                                                                 |\n| `Status`                      | The `ValidationEntryStatus` value for this entry.                                                                                                                                                                                                          |\n| `Suggestions`                 | The potential corrections for the input data, in the event Verifalia identified potential typos during the verification process.                                                                                                                           |\n| `SyntaxFailureIndex`          | The position of the character in the email address that eventually caused the syntax validation to fail.                                                                                                                                                   |\n\nHere is another example, showing some of the additional result details provided by Verifalia:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(\"bat[man@gmal.com\");\n\nvar entry = job.Entries[0];\n\nConsole.WriteLine($\"Classification: {entry.Classification}\");\nConsole.WriteLine($\"Status: {entry.Status}\");\nConsole.WriteLine($\"Syntax failure index: {entry.SyntaxFailureIndex}\");\n\nif (entry.Suggestions != null)\n{\n    Console.WriteLine(\"Suggestions:\");\n\n    foreach (var suggestion in entry.Suggestions)\n    {\n        Console.WriteLine($\"- {suggestion}\");\n    }\n}\n\n// Classification: Undeliverable\n// Status: InvalidCharacterInSequence\n// Syntax failure index: 3\n// Suggestions:\n// - batman@gmail.com\n```\n\n### How to validate a list of email addresses ###\n\nTo verify a list of email addresses - instead of a single address - it is possible to use the `SubmitAsync()` method\noverload which accepts an `IEnumerable\u003cstring\u003e`; if the email addresses to be verified are originally stored\nin a file, it is also possible to simply upload the file and have Verifalia automatically import and verify\nit - see the next section for the details.\n\nHere is an example showing how to verify an array with some email addresses:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(new[] {\n        \"batman@gmail.com\",\n        \"steve.vai@best.music\",\n        \"samantha42@yahoo.it\"\n    });\n\nConsole.WriteLine($\"Job ID: {job.Overview.Id}\");\n\nforeach (var entry in job.Entries)\n{\n    Console.WriteLine($\"- {entry.InputData} =\u003e {entry.Classification} ({entry.Status})\");\n}\n\n// Job Id: 290b5146-eeac-4a2b-a9c1-61c7e715f2e9\n// - batman@gmail.com =\u003e Deliverable (Success)\n// - steve.vai@best.music =\u003e Undeliverable (DomainIsMisconfigured)\n// - samantha42@yahoo.it =\u003e Deliverable (Success)\n```\n\n\n### How to import and submit a file for validation\n\nThis library includes support for submitting and validating files with email addresses, including:\n\n- **plain text files** (.txt), with one email address per line;\n- **comma-separated values** (.csv), **tab-separated values** (.tsv) and other delimiter-separated values files;\n- **Microsoft Excel spreadsheets** (.xls and .xlsx).\n\nTo submit and validate files, one can still use the `SubmitAsync()` method mentioned\nabove, passing either a `Stream` or a `FileInfo` instance or just a `byte[]` with the\nfile content. Along with that, it is also possible to specify the eventual starting\nand ending rows to process, the column, the sheet index, the line ending and the\ndelimiter - depending of course on the nature of the submitted file (see\n`FileValidationRequest` in the source to learn more).\n\nHere is how to submit and verify an Excel file, for example:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(new FileInfo(\"that-file.xslx\"));\n```\n\nFor more advanced options, just pass `FileValidationRequest` instance to the `SubmitAsync()`\nmethod:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(new FileValidationRequest(new FileInfo(\"that-file.xslx\"))\n        {\n            Sheet = 3,\n            StartingRow = 1,\n            Column = 5\n        },\n        quality: QualityLevelName.High);\n```\n\nAnd here is another example, showing how to submit a `Stream` instance and specifying the\nMIME content type of the file, which is automatically determined from the file extension in\nthe event you pass a `FileInfo` instance:\n\n```c#\nStream inputStream = ...; // TODO: Acquire the input data somehow\n\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(inputStream,\n        MediaTypeHeaderValue.Parse(WellKnownMimeContentTypes.TextPlain)); // text/plain\n```\n\n### Processing options\n\nWhile submitting one or more email addresses for verification, it is possible to specify several\noptions which affect the behavior of the Verifalia processing engine as well as the verification flow\nfrom the API consumer standpoint.\n\n#### Quality level\n\nVerifalia offers three distinct quality levels - namely, _Standard_, _High_ and _Extreme_  - which rule out how the email verification engine should\ndeal with temporary undeliverability issues, with slower mail exchangers and other potentially transient\nproblems which can affect the quality of the verification results. The `SubmitAsync()` method overloads accept a `quality` parameter which allows\nto specify the desired quality level; here is an example showing how to verify an email address using\nthe _High_ quality level:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(\"batman@gmail.com\", quality: QualityLevelName.High);\n```\n\n#### Deduplication mode\n\nThe `SubmitAsync()` method overloads accepting multiple email addresses at once allow to specify how to\ndeal with duplicated entries pertaining to the same input set; Verifalia supports a _Safe_ deduplication\nmode, which strongly adheres to the old IETF standards, and a _Relaxed_ mode which is more in line with\nwhat can be found in the majority of today's mail exchangers configurations.\n\nIn the next example, we show how to import and verify a list of email addresses and mark duplicated\nentries using the _Relaxed_ deduplication mode:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(new FileInfo(\"that-file.xslx\"), deduplication: DeduplicationMode.Relaxed);\n```\n\n#### Data retention\n\nVerifalia automatically deletes completed email verification jobs according to the data retention\npolicy defined at the account level, which can be eventually overriden at the user level: one can\nuse the [Verifalia clients area](https://verifalia.com/client-area) to configure these settings.\n\nIt is also possible to specify a per-job data retention policy which govern the time to live of a submitted\nemail verification job; to do that, use the `SubmitAsync()` method overloads which either accepts\na `ValidationRequest` or a `FileValidationRequest` instance and initialize its `Retention` property\naccordingly.\n\nHere is how, for instance, one can set a data retention policy of 10 minutes while verifying\nan email address:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(new ValidationRequest(new[]\n    {\n        \"batman@gmail.com\"\n    })\n    {\n        Retention = TimeSpan.FromMinutes(10)\n    });\n```\n\n### Wait options\n\nBy default, the `SubmitAsync()` method overloads submit an email verification job to Verifalia and wait\nfor its completion; the entire process may require some time to complete depending on the plan of the\nVerifalia account, the number of email addresses the submission contains, the specified quality level\nand other network factors including the latency of the mail exchangers under test. \n\nIn waiting for the completion of a given email verification job, the library automatically polls the\nunderlying Verifalia API until the results are ready; by default, it tries to take advantage of the long\npolling mode introduced with the Verifalia API v2.4, which allows to minimize the number of requests\nand get the verification results faster.\n\n#### Avoid waiting\n\nIn certain scenarios (in a microservice architecture, for example), however, it may be preferable to avoid\nwaiting for a job completion and ask the Verifalia API, instead, to just queue it: in that case, the library\nwould just return the job overview (and not its verification results) and it will be necessary to retrieve\nthe verification results using the `GetAsync()` method.\n\nTo do that, it is possible to specify the `WaitOptions.NoWait` as the value for the `waitOptions` parameter\nof the `SubmitAsync()` method overloads, as shown in the next example:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(new FileInfo(\"that-file.xslx\"),\n        waitOptions: WaitOptions.NoWait);\n\nConsole.WriteLine($\"Status: {job.Overview.Status}\");\n// Status: InProgress\n```\n\n#### Progress tracking\n\nFor jobs with a large number of email addresses, it could be useful to track progress as they are processed\nby the Verifalia email verification engine; to do that, it is possible to create an instance of the\n`WaitOptions` class and provide an handler which eventually receives progress notifications through the\n`Progress` property.\n\nHere is how to define a progress notification handler which displays the progress percentage of a submitted\njob to the console window:\n\n```c#\nvar job = await verifalia\n    .EmailValidations\n    .SubmitAsync(new FileInfo(\"that-other-file.csv\"),\n        waitOptions: new WaitOptions\n        {\n            Progress = new Progress\u003cValidationOverview\u003e(overview =\u003e\n            {\n                Console.WriteLine(overview.Progress?.Percentage);\n            })\n        });\n```\n\n### Completion callbacks\n\nAlong with each email validation job, it is possible to specify an URL which\nVerifalia will invoke (POST) once the job completes: this URL must use the HTTPS or HTTP\nscheme and be publicly accessible over the Internet.\nTo learn more about completion callbacks, please see https://verifalia.com/developers#email-validations-completion-callback\n\nTo specify a completion callback URL, pass either a `ValidationRequest` or a `FileValidationRequest`\nto the `SubmitAsync()` method and set its `CompletionCallback` property accordingly, as shown\nin the example below:\n\n```c#\nawait verifalia\n    .EmailValidations\n    .SubmitAsync(new ValidationRequest(new[] { \"batman@gmail.com\" })\n    {\n        CompletionCallback = new CompletionCallback(\"https://your-website-here/foo/bar\")\n    });\n```\n\nNote that completion callbacks are invoked asynchronously and it could take up to\nseveral seconds for your callback URL to get invoked.\n\n### Retrieving jobs\n\nIt is possible to retrieve a job through the `GetAsync()` and `GetOverviewAsync()` methods, which\nreturn, respectively, a `Validation` instance or a `ValidationOverview` instance for the desired\nemail verification job. While doing that, the library automatically waits for the completion of\nthe job, and it is possible to adjust this behavior by passing to the aforementioned methods\na `waitOptions` parameter, in the exactly same fashion as described for the `SubmitAsync()` method\noverloads; please see the [Wait options](#wait-options) section for additional details.\n\nHere is an example showing how to retrieve a job, given its identifier:\n\n```c#\nvar jobId = Guid.Parse(\"ec415ecd-0d0b-49c4-a5f0-f35c182e40ea\");\nvar job = await verifalia.EmailValidations.GetAsync(jobId);\n```\n\n### Exporting email verification results in different output formats\n\nThis library also allows to export the entries of a completed email validation\njob in different output formats through the `ExportEntriesAsync()` method, with the goal of generating a human-readable representation\nof the verification results.\n\n\u003e **WARNING**: While the output schema (columns / labels / data format) is fairly\n\u003e complete, you should always consider it as subject to change: use the `GetAsync()` / `GetEntriesAsync()`\n\u003e methods instead if you need to rely on a stable output schema.\n\nHere is an example showing how to export a given email verification job as a comma-separated values (CSV) file:\n\n```c#\n// Exports the validated entries for the job in the CSV format\n\nvar exportedStream = await verifalia\n    .EmailValidations\n    .ExportEntriesAsync(new Guid(\"722c2fd8-8837-449f-ad24-0330c597c993\"),\n        ExportedEntriesFormat.Csv);\n\n// Creates the output file stream\n\nvar fileStream = new FileStream(\"my-list.csv\", FileMode.Create);\n\n// Copies the exported stream into the output file stream\n\nawait exportedStream.CopyToAsync(fileStream);\n```\n\n### Don't forget to clean up, when you are done\n\nVerifalia automatically deletes completed jobs after a configurable\ndata-retention policy (see the related section) but it is strongly advisable that\nyou delete your completed jobs as soon as possible, for privacy and security reasons. To do that, you can invoke the `DeleteAsync()` method passing the job Id you wish to get rid of:\n\n```c#\nawait verifalia\n    .EmailValidations\n    .DeleteAsync(job.Id);\n```\n\nOnce deleted, a job is gone and there is no way to retrieve its email validation results.\n\n### Iterating over your email validation jobs\n\nFor management and reporting purposes, you may want to obtain a detailed list of your past email validation jobs. This SDK library allows to do that through the `ListAsync()` method, which allows to iterate asynchronously over a collection of `ValidationOverview` instances (the same type of the `Overview` property of the results returned by `SubmitAsync()` and `GetAsync()`).\n\nHere is how to iterate over your jobs, from the most recent to the oldest one:\n\n```c#\nvar jobOverviews = verifalia\n    .EmailValidations\n    .ListAsync(new ValidationOverviewListingOptions\n    {\n        Direction = Direction.Backward\n    });\n\nawait foreach (var jobOverview in jobOverviews)\n{\n    Console.WriteLine(\"Id: {0}, status: {2}, entries: {3}\",\n        jobOverview.Id,\n        jobOverview.Status,\n        jobOverview.NoOfEntries);\n}\n\n// Prints out something like:\n// Id: a7784f9a-86d4-436c-b8e4-f72f2bd377ac, status: InProgress, entries: 9886\n// Id: 86d57c00-147a-4736-88cc-c918260c67c6, status: Completed, entries: 1\n// Id: 594bbb0f-6f12-481c-926f-606cfefc1cd5, status: Completed, entries: 1\n// Id: a5c1cd5b-39cc-43bc-9a3a-ee4a0f80ee6d, status: InProgress, entries: 226\n// Id: b6f69e30-60dd-4c21-b2cb-e73ba75fb278, status: Completed, entries: 12077\n// Id: 5e5a97dc-459f-4edf-a607-47371c32aa94, status: Deleted, entries: 1009\n// ...\n```\n\n\u003e The `ListAsync()` method uses the *C# 8.0 async enumerable* feature; for previous language support please check the `ListSegmentedAsync()` methods group.\n\n#### Filtering email validation jobs\n\nThe `ListAsync()` method also have the ability, by way of the same `options` argument, to filter the email\nverification jobs returned by the Verifalia API: it is possible to filter by date of submission,\nowner and status of the jobs.\n\nHere is how to repeat the listing operation shown in the example above, this time returning only the jobs\nof a given user and for a given date range:\n\n```c#\nvar jobOverviews = verifalia\n    .EmailValidations\n    .ListAsync(new ValidationOverviewListingOptions\n    {\n        Direction = Direction.Backward,\n        CreatedOn = new DateBetweenPredicate(new DateTime(2024, 1, 3),\n            new DateTime(2024, 1, 7)),\n        Owner = new StringEqualityPredicate(\"50173acd-9ed2-4298-ba7f-8ccaeed48deb\")\n    });\n\nawait foreach (var jobOverview in jobOverviews)\n{\n    // ...\n}\n```\n\n## Managing credits ##\n\nTo manage the Verifalia credits for your account you can use the `Credits` property exposed by the `VerifaliaRestClient` instance created above. Like for the previous topic, in the next few paragraphs we are looking at the most used operations, so it is strongly advisable to explore the library and look at the embedded xmldoc help for other opportunities.\n\n### Getting the credits balance ###\n\nOne of the most common tasks you may need to perform on your account is retrieving the available number of free daily credits and credit packs. To do that, you can use the `GetBalanceAsync()` method, which returns a `Balance` object, as shown in the next example:\n\n```c#\nvar balance = await verifalia\n    .Credits\n    .GetBalanceAsync();\n\nConsole.WriteLine(\"Credit packs: {0}, free daily credits: {1} (will reset in {2})\",\n\tbalance.CreditPacks,\n\tbalance.FreeCredits,\n\tbalance.FreeCreditsResetIn);\n\n// Prints out something like:\n// Credit packs: 956.332, free daily credits: 128.66 (will reset in 09:08:23)\n```\n\nTo add credit packs to your Verifalia account visit [https://verifalia.com/client-area#/credits/add][5].\n\n### Retrieving credits usage statistics ###\n\nAs a way to monitor and forecast the credits consumption for your account, the method `ListDailyUsagesAsync()` allows to retrieve statistics about historical credits usage, returning an asynchronously iterable collection of `DailyUsage` instances. The method also allows to limit the period of interest by passing a `DailyUsageListingOptions` instance. Elements are returned only for the dates where consumption (either of free credits, credit packs or both) occurred.\n\nHere is how to retrieve the daily credits consumption for the last thirty days:\n\n```c#\nvar dailyUsages = verifalia\n    .Credits\n    .ListDailyUsagesAsync(new DailyUsageListingOptions\n\t{\n        DateFilter = new DateBetweenPredicate\n        {\n            Since = DateTime.Now.AddDays(-30)\n        }\n    });\n\nawait foreach (var dailyUsage in dailyUsages)\n{\n    Console.WriteLine(\"{0:yyyyMMdd} - credit packs: {1}, free daily credits: {2}\",\n        dailyUsage.Date,\n        dailyUsage.CreditPacks,\n        dailyUsage.FreeCredits);\n}\n\n// Prints out something like:\n// 20240201 - credit packs: 1965.68, free daily credits: 200\n// 20240126 - credit packs: 0, free daily credits: 185.628\n// 20240125 - credit packs: 15.32, free daily credits: 200\n// ...\n```\n\n\u003e The `ListDailyUsagesAsync()` method uses the *C# 8.0 async enumerable* feature; for previous language support please check the `ListDailyUsagesSegmentedAsync()` methods group.\n\n## Changelog / What's new\n\nThis section lists the changelog for the current major version of the library: for older versions,\nplease see the [project releases](https://github.com/verifalia/verifalia-csharp-sdk/releases). For the sake of clarity, logs for build and revision updates are excluded.\n\n### v4.2\n\nReleased on January 11\u003csup\u003eth\u003c/sup\u003e, 2024\n\n- Added support for API v2.5\n- Added support for classification override rules\n- Added support for AI-powered suggestions\n- Added support for .NET 8.0\n- Bumped dependencies\n\n### v4.1\n\nReleased on May 26\u003csup\u003eth\u003c/sup\u003e, 2023\n\n- Added support for filters when listing email verification jobs\n- Resolved an issue with the `ToAsyncEnumerableAsync()` method that previously resulted in incomplete listings in specific scenarios\n\n### v4.0\n\nReleased on February 27\u003csup\u003eth\u003c/sup\u003e, 2023\n\n- Added support for API v2.4\n- Added support for .NET 7.0\n- Added support for new completion callback options\n- Added support for parked mail exchangers detection\n- Added support for specifying a custom wait time while submitting and retrieving email verification jobs\n- Added support for nullable annotations\n- Breaking change: renamed `WaitingStrategy` into `WaitOptions` and refactored the latter so that it now allows to\nadjust the underlying polling wait times\n- Breaking change: the default job submission and retrieval behavior is now to wait for the completion\nof jobs (but it is possible to change that through the new `WaitOptions` class)\n- Breaking change: the `CompletionCallback` property of the `ValidationRequest` and `FileValidationRequest` classes\nnow points to a full fledged `CompletionCallback` class instead of a simple `Uri`\n- Bumped dependencies (including Newtonsoft.Json and Flurl) \n- Improved documentation\n\n[0]: https://verifalia.com\n[1]: https://github.com/verifalia/verifalia-csharp-sdk/archive/master.zip\n[2]: https://verifalia.com/developers#authentication\n[3]: https://verifalia.com/client-area#/users/new\n[4]: https://verifalia.com/sign-up\n[5]: https://verifalia.com/client-area#/credits/add\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverifalia%2Fverifalia-csharp-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverifalia%2Fverifalia-csharp-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverifalia%2Fverifalia-csharp-sdk/lists"}