Responses

All requests are performed via an HTTPS connection and responses are returned as JSON. All responses will contain a success parameter. This parameter will indicate whether the requested operation was successfully completed or if an error was encountered.

Always check the response status code to ensure the request was successfully received and successfully handled.

Success Response

200 OK

The success message for a single validation:

HTTP/1.1 200 OK

{
    "result": "deliverable",
    "message": "This address can receive emails.",    
    "email": "[email protected]",
    "user": "support",
    "domain": "validto.com",
    "accept_all": 2,
    "role": 1,
    "free_email": 0,
    "disposable": 0,
    "spamtrap": 0,
    "success": true
}

The success response you get when bulk validation list is successfully uploaded:

HTTP/1.1 200 OK

{
    "success": true,
    "job_id": "e7sb72fbi3a93s4aitfayvardxa3qiqvffxy",
    "message": "Bulk email verification list has been created and starts verification shortly"
}

The success response you get when bulk validation starts instead of auto-verify:

HTTP/1.1 200 OK
{
    "job_id": "e7sb72fbi3a93s4aitfayvardxa3qiqvffxy",
    "success": true,
    "message": "Job verification will be attempted shortly. Call /status endpoint to know the status of the Job"
}

The success response you get when you check the list's progress:

HTTP/1.1 200 OK
{
    "job_id": "e7sb72fbi3a93s4aitfayvardxa3qiqvffxy",
    "status": "completed",
    "created_at": "07/19/2024, 09:08:26 AM",
    "total": 3,
    "verified": 3,
    "pending": 0,
    "analysis": {
        "common_isp": 2,
        "role_based": 1,
        "disposable": 0,
        "spamtrap": 0,
        "syntax_error": 0
    },
    "results": {
        "deliverable": 2,
        "undeliverable": 0,
        "accept_all": 1,
        "unknown": 0
    },
    "success": true,
    "message": "Verification completed successfully. Please download the result using /download endpoint"
}

The success response you get during the results download:

"Email","Verification Result","Verified At","Syntax Error","ISP","Role","Disposable","Trap"
"[email protected]","deliverable","2024-07-20T09:52:19.734Z","N","Y","N","N","N"
"[email protected]","deliverable","2024-07-20T09:52:19.409Z","N","Y","N","N","N"
"[email protected]","accept-all","2024-07-20T09:52:19.061Z","N","N","Y","N","N"

The success response you get when you delete your bulk validation list:

HTTP/1.1 200 OK
{
    "job_id": "e7sb72fbi3a93s4aitfayvardxa3qiqvffxy",
    "success": true,
    "message": "List will be deleted"
}

The success response you get when you fetch your credit balance:

HTTP/1.1 200 OK
{
    "success": true,
    "credits_info": {
        "credits_remaining": 100
    }
}

In the response, you’ll find the result parameter. This parameter will indicate the status of the email.

Understanding Results

Result Code	Description	Safe to send?
Deliverable	Valid email	Yes
Undeliverable	Not a valid email	No
Accept-all	Unverifiable	Maybe
Unknown	Unable to verify	Maybe

Valid
Email address exist and is accepting emails. This is confirmed by communicating via SMTP. These emails are valid and safe to send mail.

Invalid
Email address do not exist or is not accepting mails. Sending mails will result in bounce.

Accept-all
Accept-all, also known as 'Catch-all'. These addresses are not verifiable, as their mail server accepts both valid and invalid addresses. So we cannot definitively verify.

Unknown
We were unable to definitively verify these emails as their mail servers were not reachable during verification. Unknown addresses are checked multiple times from different locations with varying interval before arriving at this result.

Disposable
These are temporary email address and should not be mailed as there is a very high chance of email bouncing.

Error Response

400 BadRequest

The error response you get when your account is under review or restricted:

HTTP/1.1 400 BadRequest

{
    "result": "Verify restricted",
    "success": false
}

The error response you get when you provide the incorrect file format for bulk validation API:

HTTP/1.1 400 BadRequest

{
   "result": "Invalid file data",
   "success": false
}

The error response you get when the job not found for bulk validation:

HTTP/1.1 400 BadRequest

{
    "result": "Job not found.",
    "success": false
}

The error response you get when you passed the invalid job_id:

HTTP/1.1 400 BadRequest

{
    "result": "Job not found. Invalid jobId",
    "success": false
}

The response you get when you passed the incorrect filter result options for download bulk validation results:

HTTP/1.1 400 BadRequest

{
  "result": "Invalid filterResult. Please provide correct filterResult options",
  "success": false
}

The error response you get when you try to delete the list is still processing in the bulk validation:

HTTP/1.1 400 BadRequest

{
    "result": "List is being processed, and cannot be deleted.",
    "success": false
}

The error response you get when the list not found while deleting list in a bulk validation:

HTTP/1.1 400 BadRequest

{
    "result": "List not found, may be already deleted.",
    "success": false
}

401 Unauthorized

The error response you get when the API key you provided is not correct:

HTTP/1.1 401 Unauthorized

{
   "success":"false",
   "result":"Invalid API Key"
}

402 Payment Required

The error response you receive when your credits are exhausted

HTTP/1.1 402 Payment Required

{   
   "success":"false",
   "result":"Insufficient verification credits"
}

429 Too Many Requests

The error response you get when your call rate is high :

HTTP/ 429 Too Many Requests

{   
   "success":"false",
   "result":"Too many requests"
}