API documentation

Base URL: https://api.inboxpolicy.com · Auth: x-api-key: ip_live_... header, or pay per call with x402.

Updated 2026-07-03 · llms.txt

Quickstart

curl -X POST https://api.inboxpolicy.com/v1/decide \
  -H "x-api-key: ip_live_..." \
  -H "content-type: application/json" \
  -d '{"email": "someone@example.com"}'

POST /v1/decide

Decision-shaped verification: always answers with one action — send, send_with_caution, review, retry_later, or avoid — plus reason, confidence, signals, and cost. Malformed emails return avoid at no charge instead of an error.

{
  "request_id": "vrf_...",
  "action": "send",
  "reason": "Verified mailbox with acceptable risk.",
  "confidence": 95,
  "status": "valid",
  "signals": { "catch_all": false, "disposable": false, "free": false, "role_account": false },
  "from_cache": false,
  "cost": { "credits": 1, "billable": true }
}

POST /v1/verify

Full verification detail: status, deliverability and reachability flags, catch-all/disposable/role signals, MX context, confidence, recommended action, and SMTP evidence. Malformed input returns 422. Same request body as /v1/decide: {"email", "strictness?", "force_refresh?"} with strictness one of aggressive | default | strict.

Batches

POST /v1/batches/verify

Async verification for up to 50,000 emails: {"emails": [...], "strictness?", "webhook_url?"}. Returns 202 with a batch_id, worst-case credit estimate, and a webhook_secret when a webhook URL was given (completion webhooks are signed x-inboxpolicy-signature: HMAC-SHA256(secret, body)). Duplicate emails are deduplicated internally and billed once.

GET /v1/batches/:batchId

Status and summary counts: total_items, processed_items, valid/invalid/unknown/error counts, timestamps.

GET /v1/batches/:batchId/items

Per-email results, paginated: ?status=queued|processing|completed|failed&limit=100&offset=0.

GET /v1/batches

Your recent batch jobs, newest first.

Usage & account

GET /v1/usage — remaining credits, month-to-date spend and request counts. GET /v1/requests — recent verification activity. POST /v1/estimate — credit estimate before an operation: {"operation": "verify_email|verify_batch|send_decision", "count": n}.

Billing rules

• 1 credit = 1 fresh verification (verify, decide, or batch item — same price).
• Free: cache hits within 72 hours (from_cache: true), malformed-input rejections, idempotent replays.
• Insufficient balance returns 402. Credit checks are atomic — concurrent requests cannot overdraw.
• Unknown verdicts may escalate automatically to a wholesale fallback verifier at no extra charge; evidence discloses the chain.

Idempotency

Send an idempotency-key header on /v1/verify or /v1/decide. Exactly one concurrent request executes; others replay the stored response or receive 409 while it is in flight. Reusing a key with a different payload returns 409. A crashed owner releases the key after ~5 minutes.

MCP server (agents)

Remote MCP over Streamable HTTP. Tools: decide_send, verify_email, estimate_credits, create_verify_batch, get_batch_status, get_batch_items, get_usage.

{
  "mcpServers": {
    "inboxpolicy": {
      "url": "https://mcp.inboxpolicy.com",
      "headers": { "x-api-key": "ip_live_..." }
    }
  }
}

x402 pay-per-call

No account needed: keyless requests to /v1/decide or /v1/verify return 402 with an x402 v1 challenge ($0.01 per call, USDC on Base). Retry with an X-PAYMENT header; the settlement receipt returns in X-PAYMENT-RESPONSE. Credit packs are cheaper for volume ($0.005/check).

Errors & limits