API Reference

The InboxValid REST API lets you verify emails, audit domain deliverability and run bulk jobs from your own code. Every endpoint returns JSON and is authenticated with an API key. New to the product? Start with the product guide.

Authentication

Create an API key from the API page in the dashboard. The full key (starting with iv_live_) is shown once at creation, so store it securely. Pass it as a bearer token on every request:

Authorization: Bearer iv_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

The base URL is https://api.inboxinsights.in. Requests without a valid key return 401 with { "error": "invalid api key" }.

Credits & errors

Verification is metered in credits: 1 credit per single verify, 1 per email in a bulk job (held upfront, unused credits refunded) and 5 per deliverability audit. New accounts start with 1,000 free credits.

Errors always have the shape { "error": "message" }:

Verify an email

Runs a live check on a single address: syntax, MX lookup and an SMTP conversation with the receiving server, plus catch-all, disposable, role-account and free-provider detection. Costs 1 credit.

curl -X POST https://api.inboxinsights.in/v1/verify \
  -H "Authorization: Bearer iv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "sara@acmecorp.com"}'

{
  "email": "sara@acmecorp.com",
  "domain": "acmecorp.com",
  "status": "valid",
  "sub_status": null,
  "risk_score": 12,
  "mx_found": true,
  "mx_host": "aspmx.l.google.com",
  "provider": "Gmail",
  "is_role": false,
  "is_disposable": false,
  "is_catch_all": false,
  "free": false
}

status is one of:

sub_status adds detail when available (for example mailbox_not_found or mailbox_full), and risk_score is 0 to 100, lower is safer.

Deliverability audit

Grades a sending domain across 8 checks: MX, SPF, DKIM, DMARC, PTR, DNSBL listing, MTA-STS and BIMI, and tells you whether it passes the Gmail, Yahoo and Microsoft bulk-sender rules. Costs 5 credits.

curl -X POST https://api.inboxinsights.in/v1/deliverability \
  -H "Authorization: Bearer iv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "acmecorp.com"}'

{
  "domain": "acmecorp.com",
  "score": 85,
  "grade": "A",
  "passes_bulk_rules": true,
  "provider": "Gmail",
  "checks": {
    "spf":   { "state": "pass", "detail": "SPF record found: v=spf1 ...", "recommendation": null },
    "dkim":  { "state": "pass", "detail": "DKIM selectors found", "recommendation": null },
    "dmarc": { "state": "pass", "detail": "DMARC policy: reject", "recommendation": null },
    "mx":    { "state": "pass", "detail": "MX records: aspmx.l.google.com (10)" },
    "ptr":   { "state": "warn", "detail": "PTR record not found for sending IP",
               "recommendation": "Configure reverse DNS on your sending IP" },
    "dnsbl":   { "state": "pass", "detail": "Not listed on common blocklists" },
    "mta_sts": { "state": "warn", "detail": "No MTA-STS policy" },
    "bimi":    { "state": "warn", "detail": "No BIMI record" }
  }
}

Each check is pass, warn or fail, with a human-readable detail and a fix recommendation where one applies.

Bulk jobs

Verifies up to 50,000 emails per job. The list is de-duplicated automatically and credits are held upfront, 1 per email; anything unused is refunded when the job settles.

curl -X POST https://api.inboxinsights.in/v1/jobs/bulk \
  -H "Authorization: Bearer iv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 leads", "emails": ["a@acme.com", "b@example.org"]}'

{ "id": "job_cuid", "total": 2, "status": "queued" }

To carry extra columns (e.g. name, company) through to your results and CSV export, send rows instead of emails, plus metaColumns listing the keys to include:

curl -X POST https://api.inboxinsights.in/v1/jobs/bulk \
  -H "Authorization: Bearer iv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 leads",
    "metaColumns": ["first_name", "company"],
    "rows": [
      {"email": "a@acme.com", "meta": {"first_name": "Ada", "company": "Acme"}},
      {"email": "b@example.org", "meta": {"first_name": "Ben", "company": "Example"}}
    ]
  }'

For large lists, upload the file itself (multipart) instead of a JSON body, the server streams it, so jobs can reach the configured maximum (far above the inline ~50k body limit). Send the file plus optional name, emailColumn (header name; omit for a plain .txt list) and metaColumns (JSON array of headers to keep) as form fields. The server counts the rows, holds the credits, and queues verification; the response includes the record total.

curl -X POST https://api.inboxinsights.in/v1/jobs/upload \
  -H "Authorization: Bearer iv_live_..." \
  -F "name=Q3 leads" \
  -F "emailColumn=email" \
  -F 'metaColumns=["first_name","company"]' \
  -F "file=@leads.csv"

{ "id": "job_cuid", "status": "queued", "total": 1500 }

To check the count and credit cost before committing, add -F "preflight=true". The job is created as pending and the response adds cost, balance and sufficient; nothing is charged until you POST /v1/jobs/{id}/confirm.

{ "id": "job_cuid", "status": "pending", "total": 1500,
  "cost": 1500, "balance": 5000, "sufficient": true }

Returns the job with live counters:

{
  "id": "job_cuid",
  "name": "Q3 leads",
  "status": "running",
  "total": 2000,
  "processed": 1250,
  "valid": 980, "invalid": 170, "risky": 40,
  "catchAll": 35, "unknown": 20, "disposable": 5,
  "createdAt": "2026-06-12T09:00:00.000Z",
  "finishedAt": null
}

GET /v1/jobs lists your jobs, newest first. Supports take (max 100, default 100) and skip for pagination, and returns a total count alongside the jobs array.

Pages through per-email results. Supports ?status=valid|invalid|risky|catch_all|unknown|disposable, q (case-insensitive email search), take (max 1000, default 200) and skip for pagination. The response includes a total count of matching rows.

curl "https://api.inboxinsights.in/v1/jobs/job_cuid/results?status=valid&take=500" \
  -H "Authorization: Bearer iv_live_..."

Downloads the full results as a CSV file (columns: email, domain, status, sub_status, risk_score, provider, is_catch_all, is_role, is_disposable, free). Add ?status=valid to export only one status, for example your cleaned send-ready list.

curl -OJ "https://api.inboxinsights.in/v1/jobs/job_cuid/export?status=valid" \
  -H "Authorization: Bearer iv_live_..."

A Server-Sent Events stream of live progress. Each message is a JSON snapshot of the counters above; the stream closes when the job completes or fails.

data: {"processed": 1250, "total": 2000, "status": "running", "valid": 980, ...}
data: {"processed": 2000, "total": 2000, "status": "completed", ...}

Account & usage

Returns your organization, plan and current credit balance.

{
  "creditBalance": 950,
  "creditsUsed": 50,
  "emailsVerified": 50,
  "jobsRun": 1,
  "deliverabilityAudits": 0
}

The append-only credit ledger: grants, charges and refunds with the balance after each movement.

The audit trail of everything done on the account, via dashboard or API key. Filter with ?action=verify and page with take (max 500).