# address.bot

> Postcard address verification API.
> Send a QR postcard, have the recipient enter the printed six-digit code, and receive a signed status update.

## Start here

- Docs: https://address.bot/docs
- OpenAPI JSON: https://address.bot/api/openapi.json
- Full LLM context: https://address.bot/llms-full.txt
- MCP descriptor: https://address.bot/mcp
- MCP server.json: https://address.bot/server.json

## Core flow

1. Use a sandbox key: `Authorization: Bearer sk_test_...`.
2. Validate and price the request with `POST /api/v1/preflight`, or send `dry_run: true` to `POST /api/v1/verifications`.
3. Create the postcard with `POST /api/v1/verifications`.
4. The recipient scans the QR and enters the printed code.
5. Read status with `GET /api/v1/verifications/{id}` or receive a webhook.

## Live mode

- Use `sk_live_...` only when you intend to send live mail.
- Live creates require `x-addressbot-preflight-id` and `x-addressbot-confirm-live-cost: true`.
- Add `x-addressbot-max-cost-cents` to reject before any record or charge if the estimate is too high.
- The API may stop for billing, policy, or review before any live postcard is created.

## Webhooks

- Configure a webhook URL during setup.
- Events include `verification.queued`, `verification.mailed`, `verification.delivered`, and `verification.submitted`.
- Verify `x-addressbot-signature` as HMAC-SHA256 over `<timestamp>.<raw_body>`.