API documentation

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

Updated 2026-07-12 · llms.txt

Quickstart: make one paid request in five minutes

Prerequisites: bring an EVM wallet funded with USDC on Base and an x402 v2 client. No account or API key is required. The optional X-InboxPolicy-Payer header asks for that wallet's rolling 30-day usage rate; the server binds the short-lived quote to the same wallet that signs. The client preserves the quote extension, signs it, retries with PAYMENT-SIGNATURE, and returns the paid decision.

import { x402Client } from "@x402/core/client";
import { encodePaymentSignatureHeader } from "@x402/core/http";
import { toClientEvmSigner } from "@x402/evm";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.WALLET_KEY);
const publicClient = createPublicClient({ chain: base, transport: http() });
const x402 = new x402Client();
registerExactEvmScheme(x402, {
  signer: toClientEvmSigner(account, publicClient),
  networks: ["eip155:8453"]
});

const request = {
  method: "POST",
  headers: { "content-type": "application/json", "X-InboxPolicy-Payer": account.address },
  body: JSON.stringify({ email: "[email protected]" })
};
let res = await fetch("https://api.inboxpolicy.com/v1/decide", request);
if (res.status === 402) {
  const payment = await x402.createPaymentPayload(await res.json());
  res = await fetch("https://api.inboxpolicy.com/v1/decide", {
    ...request,
    headers: { ...request.headers, "PAYMENT-SIGNATURE": encodePaymentSignatureHeader(payment) }
  });
}
console.log(await res.json()); // { action: "send", confidence: 95, ... }

Wallet usage rates: the standard single-call rate is $0.01. A wallet receives 20% off the current single or batch base quote after 1,000 settled units in the prior 30 days and 40% off after 10,000. Omit X-InboxPolicy-Payer to use the standard quote.

Prefer an API key? Buy a prepaid credit pack (card checkout) — your key arrives by email. With a key, send x-api-key instead of paying per call:

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: for a schema-valid request body, answers with one action — send, send_with_caution, review, retry_later, or avoid — plus reason, confidence, signals, and cost. A syntactically invalid email string in a schema-valid body returns avoid at no charge; schema-invalid bodies can fail validation. Unknown addresses resolve to review; catch-all addresses resolve to review by default or send_with_caution under aggressive strictness — see how to handle catch-all email addresses, or browse the send-decision benchmark for 40 worked input-to-decision scenarios.

{
  "request_id": "vrf_...",
  "action": "send",
  "reason": "The mail server accepted this mailbox and refuses unknown ones.",
  "reason_code": "mailbox_exists",
  "confidence": 95,
  "status": "valid",
  "mail_provider": "google",
  "did_you_mean": null,
  "signals": { "catch_all": false, "disposable": false, "free": false, "role_account": false },
  "from_cache": false,
  "cost": { "credits": 1, "billable": true }
}

reason is a sentence for people; reason_code is the same cause as a stable value for code. See reason codes.

POST /v1/verify

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

{
  "request_id": "vrf_...",
  "email": "[email protected]",
  "status": "invalid",
  "reason": "mailbox_not_found",
  "deliverable": false,
  "catch_all": false,
  "disposable": false,
  "free": false,
  "role_account": false,
  "confidence": 97,
  "mail_provider": "microsoft_365",
  "esg_provider": null,
  "mx_hosts": ["example-com.mail.protection.outlook.com"],
  "did_you_mean": null,
  "recommended_action": "avoid",
  "note": "The mail server says this mailbox does not exist.",
  "evidence": {
    "provider": "smtp_local",
    "from_cache": false,
    "smtp": { "mx_host": "example-com.mail.protection.outlook.com", "stage": "rcpt", "code": 550, "enhanced_code": "5.4.1" }
  },
  "cost": { "credits": 1, "billable": true }
}

On /v1/verify, reason is the reason code and note is the sentence. evidence.smtp is the mail server's own reply to our check: the stage we reached, its three-digit code and its enhanced status code. It is present when a live SMTP check decided the result.

Reason codes

Every result says why. A refusal aimed at us (a block or a rate limit) is never reported as an invalid mailbox.

