Verifalia email verification library for JavaScript: verify email addresses in real-time and check whether they are deliverable, invalid, or otherwise risky.
npm install verifalia!Verifalia API
Verifalia REST API - SDK and helper library for Javascript
==========================================================
Verifalia provides a fast and accurate API for verifying email addresses in real-time and checking whether they are deliverable, invalid, or otherwise risky: this SDK library integrates with Verifalia and allows to verify email addresses on both Node.js backends and in the browser.
It includes artifacts for a wide range of module loaders, including CommonJS (suitable for Node.js) and native ES modules (ideal for modern front-end module bundlers like Webpack and Rollup, for front-end frameworks like Angular, React, Vue, etc. - and supported in Node.js v13+); it also comes with a turn-key single-file IIFE for browsers (compatible with ES5 or higher), with no external dependencies.
To learn more about Verifalia please see https://verifalia.com
- Getting started
* Install the package
* Using Verifalia in Node.js
+ CommonJS (default in Node.js)
+ ES modules (available in Node.js v13 and higher)
* Using Verifalia in the browser
+ ES modules (ideal for: Webpack, Rollup, ..., Angular, React, Vue, ...)
+ CommonJS
+ AMD
+ IIFE (single-file, which can be directly included in web-pages as is)
* Authentication
+ Username and password
+ Browser app key
+ Bearer token
+ Multi-Factor Authentication
+ X.509 client certificate (Node-only)
+ Errors
- Validating email addresses
* How to validate an email address
* How to validate a list of email addresses
* How to import and submit a file for validation
* Processing options
+ Quality level
+ Deduplication mode
+ Data retention
+ CAPTCHA - Bot detection
+ Wait options
- Avoid waiting
- Progress tracking
+ Completion callbacks
* Retrieving a job and its results
* Exporting email verification results in different output formats
* Don't forget to clean up, when you are done
- Managing credits
* Getting the credits balance
* Retrieving credits usage statistics
- Changelog / What's new
* v5.0
The best and easiest way to add the Verifalia email verification Javascript library to your project is to use npm, which will automatically download and install the required files. With npm installed, run the following from your project root:
``bash`
$ npm install verifalia
Once done, you can load the library into your application according to the module system you are using, as explained in the following sections.
Node.JS applications use the CommonJS module system to load dependencies through the require(...) builtin function and,import
starting from Node.js v13, it is also possible to native ES modules directly: this library includes both CommonJS
and native ES modules support.
Using this method you can load any export through the require(...) Node.js builtin function. Here is how to load theVerifaliaRestClient class, which is the main export of this library:
`javascript`
const { VerifaliaRestClient } = require('verifalia');
The build artifacts are available in the node/cjs folder.
This is the most modern approach and relies on native ES module support in Node.js; here is how to load the VerifaliaRestClient
class, which is the main export of this library:
`javascript`
import { VerifaliaRestClient } from 'verifalia/node/esm/index.mjs';
The build artifacts with native ES modules can be found in the node/esm folder.
This library includes out of the box support for all modern front-end module bundlers like Webpack and Rollup and for front-end frameworks like Angular, React, Vue, etc. It comes with support for these module systems:
- ES modules;
- CommonJS;
- AMD;
- SystemJS;
And with these additional build artifacts:
- UMD;
- IIFE.
This is the most modern approach, which allows to improve the module loading time as well as to perform tree shaking on your final bundle; using the features of this library requires the use of the import keyword, as shown below:
`javascript`
import { VerifaliaRestClient } from 'verifalia';
A build artifact with native ES modules is distributed in the browser/esm folder.
Using this loading method you can use the features of this library through the require function, as shown below:
`javascript`
const { VerifaliaRestClient } = require('verifalia');
The build artifact with the CommonJS module is available in the browser/cjs folder.
Using this loading method you can use the features of this library through the define function, as shown below:
`javascript
define(["verifalia"], function (verifaliaModule) {
const verifalia = new verifaliaModule.VerifaliaRestClient({
username: 'samantha',
password: '42istheanswer'
});
return { };
});
`
The build artifact with the CommonJS module is available in the browser/amd folder.
While we always recommend using a module loader for a much better performance and duplicate code removal, you can also load the Verifalia SDK along with all its dependencies in a single script and include it in a web page through an IIFE, available at browser/iife/verifalia.min.js:
`html`
...
First things first: authentication to the Verifalia API is performed by way of the username and password credentials of your root Verifalia account or
those of a Verifalia user (previously known as sub-account): if you don't have a Verifalia account, just register for a free one. For security reasons,
it is always advisable to create and use a dedicated user for accessing the API from a Node app and to create and use a dedicated user,
as doing so will allow to assign only the specific needed permissions to it.
Learn more about authenticating to the Verifalia API at https://verifalia.com/developers#authentication
The most straightforward method for authenticating against the Verifalia API involves using a username and password pair. These credentials can be applied
during the creation of a new instance of the VerifaliaRestClient class, serving as the initial step for all interactions with the Verifalia API: the
provided username and password will be automatically transmitted to the API using the HTTP Basic Auth method.
`ts`
const verifalia = new VerifaliaRestClient({
username: 'YOUR-USERNAME-HERE',
password: 'YOUR-PASSWORD-HERE'
});
As an alternative to regular Verifalia users, browser apps come with a fixed and minimal permissions set which only allows to submit email validations
and retrieve their results, which may be ideal for a public website or app. If you wish to learn more about how to configure and manage Verifalia browser
apps, please see https://verifalia.com/help/sub-accounts/how-to-manage-browser-apps
A browser app key is essentially a username you can use while authenticating against the Verifalia API, which does not have a password. To employ a browser
app key with this library, just use it as the username field while instantiating a VerifaliaRestClient object, as shown below:
`ts`
const verifalia = new VerifaliaRestClient({
username: 'YOUR-BROWSER-APP-KEY-HERE'
});
Bearer authentication offers higher security over password-based authentication, 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 password-based authentication provides the same degree of security and is also faster.
Bearer authentication requires a username and password and is thus incompatible with browser app keys.
To authenticate using bearer tokens, provide the username and password to the BearerAuthenticator constructor, and then assign the resulting instance to the authenticator
field while instantiating a object, as shown below:
`ts`
const verifalia = new VerifaliaRestClient({
authenticator: new BearerAuthenticator('YOUR-USERNAME-HERE', 'YOUR-PASSWORD-HERE')
});
#### Multi-Factor Authentication
Bearer authentication supports Multi-Factor Authentication (MFA) and it is possible to configure the BearerAuthenticator object so that it obtainsprovideTotp()
a Time-based One-time Password (TOTP) when necessary. To do that, pass an instance of an object with a method named which returns a Promise
containing the required TOTP: this could involve prompting the user to input it or retrieving it from an external device, for instance.
`ts`
const verifalia = new VerifaliaRestClient({
authenticator: new BearerAuthenticator('YOUR-USERNAME-HERE',
'YOUR-PASSWORD-HERE',
{
async provideTotp() {
// TODO: Obtain the TOTP either from the user directly or from an external device
return 'YOUR-TOTP-HERE';
}
})
});
> :warning: This authentication method is only available in Node.js and not in the browser.
This 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. To learn more about this option, please see https://verifalia.com/help/sub-accounts/what-is-x509-tls-client-certificate-authentication
To authenticate using an X.509 client certificate, specify its public key through the cert field and pass its private key via the key field. An optionalpassphrase
passphrase can be set via with the field.
`ts`
const verifalia = new VerifaliaRestClient({
cert: fs.readFileSync('/home/rmontagnani/my-client-certificate.pem'),
key: fs.readFileSync('/home/rmontagnani/my-client-certificate.key')
});
In case of API-related errors, the library throws instances of classes derived from VerifaliaError; these instances may includeproblem
a field which, if present, contains a representation of the issue in the RFC 9457 problem+json format. Thisproblem.type
format offers a clearer understanding of the error and can pinpoint the exact reason for the error condition: in particular,
the field contains an error string that helps distinguish between different errors that share the same HTTP
status code.
Furthermore, the library incorporates several typed exception classes, aiding in precisely conveying the reason for a specific
error condition:
- AuthenticationError, thrown in the event the user is unable to authenticate to Verifalia due to authentication-related issues, such asAuthorizationError
invalid credentials or missing authentication tokens.
- , thrown in the event the user is authenticated but does not have the necessary permissions to access the requestedCaptchaValidationError
resource.
- , thrown in the event the provided CAPTCHA token failed the validation on the server side.EndPointServerError
- , thrown in the rare event a Verifalia API endpoint returns an HTTP server error status code (HTTP 5xx).InsufficientCreditError
- , thrown when the credit of the requesting account is not enough to accept a givenOperationCanceledError
email validation job.
- , thrown whenever an async function is canceled.RequestThrottledError
- , thrown in the event a request exceeded the maximum configured email validations rate or the maximum numberServiceUnreachableError
of concurrent requests from the same IP address.
- , thrown in the event all the Verifalia API endpoints are unreachable.
Every operation related to verifying / validating email addresses is performed through the emailValidations property exposed by the VerifaliaRestClient instance you created above. The property contains references to methods which can be used to verify email addresses and manage past emaiil validation jobs, as explained below.
The library automatically waits for the completion of email verification jobs: if needed, it is possible to adjust the wait options and have more control over the entire underlying polling process. Please refer to the Wait options section below for additional details.
To validate an email address you can invoke the submit() 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 and processing priority.
> Note
> In the event you need to verify a list of email addresses, it is advisable to submit them all at once through an
> array of strings or through a ValidationRequest / FileValidationRequest object (see the next sections), instead of iterating over the
> source set and submitting the addresses one by one. Not only the all-at-once method would be faster, it would
> also allow to detect and mark duplicated items - a feature which is unavailable while verifying the email addresses
> one by one.
In the next example, you can see how to verify an email address using the default options, with the async/await pattern;
for more advanced waiting scenarios and progress tracking, you can also pass an instance of the WaitOptions class.
`ts
const result = await verifalia
.emailValidations
.submit('batman@gmail.com');
// At this point the address has been validated: let's print
// its email validation result to the console.
const entry = result.entries[0];
console.log(${entry.classification} (${entry.status}));
// Prints out something like:
// Deliverable (Success)
`
Of course, you can use the promise callback pattern if your platform does not support the async/await pattern:
`ts
verifalia
.emailValidations
.submit('batman@gmail.com')
.then(result => {
// At this point the address has been validated: let's print
// its email validation result to the console.
const entry = result.entries[0];
console.log(${entry.classification} (${entry.status}));
// Prints out something like:
// Deliverable (Success)
});
`
As you may expect, each entry may include various additional details about the verified email address:
| Field | Description |
|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| asciiEmailAddressDomainPart | Gets the domain part of the email address, converted to ASCII if needed and with comments and folding white spaces stripped off. |classification
| | The classification value for this entry; values known at the time this SDK is released are available through the ValidationEntryClassification_* constants. |completedOn
| | The date this entry has been completed, if available. |custom
| | A custom, optional string which is passed back upon completing the validation. To pass back and forth a custom value, use the custom field of the specific submitted entry. |duplicateOf
| | The zero-based index of the first occurrence of this email address in the parent validation job, 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. |index
| | The index of this entry within its validation job; this property is mostly useful in the event the API returns a filtered view of the items. |inputData
| | The input string being validated. |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. |emailAddressDomainPart
| | Gets the domain part of the email address, without comments and folding white spaces. |emailAddressLocalPart
| | Gets the local part of the email address, without comments and folding white spaces. |hasInternationalDomainName
| | If true, the email address has an international domain name. |hasInternationalMailboxName
| | If true, the email address has an international mailbox name. |isDisposableEmailAddress
| | If true, the email address comes from a disposable email address (DEA) provider. What is a disposable email address? |isFreeEmailAddress
| | If true, the email address comes from a free email address provider (e.g. gmail, yahoo, outlook / hotmail, ...). |isRoleAccount
| | If true, the local part of the email address is a well-known role account. |status
| | The status value for this entry; values known at the time this SDK is released are available through the ValidationEntryStatus_* constants. | suggestions
| | The potential corrections for the input data, in the event Verifalia identified potential typos during the verification process. |syntaxFailureIndex
| | The position of the character in the email address that eventually caused the syntax validation to fail. |
Here is another example, showing some of the additional result details provided by Verifalia:
`js
const result = await verifalia
.emailValidations
.submit('bat[man@gmal.com');
const entry = result.entries[0];
console.log(Classification: ${entry.classification});Status: ${entry.status}
console.log();Syntax failure index: ${entry.syntaxFailureIndex}
console.log();
if (entry.suggestions) {
console.log('Suggestions:');
entry.suggestions.forEach(suggestion => {
console.log(- ${suggestion});
});
}
// Classification: Undeliverable
// Status: InvalidCharacterInSequence
// Syntax failure index: 3
// Suggestions:
// - batman@gmail.com
`
To verify a list of email addresses - instead of a single address - it is possible to pass an array of strings
to submit(); if the email addresses to be verified are originally stored
in a file, it is also possible to simply upload the file and have Verifalia automatically import and verify
it (see the next section for the details).
Here is an example showing how to verify an array with some email addresses, using the async/await pattern:
`ts
const result = await verifalia
.emailValidations
.submit([
'batman@gmail.com',
'steve.vai@best.music',
'samantha42@yahoo.de'
]);
result.entries.forEach(item => {
console.log(${item.inputData}: ${item.classification});`
});
And here, of course, the promise callback syntax version of the same:
`ts
// Submit the list first
verifalia
.emailValidations
.submit([
'batman@gmail.com',
'steve.vai@best.music',
'samantha42@yahoo.de'
])
.then(result => {
result.entries.forEach((item) => {
console.log(${item.inputData}: ${item.classification});`
});
});
This library includes support for submitting and validating files with email addresses, including:
- plain text files (.txt), with one email address per line;
- comma-separated values (.csv), tab-separated values (.tsv) and other delimiter-separated values files;
- Microsoft Excel spreadsheets (.xls and .xlsx).
To submit and validate files, one can still use the submit() method mentioned above, passing an object with a file field set to, respectively, either a ReadStream or a Buffer for Node.js and a Blob or a File for the browser. Along with that field, it is also possible to specify the eventual starting and ending rows to process, the column, the sheet index, the line ending and the delimiter - depending of course on the nature of the submitted file (see FileValidationRequest in the source to learn more).
Here is how to validate the email address of an Excel file in Node.js, for example:
`ts
// Import the MIME content type for Excel files (just a string, for our convenience)
import { MimeContentType_ExcelXlsx } from 'verifalia/node/esm/index.mjs';
const file = fs.createReadStream('/home/john/sample.xlsx');
const result = await verifalia
.emailValidations
.submit({
file: file,
contentType: MimeContentType_ExcelXlsx,
startingRow: 1,
quality: 'high',
deduplication: 'safe'
});
`
Validating the email addresses of an Excel file in the browser follows a similar approach:
`html`ts
// Import the MIME content type for Excel files (just a string, for our convenience)
import { MimeContentType_ExcelXlsx } from 'verifalia';
const file = document.getElementById('file').files[0];
const result = await verifalia
.emailValidations
.submit({
file: file,
contentType: MimeContentType_ExcelXlsx,
startingRow: 1,
quality: 'high',
deduplication: 'safe'
});
`
While submitting one or more email addresses for verification, it is possible to specify several
options which affect the behavior of the Verifalia processing engine as well as the verification flow
from the API consumer standpoint.
Verifalia offers three distinct quality levels - namely, _Standard_, _High_ and _Extreme_ - which rule out how the email verification engine should
deal with temporary undeliverability issues, with slower mail exchangers and other potentially transient
problems which can affect the quality of the verification results. The submit() method accepts a ValidationRequest (orFileValidationRequest
a , for file imports), where the quality field allows
to specify the desired quality level; here is an example showing how to verify an email address using
the _High_ quality level:
`ts`
const validation = await verifalia
.emailValidations
.submit({
entries: [
{
inputData: 'batman@gmail.com'
}
],
quality: 'high'
});
ValidationRequest (or FileValidationRequest, for file imports) also allows to specify how to
deal with duplicated entries pertaining to the same input set; Verifalia supports a _Safe_ deduplication
mode, which strongly adheres to the old IETF standards, and a _Relaxed_ mode which is more in line with
what can be found in the majority of today's mail exchangers configurations.
In the next example, we show how to import and verify a list of email addresses in Node.js and mark duplicated
entries using the _Relaxed_ deduplication mode:
`ts
import { MimeContentType_ExcelXlsx } from 'verifalia/node/esm/index.mjs';
const file = fs.createReadStream('/home/john/sample.xlsx');
const validation = await verifalia
.emailValidations
.submit({
file: file,
contentType: MimeContentType_ExcelXlsx,
startingRow: 1,
quality: 'high',
deduplication: 'relaxed'
});
`
Verifalia automatically deletes completed email verification jobs according to the data retention
policy defined at the account level, which can be eventually overriden at the user level: one can
use the Verifalia clients area to configure these settings.
It is also possible to specify a per-job data retention policy which govern the time to live of a submitted
email verification job; to do that, specify a retention value through the passed ValidationRequest (or FileValidationRequest, for file imports) instance.
Here is how, for example, one can set a data retention policy of 10 minutes while verifying
an email address:
`ts`
const validation = await verifalia
.emailValidations
.submit({
entries: [
{
inputData: 'batman@gmail.com'
}
],
retention: '0:10:0' // 10 minutes
});
Verifalia can automatically verify CAPTCHA tokens generated by multiple CAPTCHA service providers, ensuring that only
verifications from genuine humans are processed; this prevents bots from consuming Verifalia credits or triggering
throttling restrictions for legitimate users.
The supported CAPTCHA services are:
- Cloudflare Turnstile;
- Google reCAPTCHA v2 (both checkbox and invisible);
- Google reCAPTCHA v3;
- hCaptcha;
To enable bot detection, start by entering the necessary CAPTCHA service settings (typically the secret key provided by
the external CAPTCHA service) into the _Bot detection_ interface for the user or browser app used to authenticate, accessible
in the Verifalia client area: these settings enable communication between the Verifalia servers and the configured
CAPTCHA service.
> To get detailed guidance on setting up Verifalia with your selected CAPTCHA service settings, check out: How to integrate with a CAPTCHA provider and prevent bot submissions
Once done, specify a captcha object at the time of the submission of an email verification job through the passedValidationRequest (or FileValidationRequest, for file imports) instance, providing the type of the CAPTCHA serviceprovider
provider through the field and the CAPTCHA response token provided by that service in response to a CAPTCHAtoken
challenge by way of the field.
> To learn how to obtain a CAPTCHA response token, please consult the documentation for your selected CAPTCHA service provider:
> - Cloudflare Turnstile;
> - Google reCAPTCHA v2;
> - Google reCAPTCHA v3;
> - hCaptcha.
The provider field accepts one of the following values:
- Turnstile (also exposed by the CaptchaProvider.Turnstile constant), for Cloudflare Turnstile;reCaptcha_v2
- (also exposed by the CaptchaProvider.ReCaptchaV2 constant), for Google reCAPTCHA v2;reCaptcha_v3
- (also exposed by the CaptchaProvider.ReCaptchaV3 constant), for Google reCAPTCHA v3;hCaptcha
- (also exposed by the CaptchaProvider.HCaptcha constant), for hCaptcha.
Here is how, for example, one can specify a Cloudflare Turnstile CAPTCHA while verifying an email address:
`ts`
const validation = await verifalia
.emailValidations
.submit({
entries: [
{
inputData: 'batman@gmail.com'
}
],
captcha: {
provider: 'Turnstile',
// TODO: Retrieve the actual token from Turnstile, see https://developers.cloudflare.com/turnstile/get-started/
token: "0.HaR4xgf0...22788e0"
}
});
By default, the submit() method submits an email verification job to Verifalia and waits
for its completion; the entire process may require some time to complete depending on the plan of the
Verifalia account, the number of email addresses the submission contains, the specified quality level
and other network factors including the latency of the mail exchangers under test.
In waiting for the completion of a given email verification job, the library automatically polls the
underlying Verifalia API until the results are ready; by default, it tries to take advantage of the long
polling mode introduced with the Verifalia API v2.4, which allows to minimize the number of requests
and get the verification results faster.
#### Avoid waiting
In certain scenarios (in a microservice architecture, for example), however, it may preferable to avoid
waiting for a job completion and ask the Verifalia API, instead, to just queue it: in that case, the library
would just return the job overview (and not its verification results) and it will be necessary to retrieve
the verification results using the get() method.
To do that, it is possible to specify the WaitOptions.noWait as the value for the waitOptions fieldValidationRequest
of the passed (or FileValidationRequest, for file imports) instance, as shown in
the next example:
`ts
const job = await verifalia
.emailValidations
.submit('batman@gmail.com', WaitOptions.noWait);
console.log(Status: ${job.Overview.Status});`
// Status: InProgress
#### Progress tracking
For jobs with a large number of email addresses, it could be useful to track progress as they are processed
by the Verifalia email verification engine; to do that, it is possible to create an instance of the
WaitOptions class and provide an handler which eventually receives progress notifications through theprogress field.
Here is how to define a progress notification handler which displays the progress percentage of a submitted
job to the console window:
`ts% completed: ${jobOverview.progress?.percentage * 100}
const result = await verifalia
.emailValidations
.submit([
'batman@gmail.com',
'steve.vai@best.music',
'samantha42@yahoo.de'
], {
...new WaitOptions(),
progress: jobOverview => {
console.log();`
}
});
Along with each email validation job, it is possible to specify an URL which
Verifalia will invoke (POST) once the job completes: this URL must use the HTTPS or HTTP
scheme and be publicly accessible over the Internet.
To learn more about completion callbacks, please see https://verifalia.com/developers#email-validations-completion-callback
To specify a completion callback URL, pass either a ValidationRequest or a FileValidationRequest
to the method and set its callback.url field accordingly, as shown
in the example below:
`ts`
const validation = await verifalia
.emailValidations
.submit({
entries: [
{
inputData: 'batman@gmail.com'
}
],
callback: {
url: 'https://your-website-here/foo/bar'
}
});
Note that completion callbacks are invoked asynchronously and it could take up to
several seconds for your callback URL to get invoked.
It is possible to retrieve a job through the get() method, passing the required email verification job identifer.waitOptions
While doing that, the library automatically waits for the completion of
the job, and it is possible to adjust this behavior by passing to the aforementioned methods
a parameter, in the exactly same fashion as described for the submit() method; please see
the Wait options section for additional details.
In the next example, you can see how to retrieve an email verification job using the default options, with the async/await pattern:
`ts`
const validation = await verifalia
.emailValidations
.get('290b5146-eeac-4a2b-a9c1-61c7e715f2e9');
And here is the same code, using the promise callback syntax:
`ts`
verifalia
.emailValidations
.get('290b5146-eeac-4a2b-a9c1-61c7e715f2e9')
.then(validation => {
// ...
});
Once an email verification job is completed, it is also possible to retrieve a human-readable report of its results as either a comma-separated values (.csv) file or as a Microsoft Excel spreadsheet (.xls and .xlsx supported). While the output schema (columns / labels / data format) of the exported results is fairly mature and complete, you should consider it as subject to change: always retrieve your results data using the get() method as explained above if you need to deal with it in an unmanned way.
Here is an example showing how to export a completed email verification job as a Microsoft Excel file, given its job ID, in Node.js:
`ts
// Import the MIME content type for Excel files (just a string, for our convenience)
import { MimeContentType_ExcelXlsx } from 'verifalia/node/esm/index.mjs';
(
await verifalia
.emailValidations
.export('dc21630a-6773-4bd0-b248-15e8b50c0d3e', MimeContentType_ExcelXlsx)
).pipe(fs.createWriteStream('/home/lbanfi/my-list.xls'))
`
And here is how to export the same completed email verification job as a comma-separated values (CSV) file in the browser, showing its content in an iframe:
`html`ts
// Import the MIME content type for CSV files (just a string, for our convenience)
import { MimeContentType_TextCsv } from 'verifalia';
const target = document.getElementByID('my-iframe');
const exportedData = await verifalia
.emailValidations
.export('dc21630a-6773-4bd0-b248-15e8b50c0d3e', MimeContentType_TextCsv);
target.src = exportedData.toBlobURL(MimeContentType_TextCsv);
`
Verifalia automatically deletes completed jobs after the data retention period eventually specified along with the submission options, falling back to the configured data retention period of the submitting user / browser app and, should it be unset, to the configured data retention period of the Verifalia account, with a default of 30 days.
It is always possible to delete completed jobs at any time, however, and deleting completed jobs is a best practice, for privacy and security reasons.
To delete a completed email validation job, you can invoke the delete() method passing the job Id you wish to get rid of. Here is an example showing how to do that using the async/await syntax:
`ts`
await verifalia
.emailValidations
.delete(validation.id);
And here is the same example using the promise callback syntax:
`ts`
verifalia
.emailValidations
.delete(validation.id)
.then(() => {
// ...
});
Once deleted, a job is gone and there is no way to retrieve its email validation results.
To manage the Verifalia credits for your account you can use the credits property exposed by the VerifaliaRestClient instance created above.
One of the most common tasks you may need to perform on your Verifalia account is retrieving the available number of free daily credits and credit packs. To do that, you can use the getBalance() method, which returns a Balance object, as shown in the next example:
`ts
const balance = await verifalia
.credits
.getBalance();
console.log(Credit packs ${balance.creditPacks});Free daily credits ${balance.freeCredits}
console.log();Free daily credits will reset in ${balance.freeCreditsResetIn}
console.log();
// Credit packs 956.332
// Free daily credits 128.66
// Free daily credits will reset in 09:08:23
`
To add credit packs to your Verifalia account visit https://verifalia.com/client-area#/credits/add.
As a way to monitor and forecast the credits consumption for your account, the method listDailyUsages() 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.
Here is how to retrieve the daily credits consumption for a certain period:
`js
const dailyUsages = verifalia
.credits
.listDailyUsages({
// from, to
dateFilter: new DateBetweenPredicate(new Date('2024-01-09'), new Date('2024-03-01'))
});
for await (const dailyUsage of dailyUsages) {
console.log(dailyUsage.date);
console.log('\tCredit packs', dailyUsage.creditPacks);
console.log('\tFree daily credits', dailyUsage.freeCredits);
}
// Prints out something like:
// Sat Jan 10 2024
// Credit packs 1965.68
// Free daily credits 200
// Mon Jan 12 2024
// Credit packs 0
// Free daily credits 185.628
// Tue Jan 13 2024
// Credit packs 15.32
// Free daily credits 200
// ...
`
This section lists the changelog for the current major version of the library: for older versions,
please see the project releases.
Released on May 2, 2024
- Added support for Verifalia API v2.6
- Added support for multiple CAPTCHA - Bot detection services.
- Added support for bearer token authentication and Multi-Factor authentication.
- Improved error handling: added support for parsing RFC-9457 problem+json responses and returning problem details in errors.invoke()
- Breaking change: the method in the MultiplexedRestClient class has been changed to accept instances of the new RestRequest class; if you're not using the MultiplexedRestClient class directly in your code, you won't be impacted by this change. Authenticator` has been updated to accommodate bearer authentication and multi-factor authentication / TOTP; if you're not using a custom authentication method in your code, you won't be impacted by this change.
- Breaking change: the logic for
- Improved documentation.