Disposable or temporary Gmail and Outlook addresses may appear legitimate, but they should be removed from your mailing lists because they lead to fake registrations and false engagement.
Verifalia email verification API reference guide
Not a software developer?
Using the Verifalia API
Javascript widget
Authentication
HTTP Basic Auth
Authorization
HTTP header,
according to the RFC 7617. This method
requires the API consumer to send the credentials for each request.Authenticate via HTTP Basic Auth
curl -u username:password \
https://api.verifalia.com/v2.6/...
using Verifalia.Api;
// ...
var verifalia = new VerifaliaRestClient("username", "password");
import com.verifalia.api.VerifaliaRestClient;
// ...
VerifaliaRestClient verifalia =
new VerifaliaRestClient("user", "password");
const { VerifaliaRestClient } = require('verifalia');
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
$verifalia = new VerifaliaRestClient([
VerifaliaRestClientOptions::USERNAME => 'your-username-here',
VerifaliaRestClientOptions::PASSWORD => 'your-password-here'
]);
package main
import (
"github.com/verifalia/verifalia-go-sdk/verifalia"
)
func main() {
client := verifalia.NewClient("username", "password")
// TODO: Use "client"
}
require 'verifalia'
# ...
verifalia = Verifalia::Client.new username: 'user', password: 'password'
Bearer authentication
Under this method Verifalia provides you with an encrypted security token (called bearer token) in response to a first authentication request, using the user-name and password of either your Verifalia root account (inadvisable for security reasons, see above) or a user bound to your account; the API consumer must then send that encrypted security token while making subsequent requests.
Bearer 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 the API consumer needs to perform only one request, using HTTP Basic Auth provides the same degree of security and is the faster option too.
v2.6+ The bearer tokens provided
by Verifalia are JSON Web Tokens (JWTs), adhering to the open standard defined by RFC 7519;
this standard offers a concise and self-contained method for securely transmitting information
between parties in the form of a JSON object. The JSON object structure contains several fields the standard calls claims, including sub
, exp
, and verifalia:mfa
- as documented below; additionally, it may contain other fields subject to change that API consumers must ignore.
sub
exp
verifalia:mfa
totp
, signaling the availability of a Time-Based One-Time Password (TOTP) factor; any other value may change and must be ignored by API consumers.
/auth/tokens
Property | Description |
---|---|
username |
A string with the username of the
requesting Verifalia user (or root account - please see the security note
above). |
password |
A string with the password of the
requesting Verifalia user (or root account - please see the security note
above). |
200
(OK) status code, meaning the operation
completed successfully, or with an HTTP 401
(Unauthorized) status code.Property | Description |
---|---|
accessToken |
A string representing the bearer token
for the authenticated user. |
Request a bearer token
curl -H "Content-Type: application/json" \
-d '{ "username": "samantha", "password": "42istheanswer" }' \
https://api.verifalia.com/v2.6/auth/tokens
var verifalia = new VerifaliaRestClient(
new BearerAuthenticationProvider("username", "password"));
// ...
// The SDK will automatically retrieve a bearer token on the first
// API invocation.
BearerAuthenticationProvider authProvider =
new BearerAuthenticationProvider("username", "password");
VerifaliaRestClient verifalia =
new VerifaliaRestClient(authProvider);
// ...
// The SDK will automatically retrieve a bearer token on the first
// API invocation.
// The Javascript SDK does not support this feature yet.
use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
use Verifalia\Security\BearerAuthenticationProvider;
$verifalia = new VerifaliaRestClient([
VerifaliaRestClientOptions::AUTHENTICATION_PROVIDER =>
new BearerAuthenticationProvider('your-username-here',
'your-password-here')
]);
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
Authorization
HTTP header, according to the RFC 7617.Use the obtained bearer token
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1...JV_adQssw5c" \
https://api.verifalia.com/v2.6/...
// The .NET SDK automatically uses bearer tokens, no need to pass
// them explicitly.
// The Java SDK automatically uses bearer tokens, no need to pass
// them explicitly.
// The Javascript SDK does not support this feature yet.
// The PHP SDK automatically uses bearer tokens, no need to pass
// them explicitly.
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
Multi-Factor Authentication (MFA) v2.6+
As mentioned before, when the user has to finalize the authentication process with a secondary factor, the API provides a JWT bearer token that contains the claim verifalia:mfa
, which lists the enrolled factors for the user.
After receiving a bearer token upon authentication, the API consumer needs to verify the presence of that claim and choose one of the provided authentication factors as outlined below. If the API consumer doesn't support any of the offered factors, the authentication process should be stopped.
Time-Based One-Time Password (TOTP)
A Time-Based One-Time Password (TOTP) is a type of authentication method which generates a unique, temporary passcode that changes periodically, typically every 30 seconds;
TOTP relies on a shared secret key, usually stored on both the server and the user's device / smartphone.
The API indicates that TOTP is available for use as an authentication factor by including the string totp
in the verifalia:mfa
claim array.
To complete the authentication process using TOTP, API consumers must issue a POST request against this sub-resource:
/auth/totp/verifications
Property | Description |
---|---|
passCode |
A string with the one-time password generated by the user's device / smartphone. |
200
(OK) status code and returns a JSON object with a
time-limited bearer token which represents the authenticated user.curl -H "Content-Type: application/json" \
-d '{ "passCode": "123456" }' \
https://api.verifalia.com/v2.6/auth/totp/verifications
using Verifalia.Api;
using Verifalia.Api.Security;
class MyTotpProvider : ITotpTokenProvider
{
public Task<string> ProvideTotpTokenAsync(CancellationToken cancellationToken)
{
// TODO: Ask the user to provide their TOTP token
return Task.FromResult("123456");
}
}
var bearerAuth = new BearerAuthenticationProvider("username",
"password",
new MyTotpProvider())
var verifalia = new VerifaliaRestClient(bearerAuth);
// The Java SDK does not support this feature yet.
const verifalia = new VerifaliaRestClient({
authenticator: new BearerAuthenticator('username',
'password',
{
async provideTotp() {
// TODO: Obtain the TOTP either from the user directly or from an external device
return '123456';
}
})
});
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
TLS mutual authentication
Authenticate through a certificate
curl --cert mycertificate.pem \
https://api-cca.verifalia.com/v2.6/...
var certificate = new X509Certificate2("mycertificate.pem");
var verifalia = new VerifaliaRestClient(certificate);
// The Java SDK uses the Java Keystore (JKS) to retrieve TSL client
// certificates. For additional information please see:
// https://github.com/verifalia/verifalia-java-sdk#authenticating-via-x509-client-certificate-tls-mutual-authentication
ClientCertificateAuthenticationProvider authProvider =
new ClientCertificateAuthenticationProvider("mycertificate",
"mypassword",
new File("identity.jks"),
new File("truststore.jks"))
VerifaliaRestClient verifalia =
new VerifaliaRestClient(authProvider);
const verifalia = new VerifaliaRestClient({
cert: fs.readFileSync('mycertificate.pem'),
key: fs.readFileSync('mycertificate.key')
});
use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
$verifalia = new VerifaliaRestClient([
VerifaliaRestClientOptions::CERTIFICATE => '/home/gfring/Documents/pollos.pem'
]);
package main
import (
"crypto/tls"
"github.com/verifalia/verifalia-go-sdk/verifalia"
)
func main() {
cert, err := tls.LoadX509KeyPair("./mycertificate.pem", "./mycertificate.key")
if err != nil {
panic(err)
}
client := verifalia.NewClientWithCertificateAuth(&cert)
// TODO: Use "client" as explained below
}
verifalia = Verifalia::Client.new ssl_client_cert: './my-cert.pem',
ssl_client_key: './my-cert.key'
Data interchange format
Content-Type
header set to application/json
, with the exception of the
job submission through file import which allows for a broader range
of values.Content-Type
HTTP
header equals to application/json
as well.Accept
HTTP header.API endpoints (base URLs)
- https://api-1.verifalia.com/v2.6
- https://api-2.verifalia.com/v2.6
- https://api-3.verifalia.com/v2.6
- https://api-cca-1.verifalia.com/v2.6
- https://api-cca-2.verifalia.com/v2.6
- https://api-cca-3.verifalia.com/v2.6
Single base URL
api.verifalia.com
which points to the
aforementioned API hosts, in a round-robin fashion.- https://api.verifalia.com/v2.6
- https://api-cca.verifalia.com/v2.6
Endpoints security
The Verifalia REST API is served over HTTPS only: to ensure data privacy, unencrypted HTTP is not supported. Also, our HTTPS endpoints require your web client to support Server Name Indication (SNI), a standard widespread extension to the TLS protocol which may be missing in some obsolete systems (most notably, in Microsoft Windows XP and lower version operating systems as well as in wget prior to version 1.14).
For additional safety, our endpoints support these TLS protocol versions:
- TLS 1.0 Deprecated
- TLS 1.1 Deprecated
- TLS 1.2
- TLS 1.3
Content compression
gzip
compression scheme, by way of the Accept-Encoding
HTTP header.Content-Encoding
HTTP
header to determine whether the response is compressed or not.Request a compressed response
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/email-validations
// No code needed, the SDK handles compression automatically
// No code needed, the SDK handles compression automatically
// No code needed, the SDK handles compression automatically
// No code needed, the SDK handles compression automatically
// No code needed, the SDK handles compression automatically
# No code needed, the SDK handles compression automatically
API limits
To help prevent strain on Verifalia's servers, our API imposes a rate limit on
API invocations: a single IP address can't issue more than 6 HTTPS requests per second to our API endpoints,
with a burst limit of 15 HTTPS requests per second: this does not limit the number of concurrent running email
verification jobs a single IP address or account may have however, which is unlimited. If a request exceeds the limit,
we return an HTTP 429
status code.
To avoid hitting the rate limit, it is suggested to reduce the number of requests against our API endpoints: for example, instead of using a loop or a script to verify individual email addresses retrieved from a database, it is advisable to submit a single email verification job with all the email addresses to verify. Not only this would require far less HTTPS requests, it would also be faster and allow to mark duplicates on the submitted entries.
Cross-Origin Resource Sharing
The Verifalia API supports CORS, so that you may send requests directly from the browser, however remember to never expose your account credentials or the credentials of one of your users. If a credentials pair become compromised, you will want to roll a new one.
As a safer alternative, you may want to configure and use a browser app through the Verifalia client area, together with one or more throttling and/or firewall rules.
Paginated results
Key | Description |
---|---|
cursor |
A string with the meta.cursor value obtained from a previous API
call: Verifalia replies with the next page of results. |
cursor:prev |
A string with the meta.cursor value obtained from a previous API
call: Verifalia replies with the previous page of results. |
Property | Description |
---|---|
meta?.isTruncated? |
An optional boolean which signals whether the
response is truncated or not. If not present, the response is not truncated.
|
meta?.cursor? |
An optional string with an opaque token that
must be used to retrieve the next (and previous, where available) result page.
|
data |
An array with zero or more items for the current page of results; the structure of the actual items varies and depends on the type of requested data. |
Paginated response structure example
{
"meta": {
"isTruncated": true,
"cursor": "tkxhHTv5xjrGLbtDAzY0IA=="
},
"data": [
// ...
]
}
HTTP status codes
The Verifalia API uses conventional HTTP status codes to indicate success or failure of a request. Here are the possible HTTP status codes which the API may return:
HTTP status code | Meaning |
---|---|
200 |
Success. The API request completed without any error. |
202 |
Accepted. The API request has been queued and will be completed as soon as possible by the system. |
303 |
See other. The Location HTTP header contains
the final URI of the requested resource. |
400 |
Bad request. Perhaps you are not sending a required parameter or not passing the information using JSON. |
401 |
Unauthorized request. No valid username or password (that is, the credentials of the user) provided; please see how to authenticate to the Verifalia API for additional details. |
402 |
Payment required. Either the credit of your account is too low to process the validation request or the request would exceed the maximum number of monthly processable items. |
403 |
Forbidden request: the client has not enough permissions to perform an action on a resource. |
404 |
Not found. The requested resource does not exist on the server. |
406 |
Not acceptable. The requested resource is not available with respect to its current state. |
410 |
Gone. The requested resource has been deleted and is no longer available on the server. |
415 |
v2.2+ Unsupported media type. The specified content type (or charset) is not supported or is invalid according to the provided data. |
429 |
Too many requests. Returned when a request cannot be served due to the application's rate limit having been exhausted for the client. |
5xx |
Server error. Verifalia failed to fulfill an apparently valid request. |
Problem details v2.6+
In the event of client usage errors (4xx
status codes) and server processing errors (5xx
status codes), the API might send back a problem details JSON document.
This document follows the guidelines in RFC 9457 and is sent with the MIME Content-Type application/problem+json
, with the purpose of providing additional information about the failure in a format that both humans and machines can understand, going beyond just the HTTP response status code.
API consumers need to be resilient and not assume that they'll always receive a problem details JSON document in response to failures, because the service might be unable to do that in certain error scenarios;
additionally, the set of fields returned within problem detail JSON documents is extensible, and API consumers must be tolerant of any new, unrecognized fields they encounter and disregard them.
The structure of a problem details JSON document includes the following fields:
type
title
status
detail
Problem detail JSON sample
{
"type": "/problems/forbidden",
"title": "Access denied",
"status": 403,
"detail": "The user or browser app is not allowed to access this resource, as permission
has been denied by the account administrator. Please note that once saved, permissions
and settings may take up to 10 minutes for changes to take effect."
}
Email validations
/email-validations
Submitting a new validation
/email-validations
200
(OK) status code and the validation
results for consumption, with no further client requests needed.
waitTime
query string
parameter, which defines the number of milliseconds to wait for a given email verification job completion.
The parameter accepts a value between 0
, meaning the API
will never wait for the job completion,
and 30000
, meaning the API
will wait for up to 30 seconds for the job completion. Under certain circumstances (see paragraph above),
the API may choose to ignore this parameter and consider a lower waiting time (or no waiting time at all) instead.
202
(Accepted) status code and an URL (via the Location
HTTP
header) the client must poll in order to obtain the results: in fact, because of the
unpredictable processing time email validations may require (especially for older mail
exchangers) it would be impractical for the client to wait indefinitely in that case.403
(Forbidden) status code if the user has not been granted the required email-validations:write:my permission; v2.1+ the same status code is returned if the user
attempts to specify a data retention period for a job without having been granted the
required email-validations:delete:my or email-validations:delete permissions.Submit an email address for validation
curl -u username:password \
--compressed \
-H "Content-Type: application/json" \
-d '{ "entries": [ { "inputData": "batman@gmail.com" } ] }' \
https://api.verifalia.com/v2.6/email-validations
var verifalia = new VerifaliaRestClient("username", "password");
// By default, SubmitAsync() automatically waits for the job completion
var job = await verifalia
.EmailValidations
.SubmitAsync("batman@gmail.com");
// Note: SubmitAsync() allows to specify the desired results quality and
// accepts arrays of email addresses as well: check its overloads for
// all the supported options.
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
// Option 1: submit the validation
Validation job = verifalia
.getEmailValidations()
.submit("batman@gmail.com");
// Option 2: submit the validation and wait for its completion
Validation job = verifalia
.getEmailValidations()
.submit("batman@gmail.com", new WaitingStrategy(true));
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: check its overloads
// as well as the builder pattern exposed by the ValidationRequest
// class for all the supported options.
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
// By default, submit() automatically waits for the job completion
const job = await verifalia
.emailValidations
.submit('batman@gmail.com');
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: check the docs for
// a list of all the supported options.
use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
$verifalia = new VerifaliaRestClient([
VerifaliaRestClientOptions::USERNAME => 'your-username-here',
VerifaliaRestClientOptions::PASSWORD => 'your-password-here'
]);
// By default, submit() automatically waits for the job completion
$job = $verifalia->emailValidations->submit('batman@gmail.com');
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: check the docs for
// all the supported options.
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Verifies an email address
validation, err := client.EmailValidation.Run("batman@gmail.com")
if err != nil {
panic(err)
}
// Print some results
entry := validation.Entries[0]
fmt.Printf("%v => %v", entry.EmailAddress, entry.Classification)
// Output:
// batman@gmail.com => Deliverable
}
require 'verifalia'
# ...
verifalia = Verifalia::Client.new username: 'username', password: 'password'
# By default, submit() automatically waits for the job completion
job = verifalia.email_validations.submit 'batman@gmail.com'
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: check the docs for
// a list of all the supported options.
Submitting email addresses through a JSON object
Content-Type
header equals to application/json
) with this structure:
entries
inputData
string
representing the email address to verify.
custom
string
with custom data to be
returned upon completion (like an ID in your own database), with a maximum
length of 50 characters.
quality
string
with the name of the
desired results quality; can be any of the following: Standard
, High
, Extreme
. If not specified, Verifalia will use
the default results quality for your account.
priority
number
which sets the priority (speed) of a validation job
relative to the parent Verifalia account. If there are multiple concurrent validation jobs in an account,
this value allows you to adjust the processing speed of a specific job in comparison to others. The valid
range for this priority spans from 0
(lowest) to 255
(highest), with 127
representing normal priority. If not specified,
Verifalia processes all concurrent validation jobs for an account at the same speed.
deduplication
string
with the name of the
algorithm our engine will use to scrub the list of email addresses and remove
its duplicates. The following values are currently supported:
Off
does not mark duplicated email addressesSafe
mark duplicated email addresses with an algorithm which guarantees no false duplicates are returnedRelaxed
v2.1+ mark duplicated email addresses using a set of relaxed rules which assume the target email service providers are configured with modern settings only
name
retention
v2.1+
string
with the desired data
retention period to observe for the validation job, expressed in the format
dd.hh:mm:ss
(where dd
: days, hh
: hours, mm
: minutes, ss
: seconds); the initial dd.
part is added only for periods of more than
24 hours. The value has a minimum of 5 minutes (0:5:0
) and a maximum of 30 days (30.0:0:0
): Verifalia will delete the job and
its data once its data retention period is over, starting to count when it gets
completed. If not specified, Verifalia falls 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.
captcha
v2.6+
provider
string
representing the CAPTCHA service provider.
The following values are currently supported:
Turnstile
for Cloudflare TurnstilereCaptcha_v2
for Google reCAPTCHA v2reCaptcha_v3
for Google reCAPTCHA v3hCaptcha
for hCaptcha
token
string
with the CAPTCHA response token provided by the chosen CAPTCHA service provider.
callback
v2.3+
url
string
with the URL Verifalia will invoke once the job results are ready.
See how to handle completion callbacks.
version
v2.4+
string
which defines the callback schema our dispatcher must obey when invoking
the provided callback URL. Valid values are:
1.0
the callback includes the completed job ID1.1
v2.4+ everything included with1.0
plus the job name
skipServerCertificateValidation
v2.4+
boolean
which allows to skip the server certificate validation for the external callback server,
useful for testing purposes at development time when the callback server is using a self-signed certificate.
Simplest request structure example
{
"entries": [
{ "inputData": "batman@gmail.com" }
]
}
A more complex request structure example
{
"entries": [
{ "inputData": "john.smith@example.com" },
{ "inputData": "batman@example.net", custom: "c_123" },
{ "inputData": "foo@inv@lid.tld" }
],
"quality": "High",
"priority": 100,
"deduplication": "Relaxed",
"callback": {
"url": "https://eznfr2ihu3lao.x.pipedream.net"
}
}
Importing email addresses from a file v2.2+
- plain text files (.txt), with one email address per line
MIME type:
text/plain
- comma-separated values (.csv), tab-separated values (.tsv) and other delimiter-separated values files
MIME types:
text/csv
andtext/tab-separated-values
- Microsoft Excel spreadsheets (.xls and .xlsx)
MIME types:
application/vnd.ms-excel
andapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
415
(Unsupported media type) status code in the event it can't process the provided file format.
Content-Type
header
to multipart/form-data
and pass a file part named inputFile
along with a recognized MIME type (see above).
settings
, with the email verification options Verifalia must obey while processing the file,
including specific settings which depend on the uploaded file format, mentioned in the sections below.
Property | Description |
---|---|
quality? |
An optional string with the name of the
desired results quality; can be any of the following: Standard , High , Extreme . If not specified, Verifalia will use
the default results quality for your account. |
priority? |
An optional number which sets the priority of
the validation job, relative to the parent Verifalia account. In the event of an
account with many concurrent jobs at the same time, this value allows to
increase the processing slot time percentage of a job with respect to the
others. The allowed range of integer values spans from 0 (lowest priority) to 255 (highest priority), where the midway value
127 means normal priority; if not specified,
Verifalia processes the validation job without a specific priority. |
deduplication? |
An optional string with the name of the
algorithm our engine will use to scrub the list of email addresses and remove
its duplicates. The following values are currently supported:
If not specified, Verifalia will not mark duplicated email
addresses.
|
name? |
An optional user-defined name for the validation job, for your own reference. |
retention? |
An optional string with the desired data
retention period to observe for the validation job, expressed in the format
dd.hh:mm:ss (where dd : days, hh : hours, mm : minutes, ss : seconds); the initial dd. part is added only for periods of more than
24 hours. The value has a minimum of 5 minutes (0:5:0 ) and a maximum of 30 days (30.0:0:0 ): Verifalia will delete the job and
its data once its data retention period is over, starting to count when it gets
completed. If not specified, Verifalia falls 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. |
startingRow? |
An optional number with the zero-based index of the first row to import and process.
If not specified, Verifalia will start processing files from the first (0) row. |
endingRow? |
An optional number with the zero-based index of the last row to import and process.
If not specified, Verifalia will process rows until the end of the file. |
Format-specific settings
settings
part can contain additional properties which
are specific to the format of the uploaded file.
Importing a file
curl -u username:password \
--compressed \
-F 'inputFile=@my-list.xls;type=application/vnd.ms-excel' \
https://api.verifalia.com/v2.6/email-validations
// Initialize the request using the file to import
var request = new FileValidationRequest("./my-list.xls");
// Submit the validation and wait for its completion
var validation = await verifalia
.EmailValidations
.SubmitAsync(request);
// Note: SubmitAsync() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
FileValidationRequest request = new FileValidationRequest("my-list.xls",
WellKnownMimeTypes.EXCEL_XLS);
// Submit the validation and wait for its completion
Validation validation = verifalia
.getEmailValidations()
.submit(request, new WaitingStrategy(true));
// Import the MIME content type for Excel files (just a string, for our convenience)
import { MimeContentType_ExcelXlsx } from 'verifalia/node/esm/index.mjs';
// Initialize the request using the file to import
const file = fs.createReadStream('/home/john/sample.xlsx');
// Submit the validation and wait for its completion
const result = await verifalia
.emailValidations
.submit({
file: file,
contentType: MimeContentType_ExcelXlsx,
startingRow: 1,
quality: 'high',
deduplication: 'safe'
});
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
// The PHP SDK does not support importing files yet
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
"os"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Verifies an Excel file with a list of email addresses
thatFile, err := os.Open("that-file.xslx")
if err != nil {
panic(err)
}
validation, err = client.EmailValidation.RunFile(thatFile)
if err != nil {
panic(err)
}
// Print some results
for _, entry := range validation.Entries {
fmt.Printf("%v => %v\n",
entry.EmailAddress,
entry.Classification)
}
}
# The Ruby SDK does not support importing files yet
Plain text import settings
Content-Type
header, for example: Content-Type: text/plain; charset=iso-8859-2
.
When the charset is not provided, Verifalia uses the UTF-8 encoding by default.
settings
part:
Property | Description |
---|---|
lineEnding? |
An optional string with the line ending sequence of the text file;
can be any of the following:
CrLf or its alias \r\n ,
Cr or its alias \r ,
Lf or its alias \n ,
Auto .
If not specified, Verifalia will use the Auto option, which attempts to guess the correct line ending.
|
curl -u username:password \
--compressed \
-F 'settings="{ \"startingRow\": 42 }";type=application/json' \
-F 'inputFile=@my-list.txt;type=text/plain' \
https://api.verifalia.com/v2.6/email-validations
var request = new FileValidationRequest("./contacts.txt")
{
StartingRow = 2,
LineEnding = LineEndingMode.CrLf
};
// Submit the validation and wait for its completion
var validation = await verifalia
.EmailValidations
.SubmitAsync(request);
// Note: SubmitAsync() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
FileValidationRequest request = new FileValidationRequest("my-list.txt",
WellKnownMimeTypes.TEXT_PLAIN);
request.setStartingRow(42);
Validation validation = verifalia
.getEmailValidations()
.submit(request);
// Initialize the request using the file to import
const file = fs.createReadStream('/contacts.txt');
// Submit the validation and wait for its completion
const result = await verifalia
.emailValidations
.submit({
file: file,
contentType: 'text/plain',
startingRow: 2,
lineEnding: '\r\n'
});
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
// The PHP SDK does not support importing files yet
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
"github.com/verifalia/verifalia-go-sdk/verifalia/emailValidation"
"os"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Verifies a plain text file with a list of email addresses
thatFile, err := os.Open("my-list.txt")
if err != nil {
panic(err)
}
// Specify which data Verifalia should process through the file options
fileOptions := emailValidation.FileSubmissionOptions{
StartingRow: 42,
}
validation, err = client.EmailValidation.RunFileWithOptions(thatFile,
fileOptions,
nil,
nil)
// ...
}
# The Ruby SDK does not support importing files yet
CSV / TSV / DSV import settings
Content-Type
header, for example: Content-Type: text/csv; charset=iso-8859-2
.
When the charset is not provided, Verifalia uses the UTF-8 encoding by default.
settings
part:
Property | Description |
---|---|
lineEnding? |
An optional string with the line ending sequence of the CSV / TSV / delimiter-separated file;
can be any of the following:
CrLf or its alias \r\n ,
Cr or its alias \r ,
Lf or its alias \n ,
Auto .
If not specified, Verifalia will use the Auto option, which attempts to guess the correct line ending.
|
delimiter? |
An optional string with the column delimiter sequence of the text file.
If not specified, Verifalia will use the , (comma) symbol for CSV files and the
\t (tab) symbol for TSV files.
|
column? |
An optional number with the zero-based index of the column to import.
If not specified, Verifalia will use the first (0) column.
|
curl -u username:password \
--compressed \
-F 'settings="{ \"delimiter\": \";\", \"startingRow\": 2 }";type=application/json' \
-F 'inputFile=@my-list.csv;type=text/csv' \
https://api.verifalia.com/v2.6/email-validations
var request = new FileValidationRequest("./my-list.csv")
{
StartingRow = 2,
Column = 1,
Delimiter = ";"
};
// Submit the validation and wait for its completion
var validation = await verifalia
.EmailValidations
.SubmitAsync(request);
// Note: SubmitAsync() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
FileValidationRequest request = new FileValidationRequest("my-list.csv",
WellKnownMimeTypes.TEXT_CSV);
request.setDelimiter(";"); // The default delimiter is comma (",")
request.setStartingRow(2);
Validation validation = verifalia
.getEmailValidations()
.submit(request);
// Initialize the request using the file to import
const file = fs.createReadStream('/my-list.csv');
// Submit the validation and wait for its completion
const result = await verifalia
.emailValidations
.submit({
file: file,
contentType: 'text/csv',
startingRow: 2,
delimiter: ';'
});
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
// The PHP SDK does not support importing files yet
# The Ruby SDK does not support importing files yet
Excel file import settings
settings
part:
Property | Description |
---|---|
sheet? |
An optional number with the zero-based index of the worksheet to import.
If not specified, Verifalia will use the first (0) worksheet.
|
column? |
An optional number with the zero-based index of the column to import.
If not specified, Verifalia will use the first (0) column of the specified sheet. If both values are not specified,
the first column of the first sheet will be imported.
|
curl -u username:password \
--compressed \
-F 'settings="{ \"quality\": \"High\", \"column\": 2, \"startingRow\": 1 }";type=application/json' \
-F 'inputFile=@my-list.xls;type=application/vnd.ms-excel' \
https://api.verifalia.com/v2.6/email-validations
var request = new FileValidationRequest("./sheet.xlsx")
{
Column = 2,
Sheet = 1
};
// Submit the validation and wait for its completion
var validation = await verifalia
.EmailValidations
.SubmitAsync(request);
// Note: SubmitAsync() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
FileValidationRequest request = new FileValidationRequest("my-list.xls",
WellKnownMimeTypes.EXCEL_XLS);
request.setQuality(QualityLevelName.High);
request.setColumn(2);
request.setStartingRow(1);
Validation validation = verifalia
.getEmailValidations()
.submit(request);
// Import the MIME content type for Excel files (just a string, for our convenience)
import { MimeContentType_ExcelXlsx } from 'verifalia/node/esm/index.mjs';
// Initialize the request using the file to import
const file = fs.createReadStream('./sheet.xlsx');
// Submit the validation and wait for its completion
const result = await verifalia
.emailValidations
.submit({
file: file,
contentType: MimeContentType_ExcelXlsx,
startingRow: 1,
column: 2
});
// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: also, the method allows to
// configure the import operation as needed (see the section below for
// the details).
// The PHP SDK does not support importing files yet
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
"github.com/verifalia/verifalia-go-sdk/verifalia/emailValidation"
"os"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Verifies an Excel file with a list of email addresses
thatFile, err := os.Open("that-file.xslx")
if err != nil {
panic(err)
}
// Configure the validation options
options := emailValidation.SubmissionOptions{
// High quality results
Quality: emailValidation.Quality.High,
// One hour of data retention
Retention: 1 * time.Hour,
}
// Specify which data Verifalia should process through the file options
fileOptions := emailValidation.FileSubmissionOptions{
// Second sheet
Sheet: 1,
// Ninth sheet
Column: 8,
// Will start importing from the third row
StartingRow: 2,
}
validation, err = client.EmailValidation.RunFileWithOptions(thatFile,
fileOptions,
options,
nil)
if err != nil {
panic(err)
}
// Print some results
for _, entry := range validation.Entries {
fmt.Printf("%v => %v\n",
entry.EmailAddress,
entry.Classification)
}
}
# The Ruby SDK does not support importing files yet
CAPTCHA - Bot detection v2.6+
Verifalia can automatically verify CAPTCHA tokens generated by multiple CAPTCHA service providers, ensuring that only email verifications submitted 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 client area: these settings enable communication between the Verifalia servers and the configured CAPTCHA service.
After completing this setup, every subsequent email verification payload must include a captcha
hash
at the time of submission: this hash should specify both the type of CAPTCHA service provider via the provider
field
and the CAPTCHA response token provided by that service in response to a CAPTCHA challenge, indicated by the token
field.
Otherwise, the submission will fail with an HTTP 401
status code.
The provider
field accepts one of the following values:
Turnstile
for Cloudflare TurnstilereCaptcha_v2
for Google reCAPTCHA v2reCaptcha_v3
for Google reCAPTCHA v3hCaptcha
for hCaptcha
The token
field must contain the CAPTCHA response token provided by the
chosen CAPTCHA service provider; to learn how to obtain a CAPTCHA response token, please consult the documentation for your CAPTCHA service provider of choice:
Completion callback v2.3+
POST
request against the specified callback URL, along
with a skinny JSON payload which includes, for security reasons, just the data essential to handle the event: that includes the completed job id, which can subsequently be used to
retrieve the final verification results. The Content-Type
header of the callback request will be application/json
.
2xx
HTTP status code: all response codes
outside this range, including 3xx
codes, indicate that you did not receive the callback event. Also your endpoint
must respond within a maximum of 5 seconds, otherwise the callback invocation will be considered failed.
In the event of a callback endpoint failure or timeout, Verifalia attempts to deliver your callback events for up to 24 hours, with an exponential backoff.
Property | Description |
---|---|
event.type |
The type of the event, which is always email-validation.completed for the email verification completion callback. |
event.version callback v1.1+ |
The version of the event schema, according to the callback?.version specified at the job submission time. |
event.createdOn |
The creation timestamp of the event, in the ISO 8601 format. |
event.data.id |
The string representing the id of the completed email verification job. |
event.data.name callback v1.1+ |
The string with the user-supplied name of the completed email verification job. |
Idempotency
Idempotency-Key
header with an opaque string value, which remains constant for all the eventual callback retries.
Completion callback JSON sample
{
"event": {
"type": "email-validation.completed",
"version": "1.1",
"data": {
"id": "a8efc16254b84c25b1d2463891dce479",
"name": "leads-crm-export"
},
"createdOn": "2023-02-14T08:56:17.3384646Z"
}
}
Getting validation results
/email-validations/{id}
id
is the unique ID generated by
Verifalia upon receiving the email validation request.202
(Accepted) status code and
the client should reissue the request at a later time to retrieve an updated job snapshot: advanced API consumers may take advantage of the
estimated remaining time indication, if available, to limit the number of pollings.waitTime
query string
parameter, which defines the number of milliseconds to wait for a given email verification job completion.
The parameter accepts a value between 0
(the default value), meaning the API
will never wait for the job completion,
and 30000
, meaning the API
will wait for up to 30 seconds for the job completion. Under certain circumstances,
the API may choose to ignore this parameter and consider a lower waiting time (or no waiting time at all) instead.
/email-validations/{id}/overview
id
is the unique ID generated by
Verifalia upon receiving the email validation request.Retrieve an email validation job
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53
var verifalia = new VerifaliaRestClient("username", "password");
// By default, GetAsync() automatically waits for job completion
var job = await verifalia
.EmailValidations
.GetAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"));
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Validation job = verifalia
.getEmailValidations()
.get("54375b5b-a399-4bc4-abd8-b8c02e109e53");
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
const job = await verifalia
.emailValidations
.get('54375b5b-a399-4bc4-abd8-b8c02e109e53');
use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
$verifalia = new VerifaliaRestClient([
VerifaliaRestClientOptions::USERNAME => 'your-username-here',
VerifaliaRestClientOptions::PASSWORD => 'your-password-here'
]);
$job = $verifalia->emailValidations->get('ec415ecd-0d0b-49c4-a5f0-f35c182e40ea');
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
"github.com/verifalia/verifalia-go-sdk/verifalia/emailValidation"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Retrieve an email validation job, given its Id
validation, err := client.EmailValidation.Get("9ece66cf-916c-4313-9c40-b8a73f0ef872")
if err != nil {
panic(err)
}
if validation.Overview.Status == emailValidation.Status.Completed {
// validation.Entries will have the validation results!
} else {
// What about having a coffee?
}
}
verifalia = Verifalia::Client.new username: 'username', password: 'password'
job_id = 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea'
job = verifalia.email_validations.get job_id
Job snapshots
Property | Description |
---|---|
overview |
A structure with general details about the job. See structure details. |
entries? |
A structure with the validated email addresses and their results, when available. See structure details. |
Job overviews
/email-validations/{id}/overview
id
is the unique ID generated by
Verifalia upon receiving the email validation request.waitTime
query string
parameter, which defines the number of milliseconds to wait for a given email verification job completion.
The parameter accepts a value between 0
(the default value), meaning the API
will never wait for the job completion,
and 30000
, meaning the API
will wait for up to 30 seconds for the job completion. Under certain circumstances,
the API may choose to ignore this parameter and consider a lower waiting time (or no waiting time at all) instead.
Retrieve a job overview
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/overview
var verifalia = new VerifaliaRestClient("username", "password");
// By default, GetOverviewAsync() automatically waits for job completion
var jobOverview = await verifalia
.EmailValidations
.GetOverviewAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"));
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
ValidationOverview jobOverview = verifalia
.getEmailValidations()
.getOverview("54375b5b-a399-4bc4-abd8-b8c02e109e53");
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
Property | Description |
---|---|
id |
A string representing the unique identifier
for the job which Verifalia generates upon receiving an email validation
request. |
status |
A string with the status of the whole job.
Can be one of the following values:
|
name? |
A string with the user-defined name
eventually given to this job at the time of its submission: used for your own
internal reference. |
owner |
A string representing the unique identifier
of the user which created the job. |
clientIP |
A string with the IP address of the API
consumer which created the job. |
quality |
A string with the name of the results quality
level requested for the job; can be one of Standard , High and Extreme (or other values for custom quality
levels). |
deduplication |
A string with the name of the deduplication
algorithm requested for the job; can be one of Off , Safe
and Relaxed v2.1+. |
noOfEntries |
The number of email addresses included in
this job. |
createdOn |
A string representing the timestamp of the
creation of the job, in the ISO
8601 format. |
submittedOn? |
A string representing the timestamp of the
eventual submission of the job, in the ISO 8601 format. |
completedOn? |
A string representing the timestamp of the
eventual completion of the job, in the ISO 8601 format. |
priority? |
A number representing the priority (speed) of a validation job relative to the parent Verifalia account.
If there are multiple concurrent validation jobs in an account, this value allows you to adjust the processing speed of a specific job in comparison
to others. The valid range for this priority spans from 0 (lowest) to 255 (highest),
with 127 representing normal priority. If not specified, Verifalia processes all concurrent validation jobs for an
account at the same speed.
|
retention v2.1+ |
A string with the data retention period to
observe for the validation job, expressed in the format dd.hh:mm:ss (where dd : days, hh : hours, mm : minutes, ss : seconds); the initial dd. part is added only for periods of more than
24 hours. Verifalia deletes the job and its data once its retention period is
over, starting to count when the job gets completed. |
progress?.percentage |
The overall progress percentage for the job, when available, expressed as a
number between 0 and 1 .
|
progress?.estimatedTimeRemaining? |
A string representing the estimated remaining
time for completing the email validation job, expressed in the format dd.hh:mm:ss (where dd : days, hh : hours, mm : minutes, ss : seconds); the initial dd. part is added only for huge lists requiring
more than 24 hours to complete. |
Job overview structure example
{
"id": "18f5a933-af67-421c-b63a-1cbee297fa19",
"status": "Completed",
"owner": "c86d09f2-c0d4-4582-bc3e-bc97fdbb6579",
"clientIP": "2.21.41.70",
"quality": "Standard",
"deduplication": "Off",
"noOfEntries": 1,
"createdOn": "2023-01-21T08:52:21.53Z",
"submittedOn": "2023-01-21T08:52:21.53Z",
"completedOn": "2023-01-21T08:52:21.757Z",
"retention": "00:05:00"
}
Job entries
/email-validations/{id}/entries
id
is the unique ID generated by
Verifalia upon receiving the email validation request.waitTime
query string
parameter, which defines the number of milliseconds to wait for a given email verification job completion.
The parameter accepts a value between 0
(the default value), meaning the API
will never wait for the job completion,
and 30000
, meaning the API
will wait for up to 30 seconds for the job completion. Under certain circumstances,
the API may choose to ignore this parameter and consider a lower waiting time (or no waiting time at all) instead.
Retrieve job entries
# curl can retrieve a single result page at a time.
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/entries
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var entries = verifalia
.EmailValidations
.ListEntriesAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"));
await foreach (var entry in entries)
{
// TODO: Use the validated entry
}
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Iterable<ValidationEntry> validationEntries = verifalia
.getEmailValidations()
.listEntries("54375b5b-a399-4bc4-abd8-b8c02e109e53");
for (ValidationEntry validationEntry : validationEntries) {
// ...
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
Filtering entries
Success
or ServerIsCatchAll
); it is also prossible to reverse the
condition and get all the entries excluding the ones with certain status code(s).Key | Description |
---|---|
status |
One or more email validation status codes representing the only values you wish
to get from the API. Multiple values are separated with the comma (, ) symbol. |
status:exclude |
One or more email validation status codes representing the values you wish to
exclude from the API result. Multiple values are separated with the comma (, ) symbol. |
Retrieve filtered job entries
# curl can retrieve a single result page at a time.
curl -u username:password \
--compressed \
"https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/entries?status=Success,ServerIsCatchAll"
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var entries = verifalia
.EmailValidations
.ListEntriesAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"),
new ValidationEntryListingOptions
{
StatusFilter = new ValidationEntryStatusMatchPredicate
{
IncludedValues = new[]
{
ValidationEntryStatus.Success,
ValidationEntryStatus.ServerIsCatchAll
}
}
});
await foreach (var entry in entries)
{
// TODO: Use the validated entry
}
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Iterable<ValidationEntry> validationEntries = verifalia
.getEmailValidations()
.listEntries("54375b5b-a399-4bc4-abd8-b8c02e109e53",
ValidationEntryListingOptions
.builder()
.statuses(
new SetInclusionPredicate<>(ValidationEntryStatus.Success,
ValidationEntryStatus.ServerIsCatchAll))
.build());
for (ValidationEntry validationEntry : validationEntries) {
// ...
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
Limiting entries
Key | Description |
---|---|
limit |
An integer number specifying the desired maximum amount of validated entries to
be returned in a single results page; subsequent / previous pages can be
retrieved as described in the paginated
results, optionally in conjunction with the limit parameter to keep getting a limited
amount of results. |
Retrieve limited job entries
# curl can retrieve a single result page at a time.
curl -u username:password \
--compressed \
"https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/entries?limit=1000"
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var entries = verifalia
.EmailValidations
.ListEntriesAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"),
new ValidationEntryListingOptions
{
// ListEntriesAsync() will automatically iterate over all the
// result pages, thus the specified Limit will only be used
// internally to the SDK and not as a way to constrain the
// overall number of returned items.
Limit = 1000
});
await foreach (var entry in entries)
{
// TODO: Use the validated entry
}
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Iterable<ValidationEntry> validationEntries = verifalia
.getEmailValidations()
.listEntries("54375b5b-a399-4bc4-abd8-b8c02e109e53",
ValidationEntryListingOptions
.builder()
// listEntries() will automatically iterate over all the
// result pages, thus the specified limit will only be used
// internally to the SDK and not as a way to constrain the
// overall number of returned items.
.limit(1000)
.build());
for (ValidationEntry validationEntry : validationEntries) {
// ...
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
Getting an entry from its index
/email-validations/{id}/entries/{index}
id
is the unique ID generated by Verifalia upon
receiving the email validation request and index
is the
zero-based index of the required entry in the whole email validation job.303
(see
other) status code, along with an HTTP Location
header
pointing at a job entries page which contains the required item.waitTime
query string
parameter, which defines the number of milliseconds to wait for a given email verification job completion.
The parameter accepts a value between 0
(the default value), meaning the API
will never wait for the job completion,
and 30000
, meaning the API
will wait for up to 30 seconds for the job completion. Under certain circumstances,
the API may choose to ignore this parameter and consider a lower waiting time (or no waiting time at all) instead.
Locate a job entries page by entry index
# curl automatically follows 303 redirects, so we will get the result
# entries page for the specified index, here:
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/entries/42
// The .NET SDK does not support this feature yet.
// The Java SDK does not support this feature yet.
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
# The Ruby SDK does not support this feature yet.
Property | Description |
---|---|
index |
A number with the zero-based index of the
entry, with respect to the whole job; this value is mostly useful in the event
the API consumer requests a filtered entries set. |
inputData |
A string with the original input data
submitted for validation. |
classification |
A string representing the name of the
classification for the email validation, which groups related email validation
status codes; can be a custom string or one of the following values:
|
status |
A string representing the name of the
specific result status for the email validation. It can be any of the validation status codes described below.
|
emailAddress? |
A string with the eventually recognized email
address, without any comment or FWS (folding white space) symbol. |
emailAddressLocalPart? |
A string with the local part of the email
address. |
emailAddressDomainPart? |
A string with the domain part of the email
address. |
asciiEmailAddressDomainPart? |
A string with the domain part of the email
address converted to ASCII, using the |
hasInternationalMailboxName? |
A boolean which, if set, signals the email
address has an international, non-ASCII mailbox name. |
hasInternationalDomainName? |
A boolean which, if set, signals the email
address has an international, non-ASCII domain name. |
isDisposableEmailAddress? |
A boolean which, if set, signals the email
address is a temporary, throw-away, disposable address. |
isRoleAccount? |
A boolean which, if set, signals the local
part of the email address is possibly referring to a well-known group of people,
instead of a single person. |
isFreeEmailAddress? |
A boolean which, if set, signals the email
address is handled by a well-known Free email service provider (e.g. Gmail,
Yahoo, Outlook / Live / Hotmail, etc.). |
syntaxFailureIndex? |
A number which, if set, refers to the
zero-based position of the first syntax error in the inputData property. |
suggestions? v2.5+ |
A string[] which, if set, contains the AI-generated alternative spellings that are more likely to be the correct email. |
custom? |
A string with the eventual custom data
included with the entry at the job submission time. |
duplicateOf? |
A number with the eventual zero-based index
of the entry which appears to be duplicated by this item. Only present when the
status property equals to Duplicate . |
completedOn |
A string representing the timestamp of the
eventual completion of the entry, in the ISO 8601 format. |
Simple job entries structure example
{
"data": [
{
"index": 0,
"inputData": "batman@gmail.com",
"completedOn": "2019-07-31T10:49:20.5957669Z",
"emailAddress": "batman@gmail.com",
"asciiEmailAddressDomainPart": "gmail.com",
"emailAddressLocalPart": "batman",
"emailAddressDomainPart": "gmail.com",
"hasInternationalDomainName": false,
"hasInternationalMailboxName": false,
"isDisposableEmailAddress": false,
"isRoleAccount": false,
"isFreeEmailAddress": true,
"status": "Success",
"classification": "Deliverable"
}
]
}
Job entries structure example with multiple email addresses
{
"meta": {
"cursor": "14l/srjfPJo7fP0hFuHsXA==",
"isTruncated": true
},
"data": [
{
"index": 0,
"inputData": "batman@gmail.com",
"completedOn": "2019-07-31T10:49:20.5957669Z",
"emailAddress": "batman@gmail.com",
"asciiEmailAddressDomainPart": "gmail.com",
"emailAddressLocalPart": "batman",
"emailAddressDomainPart": "gmail.com",
"hasInternationalDomainName": false,
"hasInternationalMailboxName": false,
"isDisposableEmailAddress": false,
"isRoleAccount": false,
"isFreeEmailAddress": true,
"status": "Success",
"classification": "Deliverable"
},
{
// ...
},
{
"index": 999,
"inputData": "steve.vai@best.music",
"completedOn": "2019-07-31T10:49:23.1029945Z",
"emailAddress": "steve.vai@best.music",
"asciiEmailAddressDomainPart": "best.music",
"emailAddressLocalPart": "steve.vai",
"emailAddressDomainPart": "best.music",
"hasInternationalDomainName": false,
"hasInternationalMailboxName": false,
"isDisposableEmailAddress": false,
"isRoleAccount": false,
"isFreeEmailAddress": false,
"status": "DomainDoesNotExist",
"classification": "Undeliverable"
}
]
}
Exporting entries v2.3+
Accept
header:
Output format | Accept header value |
---|---|
Comma-Separated Values (CSV) | text/csv |
Microsoft Excel (.xlsx) | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Microsoft Excel 97-2003 (.xls) | application/vnd.ms-excel |
Export job entries as a CSV file
curl -u username:password \
--compressed \
--header "Accept: text/csv" \
https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/entries
var verifalia = new VerifaliaRestClient("username", "password");
var jobId = Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53");
// Export the job to a stream
await using var stream = await verifalia
.EmailValidations
.ExportEntriesAsync(jobId, ExportedEntriesFormat.ExcelXlsx);
// Open the target output file stream
await using var target = File.Open(@"./export.xlsx",
FileMode.CreateNew);
// Copy the source into the target stream
stream.CopyToAsync(target);
// The Java SDK does not support this feature yet.
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
const exportedData = await verifalia
.emailValidations
.export('dc21630a-6773-4bd0-b248-15e8b50c0d3e',
MimeContentType_TextCsv);
// In Node.js: save it to a file
exportedData.pipe(fs.createWriteStream('/home/lbanfi/my-list.csv'));
// Browser-only: show it inside an IFRAME
document
.getElementByID('myIFrame')
.src = exportedData.toBlobURL(MimeContentType_TextCsv);
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
job_id = 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea'
format = 'text/csv'
data = verifalia.email_validations.export job_id, format
File.open('./export.csv', 'wb') do |fp|
fp.write(data)
end
Validation status codes
Status code | Description |
---|---|
AtSignNotFound |
Invalid email format: the @ symbol, used to separate the local part from the domain part of the address, has not been found. |
CatchAllValidationTimeout |
Validation failed due to a timeout while verifying the rejection of a fake email address by the mail server. Trying a higher results quality level is likely to provide a definitive response. |
DnsConnectionFailure |
Email verification failed due to a socket connection error while querying the DNS server(s) for records about the email address domain. Trying a higher results quality level is likely to provide a definitive response. |
DnsQueryTimeout |
A timeout occurred while querying the DNS servers for records about the domain. Trying a higher results quality level is likely to provide a definitive response. |
DomainDoesNotExist |
Invalid email address: the domain of the email address does not exist. |
DomainIsMisconfigured |
Invalid email address: the domain lacks valid DNS records and cannot receive messages from external hosts on the Internet. |
DomainHasNullMx v2.1+ |
Invalid email address, the domain intentionally does not have any mail servers configured to receive email messages. |
DomainIsWellKnownDea |
High-risk email type: the email address is associated with a well-known disposable email address (DEA). We strongly recommend removing DEAs from your lists. |
DomainPartCompliancyFailure |
Invalid email format: the domain part of the email address does not comply with IETF standards. |
DoubleDotSequence |
Invalid email format: an invalid sequence of two adjacent dots has been found. |
Duplicate |
The email is a duplicate of another entry that has been previously verified in this list; the duplicateOf property contains the zero-based
index of its first occurrence. |
InvalidAddressLength |
Invalid email format: the email address has an invalid total length. |
InvalidCharacterInSequence |
Invalid email format: an invalid character has been detected in the provided sequence. |
InvalidEmptyQuotedWord |
Invalid email format: an invalid quoted word with no content has been found. |
InvalidFoldingWhiteSpaceSequence |
Invalid email format: an invalid folding white space (FWS) sequence has been found. |
InvalidLocalPartLength |
Invalid email format: the local part of the email address has an invalid length. |
InvalidWordBoundaryStart |
Invalid email format: a new word boundary has been detected at an invalid position. |
IspSpecificSyntaxFailure |
Invalid email format: the email address does not comply with the specific formatting requirements of the target service provider. |
LocalEndPointRejected |
Validation failed because the external mail exchanger rejected the local endpoint. Trying a higher results quality level is likely to provide a definitive response. |
LocalSenderAddressRejected |
Validation failed because the external mail exchanger rejected the local sender address. Trying a higher results quality level is likely to provide a definitive response. |
MailboxDoesNotExist |
Invalid email address: the mailbox for the email address does not exist. |
MailboxHasInsufficientStorage |
The mailbox for the email address is either over its storage quota, or the mail exchanger has insufficient system storage. |
MailboxIsDea |
Risky email type: the email address is associated with a disposable / throw-away mailbox. We recommend removing disposable email addresses (DEAs) from your lists. |
MailboxTemporarilyUnavailable |
Validation failed because the requested mailbox is temporarily unavailable. This doesn't necessarily mean the mailbox doesn't exist; it's often a response from mail exchangers with greylisting enabled. Trying a higher results quality level is likely to provide a definitive response. |
MailboxValidationTimeout |
Validation failed due to a timeout while verifying the existence of the mailbox. Trying a higher results quality level is likely to provide a definitive response. |
MailExchangerIsHoneypot |
High-risk email type: the email address is a honeypot (also known as spamtrap). We strongly advise removing honeypots from your lists. |
MailExchangerIsParked v2.4+ |
High-risk email type: the email address is served by a parked or inactive mail exchanger, which may potentially resell collected email data. We strongly recommend removing this address from your lists. |
MailExchangerIsWellKnownDea |
High-risk email type: the email address is associated with a well-known disposable email address provider (DEA). We strongly recommend removing DEAs from your lists. |
OverrideMatch v2.5+ |
Input data matches a custom classifier rule expression of the submitter. |
ServerDoesNotAllowMultipleRecipients |
Possibly risky email type: the external mail exchanger may accept fake and nonexistent email addresses. Therefore, the provided email address may not exist, and the existence of the individual mailbox could not be verified. Trying a higher results quality level is likely to provide a definitive response. |
ServerDoesNotSupportInternationalMailboxes
|
Invalid email address: the external mail exchanger does not support international mailbox names. To support this feature, mail exchangers must comply with RFC 5336 and announce support for both the 8BITMIME and UTF8SMTP protocol extensions. |
ServerIsCatchAll |
Possibly risky email type: the external mail exchanger accepts fake and nonexistent email addresses. Therefore, the provided email address may not exist, and the existence of the individual mailbox cannot be verified. |
ServerTemporaryUnavailable |
Validation failed because the external mail exchanger is temporarily unavailable. Trying a higher results quality level is likely to provide a definitive response. Note: the presence of a typo in this status code is intentional and serves the purpose of maintaining backward compatibility with older API clients. |
SmtpConnectionFailure |
Possibly invalid email address: a socket connection error occurred while trying to connect to the mail exchanger that serves the email address domain. Trying a higher results quality level is likely to provide a definitive response. |
SmtpConnectionTimeout |
Possibly invalid email address: a timeout occurred while trying to connect to the mail exchanger that serves the email address domain. Trying a higher results quality level is likely to provide a definitive response. |
SmtpDialogError |
Validation failed because the external mail exchanger replied in a non-standard way. Trying a higher results quality level is likely to provide a definitive response. |
Success |
Valid email, with no high-risk factors detected: safe to send mail, which completes our multi-step verification process successfully. |
UnacceptableDomainLiteral |
Invalid email: the domain literal of the email address cannot accept messages from the Internet. While Verifalia supports them, domain literals are quite rare nowadays. |
UnbalancedCommentParenthesis |
Invalid email format: the number of parentheses used to open comments is not equal to the number used to close them. |
UnexpectedQuotedPairSequence |
Invalid email format: an unexpected quoted pair sequence has been found within a quoted word. |
UnhandledException |
Validation failed due to unexpected technical issues during the processing of this email address. Retry may provide a definitive response. |
UnmatchedQuotedPair |
Invalid email format: a quoted pair within a quoted word is not properly closed. |
Listing validation jobs
/email-validations
200
(OK) status code and the requested data if the operation succeeded or with an HTTP 403
(Forbidden) if the user has not been granted the
required listing permission (email-validations:list
to list any job for the account or email-validations:list:my for just the ones submitted
by the requesting user) and reading permission (email-validations:read to read any job data for the
account or email-validations:read:my for just the
ones submitted by the requesting user).List email validation jobs
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/email-validations
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var jobOverviews = verifalia
.EmailValidations
.ListAsync();
await foreach (var jobOverview in jobOverviews)
{
// ...
}
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Iterable<ValidationOverview> jobs = verifalia
.getEmailValidations()
.list();
for (ValidationOverview job : jobs) {
// ...
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
"github.com/verifalia/verifalia-go-sdk/verifalia/common"
"github.com/verifalia/verifalia-go-sdk/verifalia/emailValidation"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Configure the options to have the most recent job first
listingOptions := emailValidation.ListingOptions{
Direction: common.Backward,
}
// Proceed with the asynchronous listing
results := client.EmailValidation.ListWithOptions(listingOptions)
count := 0
for result := range results {
if result.Error != nil {
panic(result.Error)
}
fmt.Printf("Id: %v, submitted: %v, status: %v, entries: %v\n",
result.JobOverview.Id,
result.JobOverview.SubmittedOn,
result.JobOverview.Status,
result.JobOverview.NoOfEntries)
// Limit the iteration to the first 20 items
count++
if count > 20 {
break
}
}
// Output:
// Id: 7a7987a3-cc86-4ae8-b3d7-ff0088620503, submitted: 2022-06-18 12:56:43.908432 +0000 UTC, status: InProgress, entries: 23
// Id: 2c4b1d73-a7b3-40e3-a1b8-748dc499d9f7, submitted: 2022-06-18 12:56:15.698191 +0000 UTC, status: Completed, entries: 12
// Id: b918a5cb-a853-4cb0-a591-7c8ca21978db, submitted: 2022-06-18 12:56:12.981241 +0000 UTC, status: Completed, entries: 126
// Id: e3d769b7-e033-422a-b1d8-0a088f566f8d, submitted: 2022-06-18 12:56:02.613184 +0000 UTC, status: Completed, entries: 1
// Id: 0001aef1-e94f-40c4-b45e-9999f7e37de4, submitted: 2022-06-18 12:56:01.602428 +0000 UTC, status: Completed, entries: 65
// Id: 0e6c0b38-f3ce-4847-bee8-95947f772242, submitted: 2022-06-18 12:56:01.019199 +0000 UTC, status: Completed, entries: 18
// Id: 7fedfcb8-4be8-449f-99f4-7ae09e5e8cb5, submitted: 2022-06-18 12:55:54.18652 +0000 UTC, status: Completed, entries: 1
// ...
}
Filtering and sorting
Key | Description | ||||||
---|---|---|---|---|---|---|---|
createdOn |
A string representing the required date,
expressed according to ISO
8601 (yyyy-mm-dd). |
||||||
createdOn:since |
A string representing the inclusive beginning
date of the required period, expressed according to ISO 8601 (yyyy-mm-dd).
|
||||||
createdOn:until |
A string representing the inclusive ending
date of the required period, expressed according to ISO 8601 (yyyy-mm-dd).
|
||||||
status |
One or more job status codes representing the values you wish to include from
the API result. Multiple values are separated with the comma (, ) symbol. |
||||||
status:exclude |
One or more job status codes representing the values you wish to exclude from
the API result. Multiple values are separated with the comma (, ) symbol. |
||||||
owner |
A string representing the Id of the user
which you wish to filter the results for; if present, the API will return only
the jobs submitted by the specified user. |
||||||
sort |
A string representing the required sorting to
apply to the listing operation. Can be one of the following values:
|
List jobs for a specific period
curl -u username:password \
--compressed \
"https://api.verifalia.com/v2.6/email-validations?createdOn=2023-05-26"
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var jobOverviews = verifalia
.EmailValidations
.ListAsync(new ValidationOverviewListingOptions
{
Direction = Direction.Backward,
CreatedOn = new DateEqualityPredicate(new DateTime(2023, 5, 26))
});
await foreach (var jobOverview in jobOverviews)
{
// ...
}
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Iterable<ValidationOverview> jobs = verifalia
.getEmailValidations()
.list(ValidationOverviewListingOptions
.builder()
.createdOn(new DateEqualityPredicate(LocalDate.of(2023, 5, 26)))
.build());
for (ValidationOverview job : jobs) {
// ...
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
Deleting an email validation job
/email-validations/{id}
id
is the auto-generated random ID
returned by Verifalia upon creating the validation job.200
(OK) status code if the removal succeeded or with an HTTP 410
(Gone) if the job has already been deleted; should the
validation be still in progress, the API would reply with an HTTP 406
(Not acceptable) status code.403
(Forbidden) status code in the event the API
consumer does not have the required grant.Delete an email validation job
curl -X DELETE \
-u username:password \
https://api.verifalia.com/v2.6/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53
var verifalia = new VerifaliaRestClient("username", "password");
await verifalia
.EmailValidations
.DeleteAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"));
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
verifalia
.getEmailValidations()
.delete("54375b5b-a399-4bc4-abd8-b8c02e109e53");
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
await verifalia
.emailValidations
.delete('54375b5b-a399-4bc4-abd8-b8c02e109e53');
use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
$verifalia = new VerifaliaRestClient([
VerifaliaRestClientOptions::USERNAME => 'your-username-here',
VerifaliaRestClientOptions::PASSWORD => 'your-password-here'
]);
$verifalia->emailValidations->delete('ec415ecd-0d0b-49c4-a5f0-f35c182e40ea');
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Delete an email validation job, given its Id
err := client.EmailValidation.Delete("9ece66cf-916c-4313-9c40-b8a73f0ef872")
if err != nil {
panic(err)
}
}
job_id = 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea'
verifalia.email_validations.delete job_id
Result quality levels
/email-validations/quality-levels
List the quality levels
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/email-validations/quality-levels
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var qualityLevels = verifalia
.EmailValidations
.ListQualityLevelsAsync();
await foreach (var qualityLevel in qualityLevels)
{
// ...
}
// The Java SDK does not support this feature yet.
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
Property | Description |
---|---|
id |
A string with the identifier of the results
quality level; main, advertised values are Standard , High and Extreme . |
displayName |
A string containing the name of the results
quality level, for display purposes. |
unitPrice |
A number with the unit cost (in Verifalia
credits) of each email address validated using the quality level. |
isDefault? |
A boolean set to true for the default quality level of the
requesting API consumer. |
isCustom? |
A boolean set to true in the event the quality level is a
custom, ad-hoc one. |
isUnavailable? |
A boolean set to true for quality levels which are not available
to the API consumer. |
Quality levels response structure example
{
"meta": {
// ...
},
"data": [
{
"id": "Standard",
"displayName": "Standard",
"isDefault": true,
"unitPrice": 1
},
{
"id": "High",
"displayName": "High",
"unitPrice": 2
},
// ...
{
"id": "155abd3b-5fa6-4e3b-b0fb-612f83634de1",
"displayName": "A custom quality level",
"unitPrice": 2.125,
"isCustom": true
}
]
}
Credits
Credits balance
/credits/balance
200
(OK) status code if the operation succeeded or with an HTTP 403
(Forbidden) if the user has not been granted the
required credits:read permission.Get the credits balance
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/credits/balance
var verifalia = new VerifaliaRestClient("username", "password");
var balance = await verifalia
.Credits
.GetBalanceAsync();
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Balance balance = verifalia
.getCredits()
.getBalance();
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
const balance = await verifalia
.credits
.getBalance();
use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
$verifalia = new VerifaliaRestClient([
VerifaliaRestClientOptions::USERNAME => 'your-username-here',
VerifaliaRestClientOptions::PASSWORD => 'your-password-here'
]);
$balance = $verifalia->credits->getBalance();
package main
import (
"fmt"
"github.com/verifalia/verifalia-go-sdk/verifalia"
)
func main() {
client := verifalia.NewClient("<USERNAME>", "<PASSWORD>") // See above
// Get the available credits balance
balance, err := client.Credit.GetBalance()
if err != nil {
panic(err)
}
fmt.Printf("Credit packs: %v, free daily credits: %v (will reset in %v)\n",
balance.CreditPacks,
balance.FreeCredits,
balance.FreeCreditsResetIn)
// Output:
// Credit packs: 956.332, free daily credits: 128.66 (will reset in 9h8m23s)
}
balance = verifalia.credits.get_balance
puts "Credit packs: #{balance.credit_packs}"
puts "Free daily credits: #{balance.free_credits} (will reset in #{balance.free_credits_reset_in})"
Property | Description |
---|---|
creditPacks |
The number of credit packs (that is, the
non-expiring credits). |
freeCredits? |
The number of daily credits, where available.
|
freeCreditsResetIn? |
A string representing the amount of time before
the daily credits expire, where available, expressed in the form hh:mm:ss . |
Credits balance structure example
{
"creditPacks": 9633.516,
"freeCredits": 28.962,
"freeCreditsResetIn": "14:29:15"
}
Credits usage statistics
/credits/daily-usage
200
(OK) status code and the requested data if the operation succeeded or with an HTTP 403
(Forbidden) if the user has not been granted the
required credits:read permission.Get last credits usage
curl -u username:password \
--compressed \
https://api.verifalia.com/v2.6/credits/daily-usage
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var dailyUsages = verifalia
.Credits
.ListDailyUsagesAsync();
await foreach (var dailyUsage in dailyUsages)
{
// ...
}
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Iterable<DailyUsage> dailyUsages = verifalia
.getCredits()
.listDailyUsages();
for (DailyUsage dailyUsage : dailyUsages) {
// ...
}
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
const dailyUsages = verifalia
.credits
.listDailyUsages();
for await (const dailyUsage of dailyUsages) {
// ...
}
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
Filtering the consumption period
Key | Description |
---|---|
date |
A string representing the required date,
expressed according to ISO
8601 (yyyy-mm-dd). |
date:since |
A string representing the inclusive beginning
date of the required period, expressed according to ISO 8601 (yyyy-mm-dd).
|
date:until |
A string representing the inclusive ending
date of the required period, expressed according to ISO 8601 (yyyy-mm-dd).
|
Get credits usage for a specific period
curl -u username:password \
--compressed \
"https://api.verifalia.com/v2.6/credits/daily-usage?date:since=2021-07-01&date:until=2021-07-09"
var verifalia = new VerifaliaRestClient("username", "password");
// Uses the C# 8.0 async enumerable feature; for previous language
// versions please check the SDK help.
var dailyUsages = verifalia
.Credits
.ListDailyUsagesAsync(new DailyUsageListingOptions
{
DateFilter = new DateBetweenPredicate
{
Since = new DateTime(2020, 7, 1),
Until = new DateTime(2020, 7, 9),
}
});
await foreach (var dailyUsage in dailyUsages)
{
// ...
}
VerifaliaRestClient verifalia =
new VerifaliaRestClient("username", "password");
Iterable<DailyUsage> dailyUsages = verifalia
.getCredits()
.listDailyUsages(DailyUsageListingOptions
.builder()
.dateFilter(
new DateBetweenPredicate(LocalDate.of(2020, 6, 1),
LocalDate.of(2020, 6, 10)))
.build());
for (DailyUsage dailyUsage : dailyUsages) {
// ...
}
const verifalia = new VerifaliaRestClient({
username: 'username',
password: 'password'
});
const dailyUsages = verifalia
.credits
.listDailyUsages({
dateFilter = new DateBetweenPredicate
{
since = new Date('2020-07-01'),
until = new Date('2020-07-09'),
}
});
for await (const dailyUsage of dailyUsages) {
// ...
}
// The PHP SDK does not support this feature yet.
// The Go SDK does not support this feature yet.
Property | Description |
---|---|
date |
A string representing the date of the item,
expressed according to ISO 8601
(yyyy-mm-dd). |
freeCredits |
The number of consumed daily free credits. |
creditPacks |
The number of consumed credit packs (that is, the
non-expiring credits). |
Credits usage structure example
{
"meta": {
// ...
}
"data": [
{
"date": "2023-01-09",
"freeCredits": 50,
"creditPacks": 2.352
},
{
"date": "2023-01-07",
"freeCredits": 15.262,
"creditPacks": 0
},
// ...
]
}
Changelog / What's new
API v2.6
- New feature Bot detection / CAPTCHA integration, ensuring that only email verifications from real humans are processed; with support for Cloudflare Turnstile, Google reCAPTCHA v2 (checkbox and invisible), Google reCAPTCHA v3 and hCaptcha.
- New feature Configurable maximum numbers of entries per job submission.
- New feature Bearer authentication tokens are now returned as RFC 7519 JSON web tokens (JWT).
- New feature Multi-Factor Authentication (MFA) is now accessible for all users (previously, it was only available for root accounts).
- New feature HTTP 4xx and 5xx errors are now returned, when possible, in the problem detail (aka
problem+json
) format as defined in RFC 9457.
API v2.5
- New feature Advanced typo detection capabilities, backed by AI-powered suggestions.
- New feature Support for customizable classification scheme, for tailored email address categorization.
- New feature Support for classification override rules, allowing blacklisting or whitelisting using wildcard expressions.
API v2.4
- New feature Ability to specify a wait time while submitting an email verification or retrieving an in-progress verification job.
- New feature Support for detecting parked mail exchangers, along with a dedicated verification status code.
- New feature Support for passing the user-defined job name in callback requests.
- New feature Support for skipping the server certificate validation for callback requests (useful during development and for test purposes).
API v2.3
- New feature Ability to specify a callback URL while submitting an email verification, which our service will invoke once the results are ready.
- New feature Export capability for verification results: it is now possible to export human-readable reports of completed email verification jobs as either comma-separated values (.csv) files or Excel spreadsheets (.xlsx and .xls).
API v2.2
- New feature Ability to import and submit files with the email addresses to verify, with support for plain text files (.txt), comma-separated values (.csv) / tab-separated values (.tsv) / generic delimiter-separated values files, and Excel spreadsheets (.xlsx and .xls).
API v2.1
- New feature Ability to specify a data retention period at the email verification job level, with fallbacks to the user / browser app level and a final fallback to the account level (with a default of 30 days). Verifalia observes that data retention period and automatically delete jobs on your behalf. This allows to easily further restrict the amount of time personal data (email addresses) is kept on our databases, in accordance with EU GDPR.
- New feature New deduplication algorithm named "Relaxed" you can choose to detect duplicate email addresses using a set of relaxed rules, which assume the target email service providers are configured with modern settings only (instead of the broader options the RFCs from the '80s allow.
- New feature Detection of NULL MX RR in the DNS configuration of the domains under test, allowing Verifalia to verify undeliverable email addresses even faster than before.
Latest tweets - twitter.com/verifalia
We’ve just released v3.1 of our PHP SDK, featuring support for importing and verifying mailing list files in multiple formats, exporting results in various formats, and more. Check it out!
.NET developers: we've just released version 4.2.1 of our .NET SDK and NuGet package, featuring an improved API for .NET 8.0 and enhanced documentation. Learn more
Starting today, our email verification service can detect disposable / temporary Gmail and Outlook addresses; these special addresses may look legitimate but should be removed from your mailing lists because they lead to fake registrations and false engagement. Learn more
🚨 Big news: we've just upgraded our AI for detecting disposable / temporary emails! Our email checker can now identify over 1 million burner domains, with fresh updates every hour.
From our blog
Understanding the reasons behind email bounces is key to maintaining a successful email marketing strategy: by proactively verifying your email list, following best practices, and regularly monitoring your bounce rates, you can protect your sender reputation and ensure that your messages land where they’re meant to - your recipient’s inbox.
After more than two decades of service, SORBS (Spam and Open Relay Blocking System), a pioneering force in the realm of DNS-based blacklists (DNSBL), has officially ceased operations as of June 5, 2024: learn more about the rich history of SORBS, its technical intricacies, and its eventual decommissioning.