g}" />

API

  1. Home
  2. API

# Single Mail API

Request HTTP GET - Synchronous request

$ curl -s -i -X GET 'https://api.mailvalidator.io/validatemail?mailaddress=<testEmail@address.com>&apiKey=<yourAPIkey>'

Response JSON String

{
 "success": <true|false>,
 "mailToValidate": 
   {
    "mailAddress": "<testEmail@address.com>",
    "validAddress": "<VALID|INVALID|CANNOT_VERIFY>"
   }
 |
 "exception": "<corresponding error message>"
}

Example VALID:

{
 "success": true,
 "mailToValidate":
   {
    "mailAddress": "testEmail@address.com",
    "validAddress": "VALID"
   }
}

Example ERROR:

{
 "success": false,
 "exception":
   {
    "simpleName": "InvalidApiKeyException",
    "message": "The given API KEY: <123456789> is invalid!"
   }
}
{
 "success": false,
 "exception":
   {
    "simpleName": "UnauthorizedException",
    "message": "Invalid API KEY: <123456789> OR no credit left OR too much requests for this IP ADDRESS: 0:0:0:0:0:0:0:1"
   }
}

# Batch Mail API

The Batch validation is an Asynchronous process:
  1. Submit all email addresses you want to verify and you get a Queue URL
  2a. Query the Queue URL and get the Result URL
  2b. Once is done when you query the Queue URL you get the Result URL
  3. Query the Result URL to get the validation result

Request - Step 1: Submit the mail addresses

HTTP POST - Synchronous request

$ curl -s -i -X POST -H "Content-Type: application/json" -d
   '{
     "mailAddresses" : [ "<yourmail1@address.com>", "<yourmail2@address.com>", "<yourmail3@address.com>" ],
     "apiKey" : "<yourAPIkey>"
    }'
    'https://api.mailvalidator.io/validatemails'

Response - Step 1: get the Queue URL to follow the status of the validation

HTTP Code + Location Header

HTTP/1.1 201
Location: https://api.mailvalidator.io/queue/<queueId>

HTTP Code + JSON String (Error case)

HTTP/1.1 400
{
 "success": false,
 "exception":
   {
    "simpleName": "<Exception Name>",
    "message": "<Exception Description>"
   }
}

Request - Step 2: query the Queue URL and get the Result URL

HTTP GET - Synchronous request

$ curl -s -i -X GET 'https://api.mailvalidator.io/queue/<queueId>'

Response - Step 2: get the Result URL to know where to go to get the validation's result

HTTP Code + JSON String (Job not yet done)

HTTP/1.1 200
{
 "status": "PENDING"
}

HTTP Code + Location Header (Job done, get the Results URL)

HTTP/1.1 303
Location: https://api.mailvalidator.io/results/<resultId>

HTTP Code + Connection Close (Error case, invalid Queue ID)

HTTP/1.1 400
Connection: close

Request - Step 3: query the Result URL to get the validation's result

HTTP GET - Synchronous request

$ curl -s -i -X GET 'https://api.mailvalidator.io/results/<resultId>'

Response - Step 3: get the validation's result

HTTP Code + JSON String

HTTP/1.1 200
[
 {
  "mailAddress": "<yourmail1@address.com>",
  "validAddress": "<VALID|INVALID|CANNOT_VERIFY>"
 },
 {
  "mailAddress": "<yourmail2@address.com>",
  "validAddress": "<VALID|INVALID|CANNOT_VERIFY>"
 },
 {
  "mailAddress": "<yourmail3@address.com>",
  "validAddress": "<VALID|INVALID|CANNOT_VERIFY>"
 }
]

HTTP Code + Connection Close (Error case, invalid Result ID)

HTTP/1.1 400
Connection: close