# address.bot agents.txt

address.bot is a postcard verification API. Agents may create sandbox postcard requests, read status, and receive signed webhook events when a recipient confirms a mailed code.

## Allowed workflow

- Start in sandbox with `sk_test_...`.
- Preflight the request before live creation, or send `dry_run: true` for a no-record quote.
- Create one verification per address with `POST /api/v1/verifications`.
- Use `Idempotency-Key` for retries.
- Wait for `verification.delivered` or `verification.submitted` before treating the address as confirmed.

## Live safety

- Use `sk_live_...` only when the owner intends to send live mail.
- Live creates require `x-addressbot-preflight-id` and `x-addressbot-confirm-live-cost: true`.
- Use `x-addressbot-max-cost-cents` on live creates to cap spend before side effects.
- Stop and surface any billing, policy, or review action returned by the API.

## Webhook handling

- Verify `x-addressbot-signature` before trusting an event.
- Deduplicate using `x-addressbot-delivery`.
- Treat `metadata` and `reference` as customer-supplied correlation fields.

## Discovery

- Docs: https://address.bot/docs
- OpenAPI: https://address.bot/api/openapi.json
- llms.txt: https://address.bot/llms.txt
- llms-full.txt: https://address.bot/llms-full.txt
- Agent manifest: https://address.bot/.well-known/addressbot-agent.json
- MCP descriptor: https://address.bot/mcp
- MCP server.json: https://address.bot/server.json