> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inboxfound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a key, verify one address and read the result.

**1. Create an API key**

Sign in at [inboxfound.com/app/keys](https://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.

**2. Submit a verification**

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

```bash cURL theme={null}
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:

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

**3. Poll the job**

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

```bash cURL theme={null}
curl https://inboxfound.com/api/v1/jobs/3f6b1c2e-8d47-4a0b-9e21-6c5d4b3a2f10 \
  -H "Authorization: Bearer $INBOXFOUND_KEY"
```

```json theme={null}
{
  "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

```javascript Node.js theme={null}
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);
```

```python Python theme={null}
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"])
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.