The latest version of our client area includes several new features designed to enhance our email verification service and simplify its use: this blog post highlights the key updates.
Verifying email addresses
Not a developer?
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
Language:
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
Language:
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.
|
Language:
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.
|
Language:
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.
|
Language:
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"
}
}
Need Help?
We're here to assist you.
Visit Our Help Center
Send Us a Message
Want to chat?
Latest tweets - twitter.com/verifalia
We are excited to announce our updated client area! Now featuring multiple administrators, personalized contact settings, enhanced permissions, and improved navigation: learn more.
Verifying Yahoo email addresses is now 40% faster! We've just updated our email verification algorithms for quicker results.
🎉 We've just launched version 1.13 of our free email verification widget, which Google Tag Manager (GTM) now supports. Plus, this new version brings support for custom trusted origins and SamCart! 🚀✨
New year, new features! 🎉 We've just added support for trusted origins, making it easier for you to control which websites can host browser apps, in accordance with RFC 6454. This includes, of course, our embeddable email verification widget! 🪄
From our blog
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.
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.