Human docs

QR postcard verification for real addresses

This page is the human-readable guide. It explains how to price, create, simulate, and monitor postcard verification, while the machine surfaces stay compact and structured.

OpenAPI JSON MCP server.json

Which surface

Each endpoint has a different job

For humans

/docs

Use this page for signup, key flow, request examples, sandbox behavior, and webhook expectations.

For agents

/mcp

Use this for a compact tool catalog, auth semantics, webhook headers, and OpenAPI schema refs.

For discovery

/server.json

Use this for MCP discovery metadata only: remote URL, auth header shape, high-level capabilities, and links.

Sandbox

Same API, no live mail

Use sk_test_... for development. Sandbox requests return test_mode: true, include X-Test-Mode: true, and can be advanced with the simulate endpoint.

Live

Explicit cost confirmation

Use sk_live_... only when the owner intends to send real postcards. Live creates require a preflight id, x-addressbot-confirm-live-cost: true, and billing readiness.

QR postcard flow

From API request to verified mail access

Preflight

Validate address inputs and calculate the postcard estimate.

Create

Queue one QR postcard request for one recipient address.

Mail

The recipient receives a physical card with a QR and code.

Confirm

The QR page accepts the printed six-digit code.

Webhook

address.bot sends a signed status update to your app.

Request body

Dry run first, then create

POST/api/v1/verifications

Add dry_run: true to validate and price without creating a record, sending mail, or charging.

{
  "request_type": "address_confirmation",
  "recipient": {
    "name": "Jane Resident",
    "line1": "123 Main St",
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US"
  },
  "recipient_message": "Scan the QR and enter the code to confirm mail access.",
  "reference": "jane-main-mailbox",
  "metadata": {
    "customer_id": "cus_123"
  },
  "dry_run": true
}

LIVERequired headers

Live requests are rejected before side effects when the confirmed estimate exceeds your max-cost header.

Authorization: Bearer sk_live_...
Idempotency-Key: <stable_request_key>
x-addressbot-preflight-id: <preflight_id>
x-addressbot-confirm-live-cost: true
x-addressbot-max-cost-cents: 250

Endpoint reference

Small surface, production controls

POST/api/v1/preflightPreflight a postcard

Validate the same JSON body used for creation and persist a short-lived live cost estimate.

Returns preflight id, line items, estimated_total_cents, expiry, and confirmation status.

POST/api/v1/verificationsCreate a QR postcard verification

Creates one verification for one recipient address. Use dry_run for no-record pricing.

Returns a verification object. The private QR token and printed six-digit code are never exposed to the API caller.

GET/api/v1/verifications/{id}Read status

Fetch the lifecycle state for one postcard verification in the current key mode.

Treat delivered/submitted as recipient-confirmed states for the QR code workflow.

POST/api/v1/verifications/{id}/simulateSimulate sandbox confirmation

Sandbox-only. Marks a test verification delivered and queues the same signed webhook shape used by live confirmations.

Returns the updated test verification with test_mode: true.

GET/api/v1/billing/summaryCheck live readiness

Read billing state, live approval, per-request cap, and monthly budget for the current key.

Use this before enabling live sends in an agent workflow or customer dashboard.

Discovery

OpenAPI, MCP, server.json, and LLM context line up

OpenAPI 3.1

Runtime-aligned JSON schema for REST clients and SDK generation.

/api/openapi.jsonMCP descriptor

REST-backed tool catalog for agents that can bridge to HTTP APIs.

/mcpserver.json

MCP server discovery with auth headers and address.bot links.

/server.jsonllms.txt

Short integration context for LLMs and agents.

/llms.txtllms-full.txt

Full API context with webhook, sandbox, and live-safety details.

/llms-full.txt

Webhooks

Signed events when the code is confirmed

Configure a webhook URL during setup. Every delivery includes x-addressbot-signature, x-addressbot-event, and x-addressbot-delivery.

verification.queuedverification.printedverification.mailedverification.deliveredverification.submittedverification.undeliverable

POSTyour webhook URL

{
  "event": "verification.delivered",
  "created": 1770000000,
  "test_mode": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "mode": "test",
    "test_mode": true,
    "status": "delivered",
    "request_type": "address_confirmation",
    "submission_status": "submitted",
    "reference": "jane-main-mailbox",
    "recipient": {
      "name": "Jane Resident",
      "line1": "123 Main St",
      "line2": null,
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US"
    },
    "metadata": {
      "customer_id": "cus_123"
    },
    "estimated_cost_cents": 225,
    "created_at": "2026-05-21T12:00:00.000Z",
    "delivered_at": "2026-05-21T12:05:00.000Z",
    "completed_at": "2026-05-21T12:05:00.000Z"
  }
}

Safety model

What address.bot proves

address.bot verifies that someone can receive a postcard at the submitted address and complete the QR-code challenge. It is not a legal identity, residency, or ownership determination.