---
agentTools:
  projectIndex: https://validto.readme.io/llms.txt
---

# 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:

```json Success Response
HTTP/1.1 200 OK

{
    "result": "deliverable",
    "message": "This address can receive emails.",    
    "email": "support@validto.com",
    "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:

```json Success Response
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:

```json Success Response
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:

```json Success Response
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:

```text Success Response
"Email","Verification Result","Verified At","Syntax Error","ISP","Role","Disposable","Trap"
"marketing@example.com","deliverable","2024-07-20T09:52:19.734Z","N","Y","N","N","N"
"sales@example.com","deliverable","2024-07-20T09:52:19.409Z","N","Y","N","N","N"
"support@example.in","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:

```json Success Response
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:

```json Success Response
HTTP/1.1 200 OK
{
    "success": true,
    "credits_info": {
        "credits_remaining": 100
    }
}
```

<br />

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:

```json Error Response
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:

```json Error Response
HTTP/1.1 400 BadRequest

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

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

```json Error Response
HTTP/1.1 400 BadRequest

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

The error response you get when you passed the invalid job\_id:

```json Error Response
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:

```json Error Response
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:

```json Error Response
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:

```json Error Response
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:

```json Error Response
HTTP/1.1 401 Unauthorized

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

### 402 Payment Required

The error response you receive when your credits are exhausted

```json Error Response
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 :

```json Error Response
HTTP/ 429 Too Many Requests

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