Quickstart

Create an API key

Sign in at inboxfound.com/app/keys and create a key. It is shown once; store it in your server environment. Keys are scoped to find, verify or both.

Submit a verification

Send the address with an Idempotency-Key. Any unique string works; a UUID is easiest.

cURL

curl -X POST https://inboxfound.com/api/v1/verify \
  -H "Authorization: Bearer $INBOXFOUND_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email":"r.okafor@example.com"}'

You get a 202 with a job:

{
  "id": "3f6b1c2e-8d47-4a0b-9e21-6c5d4b3a2f10",
  "operation": "verify",
  "execution_state": "queued",
  "billing": "reserved",
  "charged_micros": 0,
  "rate_micros": 2000,
  "result": null
}

Poll the job

Read it every few seconds until execution_state is complete or incomplete. Reading is free.

cURL

curl https://inboxfound.com/api/v1/jobs/3f6b1c2e-8d47-4a0b-9e21-6c5d4b3a2f10 \
  -H "Authorization: Bearer $INBOXFOUND_KEY"

{
  "id": "3f6b1c2e-8d47-4a0b-9e21-6c5d4b3a2f10",
  "operation": "verify",
  "execution_state": "complete",
  "billing": "charged",
  "charged_micros": 2000,
  "rate_micros": 2000,
  "result": {
    "operation": "verify",
    "email": "r.okafor@example.com",
    "status": "valid",
    "reason": "recipient_accepted",
    "provider": "google",
    "domain": "example.com",
    "catch_all": false,
    "role": false,
    "free": false,
    "disposable": false,
    "retryable": false,
    "checked_at": "2026-09-14T10:02:41.000Z"
  }
}

The same thing in code

const BASE = "https://inboxfound.com";
const headers = {
  Authorization: `Bearer ${process.env.INBOXFOUND_KEY}`,
  "Content-Type": "application/json",
};

let job = await fetch(`${BASE}/api/v1/verify`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ email: "r.okafor@example.com" }),
}).then((r) => r.json());

while (!["complete", "incomplete"].includes(job.execution_state)) {
  await new Promise((r) => setTimeout(r, 3000));
  job = await fetch(`${BASE}/api/v1/jobs/${job.id}`, { headers }).then((r) => r.json());
}

console.log(job.result.status, job.result.provider);

import os, time, uuid, requests

BASE = "https://inboxfound.com"
headers = {"Authorization": f"Bearer {os.environ['INBOXFOUND_KEY']}"}

job = requests.post(
    f"{BASE}/api/v1/verify",
    headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
    json={"email": "r.okafor@example.com"},
).json()

while job["execution_state"] not in ("complete", "incomplete"):
    time.sleep(3)
    job = requests.get(f"{BASE}/api/v1/jobs/{job['id']}", headers=headers).json()

print(job["result"]["status"], job["result"]["provider"])

Finding an address works the same way with POST /api/v1/find and a body of {"name": "Rachel Okafor", "domain": "example.com"}.

Get started

Concepts

Reference

The same thing in code

​The same thing in code

The same thing in code