CodeStatusMeaningBilled
mailbox_existsvalidThe mail server accepted this mailbox. Confidence is 95 when it also refuses unknown mailboxes, and 65 when that could not be checked.Yes
mailbox_not_foundinvalidThe mail server says the mailbox does not exist.Yes
mailbox_disabledinvalidThe mailbox exists but is disabled.Yes
null_mx, domain_not_found, no_mail_routeinvalidThe domain cannot receive email at all. Answered from DNS.Yes
catch_allunknownThe domain accepts mail for any address, so this mailbox cannot be confirmed.Yes
disposableunknownA throwaway-address provider. The action is avoid. See what the API returns for a disposable address.Yes
provider_unverifiableunknownThe provider (Yahoo) accepts every address at this stage, so SMTP cannot confirm the mailbox.No
probe_blockedunknownThe mail server refused our verification request for policy reasons. The mailbox was not checked.No
probe_deferredunknownThe mail server is rate-limiting verification requests. Not cached; try again in a few minutes.No
smtp_unreachable, smtp_rejected, unverifiableunknownThe mail server could not be reached, or refused without a usable reason.No
greylistedtemporary_unavailableThe server asked us to come back later. recommended_retry_at says when.No
mailbox_fulltemporary_unavailableThe mailbox exists but is full; mail would bounce until space is freed.No
syntax_errorsyntax_errorNot a valid address. Rejected before any lookup.No

mail_provider names who hosts the mailbox, from the domain's MX records: google, microsoft_365, microsoft_consumer, yahoo, icloud, proton, zoho, fastmail and others, or other. When a security gateway sits in front (proofpoint, mimecast, barracuda, cisco), esg_provider names it too. did_you_mean suggests a correction when an address fails and its domain is one edit away from a major provider, for example [email protected] → [email protected]. Results cached before 11 November 2026 may lack these fields for up to 72 hours.

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.

Batches via x402 (keyless)

The same endpoint also accepts x402 payment — no account or key needed. The x402 path caps at 5,000 emails per call (the API-key path keeps its 50,000 cap). Without a PAYMENT-SIGNATURE header the API replies 402 with a PAYMENT-REQUIRED quote for emails × the per-email bulk rate, in USDC; a v2 x402 client reads the quote, signs, and retries automatically.

curl -i -X POST https://api.inboxpolicy.com/v1/batches/verify \
  -H "content-type: application/json" \
  -d '{"emails": ["a@x.com", "b@y.com"], "strictness": "default"}'
# 402 Payment Required — quotes total = emails x per-email bulk rate, in USDC

Once payment settles, the same call returns 202:

{
  "batch_id": "bat_...",
  "status": "queued",
  "total_items": 2,
  "amount_usd": 0.02,
  "access_token": "btok_..."
}

Poll keylessly with that token: GET /v1/batches/:batchId and GET /v1/batches/:batchId/items with header x-batch-access-token: btok_... — same response shapes as the API-key path. webhook_url works the same way. For bigger lists, chunk client-side and submit multiple calls; each payment covers exactly the emails submitted in that call, and duplicates and unresolved items within a call are charged as submitted.

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

Idempotency

For authenticated API-key calls, send an idempotency-key header on /v1/verify or /v1/decide. Keyless x402 bypasses this wrapper; after indeterminate settlement, do not submit a second payment. 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. The MCP guide lists each tool's inputs, output and cost.

Keyless agents can pay per call at https://mcp.inboxpolicy.com/x402 for decide_send and verify_email only. Send payment in _meta["x402/payment"]; the receipt returns in _meta["x402/payment-response"]. Prices match /v1/decide and /v1/verify.

Connect from Claude

In Claude, open Customize → Connectors → Add → Add custom connector and enter https://mcp.inboxpolicy.com. Click Connect, then paste your API key on the InboxPolicy sign-in page at mcp.inboxpolicy.com and choose Approve. Claude receives an encrypted access token that lasts 30 days, never your key in plain text. Every call re-checks the key, so a revoked key stops working at once. Each email check costs 1 credit from your balance; re-checks within 72 hours, unresolved checks and malformed addresses are free.

Other MCP clients

Clients that support custom headers can send the key directly:

{
  "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 v2 PAYMENT-REQUIRED challenge (standard rate $0.01 per call, USDC on Base). Send X-InboxPolicy-Payer to receive a wallet-bound rolling-usage quote: 20% off after 1,000 settled units in 30 days and 40% off after 10,000. Retry with a PAYMENT-SIGNATURE header; the settlement receipt returns in PAYMENT-RESPONSE. Credit packs provide fixed card pack pricing ($3.16–$5.00 per 1,000); model your own list with the cost calculator. Batches accept x402 too — one payment per call, up to 5,000 emails, with the earned percentage applied to the current per-email base quote.

Errors & limits

CodeMeaning
400Validation failure (body includes an issues array)
401Missing or invalid API key
402Insufficient credits, or x402 payment required (keyless)
404Unknown batch ID
409Idempotency conflict or in-flight duplicate
422Email failed syntax validation (verify only)
429Rate limited (default 10 req/s per key)