API — mbox.run

Authentication

Register to receive a key. Store it — a new key is shown once. Rotate from the dashboard if it leaks. If you lose the key, use Forgot your API key — we email a 30-minute link that issues a new key and turns the old one off. Signup is rate-limited per network (3/hour, 8/day).

POST /api/v1/auth/register
{ "email": "[email protected]" }

POST /api/v1/auth/recover
{ "email": "[email protected]" }

POST /api/v1/auth/recover/confirm
{ "token": "rec_…" }

GET /api/v1/me
Authorization: Bearer ev_live_…

Single verification

POST /api/v1/verify — pass include_country: true to receive a country code (2 credits when a country is actually returned).

curl -X POST "https://mbox.run/api/v1/verify" \
  -H "Authorization: Bearer ev_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","include_country":true}'

const res = await fetch("https://mbox.run/api/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[email protected]",
    include_country: true,
  }),
});
const { result, credits_charged, quota } = await res.json();

import requests

r = requests.post(
    f"https://mbox.run/api/v1/verify",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"email": "[email protected]", "include_country": True},
)
print(r.json()["result"], r.json()["credits_charged"])

Response

Top-level envelope plus a result object.

{
  "result": {
    "email": "[email protected]",
    "result": "valid",
    "detail": "",
    "source": "ctryISO_get",
    "country": "BR",
    "exists": true,
    "chargeable": true,
    "credits": 2
  },
  "credits_charged": 2,
  "quota": { "available": 98, "credits": 98 }
}

Field	Type	Meaning
`result.result`	string	`valid`, `invalid`, `risky`, `unknown`, `error`
`result.country`	string	ISO region when requested and available. Omitted or empty otherwise.
`result.chargeable`	bool	Whether this verdict can consume credits.
`credits_charged`	number	0, 1, or 2 for this call.
`quota.available`	number	Credits left after the call.

Billing rules

You only pay for a decision. Country is an add-on, not a surprise.

Verdict	Credits	With `include_country`
valid + country	1	2
valid / invalid, no country	1	1
unknown, error, risky	0	0

If country is requested but only 1 credit remains, the check still runs at 1 credit and country is stripped.

Bulk jobs

Start, poll, stop, list history. Pass include_country on start to enable the add-on for the whole job. JSON accounts is fine for small lists; for large files POST multipart field file (.csv / .txt / .tsv, max 64 MB, 1,000,000 unique). History accepts limit, offset, and optional status=done|stopped. One running job per account; list size is limited by credits, not a separate cap.

curl -X POST "https://mbox.run/api/v1/job/start" \
  -H "Authorization: Bearer ev_live_…" \
  -H "Content-Type: application/json" \
  -d '{"accounts":"[email protected]\[email protected]","include_country":true}'

# Large lists: upload the file. Do not put the whole list in JSON.
curl -X POST "https://mbox.run/api/v1/job/start" \
  -H "Authorization: Bearer ev_live_…" \
  -F "[email protected]" \
  -F "include_country=true" \
  -F "name=list.csv"

curl "https://mbox.run/api/v1/job/status" -H "Authorization: Bearer ev_live_…"
curl "https://mbox.run/api/v1/jobs?limit=20&offset=0&status=done" -H "Authorization: Bearer ev_live_…"

await fetch("https://mbox.run/api/v1/job/start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accounts: "[email protected]\\[email protected]",
    include_country: true,
  }),
});

const fd = new FormData();
fd.append("file", listFile); // File from input type=file
fd.append("include_country", "true");
await fetch("https://mbox.run/api/v1/job/start", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: fd,
});

const { status } = await fetch("https://mbox.run/api/v1/job/status", {
  headers: { Authorization: `Bearer ${API_KEY}` },
}).then((r) => r.json());
// status.credits_charged, status.top_countries, status.billed_1, status.billed_2

import requests

headers = {"Authorization": f"Bearer {API_KEY}"}
requests.post(
    f"https://mbox.run/api/v1/job/start",
    headers=headers,
    json={"accounts": "[email protected]\\[email protected]", "include_country": True},
)
with open("list.csv", "rb") as f:
    requests.post(
        "https://mbox.run/api/v1/job/start",
        headers=headers,
        files={"file": f},
        data={"include_country": "true", "name": "list.csv"},
    )
print(requests.get(f"https://mbox.run/api/v1/job/status", headers=headers).json())

Status field	Meaning
`credits_charged`	Total credits spent on this job so far
`billed_1` / `billed_2`	How many addresses billed at 1 vs 2 credits
`not_billed`	Error / risky / unknown
`top_countries`	Array of `{ "code", "count" }`, top 10

Downloads

Authenticated GET. Add ?job=JOB_ID for a past job.

GET /api/v1/job/download/Valid.txt
GET /api/v1/job/download/ValidCountry.txt?job=JOB_ID
GET /api/v1/job/download/Invalid.txt
GET /api/v1/job/download/Risky.txt
GET /api/v1/job/download/Errors.txt
GET /api/v1/job/download/Remaining.txt
GET /api/v1/job/download/Results.csv
GET /api/v1/job/download/Results.zip

Individual .txt files stay as the source of truth. Results.csv and Results.zip are extra exports. Empty categories are omitted. Remaining.txt is written on stop, out-of-credits, or an interrupted restart.

Credits

Signup grants 100 credits. Packs never expire. Checkout returns payment instructions; poll the order until credits apply.

GET  /api/v1/pricing
POST /api/v1/billing/checkout   { "pack_id": "p100k", "from_ccy": "USDTTRC" }
GET  /api/v1/billing/order?id=ORDER_ID

HTTP errors

Code	When
`401`	Missing or invalid API key
`402`	Not enough credits (`limit: …`)
`409`	A bulk job is already running on this account
`413`	Upload larger than 64 MB
`429`	Rate limit on signup, demo, checkout, or key rotate
`503`	Payments temporarily unavailable

API reference