Documentation Powered by ReDoc

MillionVerifier API (3.1.0)

Download OpenAPI specification:Download

API stands for Application Programming Interface. You can connect our system with your website, landing page, application or software to verify emails in real time or to send us files programmatically.

Using MillionVerifier's API you can avoid bad emails added to your email lists. You may also use our API to resell our services.

Authentication

Use your API key to identify your account when making an API call. Each endpoint contains an example of how to use our API. Simply just replace "your-api-key" with your API key you can find on this page: https://app.millionverifier.com/api

Test API key for development: "API_KEY_FOR_TEST". This API key will return random results.

SSL Information

The following versions (or above) are supported to make a succesful request in certain programming languages:

  • PHP 5.4.45 <=
  • Python (Requests module) 1.0.0 <=
  • cURL 7.65.3 <=
  • Java (OpenJDK) 10 <=
  • NodeJS 0.10.28 <=
  • C# (.NET Core) 2.1 <=

Servers

Single API

Verify an email address in real time as your subscriber signs up to your newsletter. For cleaning larger databases please use our Bulk API.

Special characters in the email address should be encoded.

Demo API keys:

  • API_KEY_FOR_TEST
    • Returns with a random response
  • API_KEY_FOR_UNVERIFIED
  • API_KEY_FOR_OK
  • API_KEY_FOR_CATCH_ALL
  • API_KEY_FOR_INVALID
  • API_KEY_FOR_UNKOWN
  • API_KEY_FOR_DISPOSABLE
  • API_KEY_FOR_ERROR_NO_EMAIL
  • API_KEY_FOR_ERROR_NO_APIKEY
  • API_KEY_FOR_ERROR_INVALID_APIKEY
  • API_KEY_FOR_ERROR_INSUFFICIENT_CREDITS
  • API_KEY_FOR_ERROR_IP_ADDRESS_BLOCKED
  • API_KEY_FOR_ERROR_INTERNAL_ERROR

Verify an email address in real time

Verify an email address in real time and get resutls in just a second.

query Parameters
api
required
string
Example: api=your-api-key

Your API key

email
required
string

Email address that needs to be verified

timeout
integer
Example: timeout=10

Time in seconds to terminate the connection in case no response recevied from the recipient server. You can set between 2 and 60 seconds. Default timeout is 20 seconds.

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.millionverifier.com/api/v3/?api=your-api-key&[email protected]&timeout=10',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
Example
SingleApiResponse
SingleApiResponse
SingleApiResponseBadApiKey
SingleApiResponseMissingEmail
{
  • "email": "[email protected]",
  • "quality": "good",
  • "result": "invalid",
  • "resultcode": 6,
  • "subresult": "unknown",
  • "free": false,
  • "role": false,
  • "didyoumean": "[email protected]",
  • "credits": 3454,
  • "executiontime": 2,
  • "error": "",
  • "livemode": true
}

Bulk API

Send your emails in a CSV file programmatically and retrieve your results.

File upload

Upload file containing email addresses for verification

query Parameters
key
required
string
Example: key=your-api-key

Your API key

Request Body schema: multipart/form-data

Request parameters for upload

file_contents
string <binary>

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bulkapi.millionverifier.com/bulkapi/v2/upload?key=your-api-key',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('file_contents'=> new CURLFILE('path/to/file')),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
Example
BulkapiUploadSuccess
BulkapiUploadSuccess
BulkapiInsufficientCredits
{
  • "file_id": "940",
  • "file_name": "mails500.txt",
  • "status": "in_progress",
  • "unique_emails": 257,
  • "updated_at": "2021-05-16 12:25:42",
  • "createdate": "2021-05-16 12:25:42",
  • "percent": 60,
  • "total_rows": 500,
  • "verified": 0,
  • "unverified": 0,
  • "ok": 0,
  • "catch_all": 0,
  • "disposable": 0,
  • "invalid": 0,
  • "unknown": 0,
  • "reverify": 0,
  • "credit": 0,
  • "estimated_time_sec": 120,
  • "error": ""
}

File info

Get info of the uploaded file

query Parameters
key
required
string
Example: key=your-api-key

Your API key

file_id
required
integer
Example: file_id=940

The ID of the uploaded file

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bulkapi.millionverifier.com/bulkapi/v2/fileinfo?key=your-api-key&file_id=940',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
{
  • "file_id": "940",
  • "file_name": "mails500.txt",
  • "status": "in_progress",
  • "unique_emails": 257,
  • "updated_at": "2021-05-16 12:25:42",
  • "createdate": "2021-05-16 12:25:42",
  • "percent": 60,
  • "total_rows": 500,
  • "verified": 0,
  • "unverified": 0,
  • "ok": 0,
  • "catch_all": 0,
  • "disposable": 0,
  • "invalid": 0,
  • "unknown": 0,
  • "reverify": 0,
  • "credit": 0,
  • "estimated_time_sec": 120,
  • "error": ""
}

