Verifalia API reference guide

Verifalia exposes a RESTful email validation API which is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors.

Not a software developer?

Verifalia is a web-based email validation service which allows to upload and validate lists of email addresses with ease: you don't need to be a software developer to use Verifalia!
Just upload your list of email addresses and we will validate them for you, giving you back a detailed report.
The Verifalia API uses built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients.
Authenticate via HTTP Basic Auth
curl -u username:password
    https://api.verifalia.com/v2.0/...
using Verifalia.Api;
// ...
var verifalia = new VerifaliaRestClient("username", "password");
const { VerifaliaRestClient } = require('verifalia');

const verifalia = new VerifaliaRestClient({
    username: 'username',
    password: 'password'
});
use \Verifalia\VerifaliaRestClient;

$verifalia = new VerifaliaRestClient([
    'username' => 'your-username-here',
    'password' => 'your-password-here'
]);
Request a bearer token
curl -H "Content-Type: application/json"
    -d "{ username: 'samantha', password: '42istheanswer' }"
    https://api.verifalia.com/v2.0/auth/tokens
// The C# 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.
Use the obtained bearer token
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1...JV_adQssw5c"
    https://api.verifalia.com/v2.0/...
// The C# 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.
Authenticate through a certificate
curl --cert mycertificate.pem
    https://api.verifalia.com/v2.0/...
var certificate = new X509Certificate2("mycertificate.pem");
var verifalia = new VerifaliaRestClient(certificate);
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
Request a compressed response
curl -u username:password
    --compressed                                    
    https://api.verifalia.com/v2.0/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
Paginated response structure example
{
    "meta": {
        "isTruncated": true,
        "cursor": "tkxhHTv5xjrGLbtDAzY0IA=="
    },
    "data": [
        // ...
    ]
}
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.0/email-validations
var verifalia = new VerifaliaRestClient("username", "password");

// Option 1: submit the validation

var job = await verifalia
    .EmailValidations
    .SubmitAsync("batman@gmail.com");

// Option 2: submit the validation and wait for its completion

var job = await verifalia
    .EmailValidations
    .SubmitAsync("batman@gmail.com", new WaitingStrategy(true));

// 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.
const verifalia = new VerifaliaRestClient({
    username: 'username',
    password: 'password'
});

// Option 1: submit the validation

const job = await verifalia
    .emailValidations
    .submit('batman@gmail.com');

// Option 2: submit the validation and wait for its completion

const job = await verifalia
    .emailValidations
    .submit('batman@gmail.com', true);

// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: check its parameter
// list for all the supported options.
$verifalia = new VerifaliaRestClient([
    'username' => 'your-username-here',
    'password' => 'your-password-here'
]);

// Option 1: submit the validation

$job = $verifalia
    ->emailValidations
    ->submit('batman@gmail.com');

// Option 2: submit the validation and wait for its completion

$job = $verifalia
    ->emailValidations
    ->submit('batman@gmail.com', true);

// Note: submit() allows to specify the desired results quality and
// accepts arrays of email addresses as well: check its parameter
// list for all the supported options.
Simple 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: 'Safe'
}
Retrieve an email validation job
curl -u username:password
    --compressed
    https://api.verifalia.com/v2.0/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53
var verifalia = new VerifaliaRestClient("username", "password");

var job = await verifalia
    .EmailValidations
    .GetAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"));
const verifalia = new VerifaliaRestClient({
    username: 'username',
    password: 'password'
});

const job = await verifalia
    .emailValidations
    .get('54375b5b-a399-4bc4-abd8-b8c02e109e53');
$verifalia = new VerifaliaRestClient([
    'username' => 'your-username-here',
    'password' => 'your-password-here'
]);

$job = $verifalia
    ->emailValidations
    ->get('54375b5b-a399-4bc4-abd8-b8c02e109e53');
Retrieve a job overview
curl -u username:password
    --compressed
    https://api.verifalia.com/v2.0/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/overview
var verifalia = new VerifaliaRestClient("username", "password");

var jobOverview = await verifalia
    .EmailValidations
    .GetOverviewAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"));
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
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: "2019-07-31T08:52:21.53Z",
    submittedOn: "2019-07-31T08:52:21.53Z",
    completedOn: "2019-07-31T08:52:21.757Z"
}
Retrieve job entries
# curl can retrieve a single result page at a time.
curl -u username:password
    --compressed
    https://api.verifalia.com/v2.0/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
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.

Retrieve filtered job entries

