API Documentation

Getting started

The API answers at https://inboxvet.com/api. Every request is a JSON POST and every response is JSON.

Create a free account and buy credits on the pricing page. Each address checked uses one credit; credits never expire.
Create an API key under Dashboard → API keys.
Send it with each request, as below.

For lists bigger than a few thousand addresses, upload a CSV in the dashboard instead: bulk uploads check every address down to the mailbox and you can download the results when they are done.

Authentication

Send your key in the x-api-key header. Keep it secret: anyone with the key can spend your credits. Delete a key in the dashboard to revoke it immediately.

x-api-key: YOUR_API_KEY
Content-Type: application/json

Validate one email

Request

POST https://inboxvet.com/api/validate

{
  "email": "jane@example.com",
  "skipSMTP": false
}

Field	Type	Description
`email`	string	Required. The address to check.
`skipSMTP`	boolean	Optional, default `true`. With `true` the check stops after syntax, disposable-domain and MX tests (instant). Send `false` to also ask the mail server whether the mailbox exists and whether the domain is catch-all; this usually takes 1–10 seconds, up to 30.

Response 200

{
  "success": true,
  "result": {
    "email": "jane@example.com",
    "status": "VALID",
    "syntaxValid": true,
    "isDisposable": false,
    "mxRecordExists": true,
    "isCatchAll": false,
    "smtpValid": true,
    "reason": "Email is valid and deliverable"
  },
  "creditsRemaining": 4210
}

Validate a batch

Up to 1,000 addresses per request. Credits for the whole batch are taken up front and refunded if the request fails.

Request

POST https://inboxvet.com/api/validate/batch

{
  "emails": ["jane@example.com", "nobody@example.com"],
  "skipSMTP": false
}

Response 200

{
  "success": true,
  "results": [
    { "email": "jane@example.com", "status": "VALID", "reason": "Email is valid and deliverable", ... },
    { "email": "nobody@example.com", "status": "INVALID", "reason": "Mailbox does not exist", ... }
  ],
  "creditsRemaining": 4208
}

Each item in results has the same fields as result above, in the order you sent the addresses.

Result fields

Field	Type	Meaning
`email`	string	The address, lowercased and trimmed.
`status`	string	One of `VALID`, `INVALID`, `RISKY`, `UNKNOWN` (see below).
`syntaxValid`	boolean	The address is correctly formed.
`isDisposable`	boolean	The domain belongs to a throwaway-email service.
`mxRecordExists`	boolean	The domain has mail servers.
`isCatchAll`	boolean \| null	The domain accepts mail for any address. `null` when not checked.
`smtpValid`	boolean \| null	The mail server accepted the mailbox. `null` when not checked or no clear answer.
`reason`	string	A plain-English explanation of the status.

Statuses

Status	What it means	What to do
`VALID`	The address exists and accepts mail.	Send.
`INVALID`	Bad syntax, no mail servers, the mailbox does not exist, or it is full.	Remove it: mail to it bounces.
`RISKY`	A disposable address, or a catch-all domain that accepts every address so the mailbox cannot be confirmed.	Send with care, or segment.
`UNKNOWN`	The mail server did not give a clear answer (greylisting, timeouts, or it refused the check).	Try again later; don't treat it as invalid.

Errors

Errors return a JSON body with an error message. No credit is used when a request fails.

HTTP status	When
400	Missing `email` or `emails`, or more than 1,000 addresses in a batch.
401	No API key, or the key is not valid.
402	Not enough credits. Batch responses also include `required` and `available`.
403	The account is suspended. Contact support.
500	Something went wrong on our side. Retry, and contact support if it persists.

Code examples

cURL

curl -X POST https://inboxvet.com/api/validate \
  -H "x-api-key: $INBOXVET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "skipSMTP": false}'

JavaScript (Node 18+)

const response = await fetch("https://inboxvet.com/api/validate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.INBOXVET_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "jane@example.com", skipSMTP: false }),
})
const { result } = await response.json()
console.log(result.status, result.reason)

Python

import os, requests

response = requests.post(
    "https://inboxvet.com/api/validate",
    headers={"x-api-key": os.environ["INBOXVET_API_KEY"]},
    json={"email": "jane@example.com", "skipSMTP": False},
    timeout=40,
)
result = response.json()["result"]
print(result["status"], result["reason"])

PHP

$ch = curl_init("https://inboxvet.com/api/validate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 40,
    CURLOPT_HTTPHEADER => [
        "x-api-key: " . getenv("INBOXVET_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["email" => "jane@example.com", "skipSMTP" => false]),
]);
$result = json_decode(curl_exec($ch), true)["result"];
echo $result["status"];

Questions? Email support@inboxvet.com.