Files list

Get a list of files according to the given filters

query Parameters
key
required
string
Example: key=your-api-key

Your API key

offset
integer
Example: offset=0

Offset for pagination

limit
integer
Example: limit=25

The amount of files to show on one page. Defaults to 50, which is also the maximum amount that can be used for limit

id
integer
Example: id=1

Filter for file IDs. To filter for multiple file IDs, use comma separated values e.g.: id=1,2,3

name
string
Example: name=myfile.txt

Filter for file name. It checks if any of the file names contain the given filter

status
string
Enum: "in_progress" "error" "finished" "canceled" "paused" "in_queue_to_start"
Example: status=in_progress,error

Filter for file state. To filter for multiple file states, use comma separatedvalues e.g.: status=in_progress,finished. Any state type that does not match the possible values will be ignored

updated_at_from
string <yyyy-MM-dd HH:mm:ss>
Example: updated_at_from=2023-01-01 15:00:05

Filter for files that were updated after the given date time. If the given value does not match the format, the filter will be ignored

updated_at_to
string <yyyy-MM-dd HH:mm:ss>
Example: updated_at_to=2023-01-01 15:00:05

Filter for files that were updated before the given date time. If the given value does not match the format, the filter will be ignored

createdate_from
string <yyyy-MM-dd HH:mm:ss>
Example: createdate_from=2023-01-01 15:00:05

Filter for files that were created after the given date time. If the given value does not match the format, the filter will be ignored

createdate_to
string <yyyy-MM-dd HH:mm:ss>
Example: createdate_to=2023-01-01 15:00:05

Filter for files that were created before the given date time. If the given value does not match the format, the filter will be ignored

percent_from
integer
Example: percent_from=50

Filter for files that has a progress over the given percentage

percent_to
integer
Example: percent_to=75

Filter for files that has a progress below the given percentage

has_error
string
Enum: "1" "t" "T" "TRUE" "True" "true" "0" "f" "F" "FALSE" "False" "false"
Example: has_error=0

Filter for files that either had or didn't have any errors. It accepts the listed boolean values. Any other values will be ignored

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bulkapi.millionverifier.com/bulkapi/v2/filelist?key=your-api-key&offset=0&limit=0&status=in_progress&updated_at_from=2023-01-18%2015:00:00&percent_from=5&percent_to=75&has_error=0',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "total": 1
}

Download report

Download report of the verification result

query Parameters
key
required
string
Example: key=your-api-key

Your API key

file_id
required
string
Example: file_id=940

The ID of the uploaded file

filter
required
string
Enum: "ok" "ok_and_catch_all" "unknown" "invalid" "all" "custom"
Example: filter=all

Download only filtered results

statuses
string
Enum: "ok" "catch_all" "unknown" "invalid" "disposable"
Example: statuses=ok,disposable,invalid

When the 'custom' filter is used, result statuses can be given as a comma separated values. If omitted, then all statuses will be in the results

free
string
Enum: "1" "0"

When the 'custom' filter is used, this option decides whether to filter for free domains or not. If omitted, both type of domains will be in the results

role
string
Enum: "1" "0"

When the 'custom' filter is used, this option decides whether to filter for role emails or not. If omitted, both type of emails will be in the results

Responses

Request samples 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bulkapi.millionverifier.com/bulkapi/v2/download?key=your-api-key&file_id=940&filter=all',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
application/json
application/octet-stream
Example
Invalid_API_key
Invalid_API_key
Unsupported_filter_value
File_id_is_empty
{
  • "error": "invalid_api_key"
}

Stop a file in Progress

This will cancel the file in progress and the results for already verified emails can be downloaded in a few seconds

query Parameters
key
required
string
Example: key=your-api-key

Your API key

file_id
required
string
Example: file_id=940

The ID of the uploaded file

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bulkapi.millionverifier.com/bulkapi/stop?key=your-api-key&file_id=942',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
Example
BulkApiStopSuccessfulRequest
BulkApiStopSuccessfulRequest
BulkApiStopBadRequest
{
  • "result": "ok"
}

Delete a file

This will delete a file uploaded to the bulk API

query Parameters
key
required
string
Example: key=your-api-key

Your API key

file_id
required
string
Example: file_id=115

The ID of the uploaded file

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bulkapi.millionverifier.com/bulkapi/v2/delete?key=your-api-key&file_id=115',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
Example
BulkApiStopSuccessfulRequest
BulkApiStopSuccessfulRequest
BulkApiStopBadRequest
{
  • "result": "ok"
}

API credits

Get information of the available credits on your account.

API credits

Check the amount of available credits

query Parameters
api
required
string
Example: api=your-api-key

Your API key

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.millionverifier.com/api/v3/credits?api=your-api-key',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response samples

Content type
application/json
{
  • "credits": 12345,
  • "bulk_credits": 12345,
  • "renewing_credits": 0,
  • "plan": 4
}