# curl can retrieve a single result page at a time.

curl -u username:password
    --compressed
    "https://api.verifalia.com/v2.0/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
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
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.0/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53/entries[42]
// The C# 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.
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"
        }
    ]
}
List email validation jobs
curl -u username:password
    --compressed
    https://api.verifalia.com/v2.0/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)
{
    // ...
}
// The Javascript SDK does not support this feature yet.
// The PHP SDK does not support this feature yet.
List jobs for a specific period
curl -u username:password
    --compressed
    "https://api.verifalia.com/v2.0/email-validations?date=2019-07-09"
// The C# 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.
JSON structure
Verifalia returns listings of email validations through a JSON object which derive from the common paginated results structure described above, where each data item has the same JSON structure of the job overviews.
Delete an email validation job
curl -X DELETE
    -u username:password
    https://api.verifalia.com/v2.0/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53
var verifalia = new VerifaliaRestClient("username", "password");
        
await verifalia
    .EmailValidations
    .DeleteAsync(Guid.Parse("54375b5b-a399-4bc4-abd8-b8c02e109e53"));
const verifalia = new VerifaliaRestClient({
    username: 'username',
    password: 'password'
});

await verifalia
    .emailValidations
    .delete('54375b5b-a399-4bc4-abd8-b8c02e109e53');
$verifalia = new VerifaliaRestClient([
    'username' => 'your-username-here',
    'password' => 'your-password-here'
]);

$verifalia
    ->emailValidations
    ->delete('54375b5b-a399-4bc4-abd8-b8c02e109e53');
List the quality levels
# curl can retrieve a single result page at a time.
curl -u username:password
    --compressed
    https://api.verifalia.com/v2.0/email-validations/quality-levels
// The C# 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.
Quality levels response structure example
{
    meta: {
        // ...
    },
    data: [
        {
            id: "Standard",
            displayName: "Standard",
            isDefault: true,
            unitPrice: 0.008
        },
        {
            id: "High",
            displayName: "High",
            unitPrice: 0.02
        },
        // ...
        {
            id: "155abd3b-5fa6-4e3b-b0fb-612f83634de1",
            displayName: "A custom quality level",
            unitPrice: 0.01,
            isCustom: true
        }
    ]
}
Get the credits balance
curl -u username:password
    --compressed
    https://api.verifalia.com/v2.0/credits/balance
var verifalia = new VerifaliaRestClient("username", "password");

var balance = await verifalia
    .Credits
    .GetBalanceAsync();
const verifalia = new VerifaliaRestClient({
    username: 'username',
    password: 'password'
});

const balance = await verifalia
    .credits
    .getBalance();
$verifalia = new VerifaliaRestClient([
    'username' => 'your-username-here',
    'password' => 'your-password-here'
]);

$balance = $verifalia
    ->credits
    ->getBalance();
JSON structure
The credit balance of the account is returned through a JSON structure with these properties:
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.
Depending on their plans, certain Verifalia accounts may not have free daily credits: in this case, the API returns only the number of credit packs.
Credits balance structure example
{
    creditPacks: 9633.516,
    freeCredits: 28.962,
    freeCreditsResetIn: '14:29:15'
}
Get last credits usage
curl -u username:password
    --compressed
    https://api.verifalia.com/v2.0/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)
{
    // ...
}
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.
Get credits usage for a specific period
curl -u username:password
    --compressed
    "https://api.verifalia.com/v2.0/credits/daily-usage?date:since=2019-07-01&date:until:2019-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(2019, 7, 1),
                Until = new DateTime(2019, 7, 9),
            }
        });

await foreach (var dailyUsage in dailyUsages)
{
    // ...
}
const verifalia = new VerifaliaRestClient({
    username: 'username',
    password: 'password'
});

const dailyUsages = verifalia
    .credits
    .listDailyUsages({
		dateFilter = new DateBetweenPredicate
		{
			since = new Date('2019-07-01'),
			until = new Date('2019-07-09'),
		}
	});

for await (const dailyUsage of dailyUsages) {
    // ...
}
// The PHP SDK does not support this feature yet.
JSON structure
Verifalia returns the credits usage consumption through a JSON object which derives from the common paginated results structure described above, where each data item has this JSON structure:
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: '2019-07-09',
            freeCredits: 50,
            creditPacks: 2.352
        },
        {
            date: '2019-07-07',
            freeCredits: 15.262,
            creditPacks: 0
        },
        // ...
    ]
}