# address.bot full API context

address.bot verifies that an address can receive mail. It sends a postcard with a private QR link and six-digit printed code. When the recipient confirms the code, address.bot updates the verification and sends a signed webhook if one is configured.

## Authentication

- Sandbox keys use the `sk_test_...` prefix.
- Live keys use the `sk_live_...` prefix.
- Send keys as `Authorization: Bearer <key>`.
- Sandbox and live use the same endpoints and request bodies.
- Sandbox responses include `test_mode: true` and `X-Test-Mode: true`; live responses include `test_mode: false`.

## Create a postcard verification

Endpoint: `POST /api/v1/verifications`

Request body:

```json
{
  "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"
  }
}
```

Use `dry_run: true` on this endpoint to validate and price the request without creating a record, sending mail, or charging. Use `Idempotency-Key` for safe retries. API responses never expose the private QR token or printed six-digit code.

## Preflight and live creation

Endpoint: `POST /api/v1/preflight`

Use preflight to validate the same JSON body and receive an estimated cost. For live creation, pass:

```text
x-addressbot-preflight-id: <preflight_id>
x-addressbot-confirm-live-cost: true
x-addressbot-max-cost-cents: 250
```

The max-cost header is a live safety cap. If the confirmed estimate exceeds it, no record is created and no charge is attempted. If billing, policy, or manual review is required, the API returns a structured action response instead of creating live mail.

## Sandbox testing

Endpoint: `POST /api/v1/verifications/{id}/simulate`

Use a sandbox key to mark a test verification delivered and queue the same webhook shape used when a real recipient confirms the postcard code.

## Webhooks

Webhook URLs are configured during setup. address.bot sends JSON events with:

- `x-addressbot-event`
- `x-addressbot-delivery`
- `x-addressbot-signature`

Signature format: `t=<timestamp>,v1=<hmac_hex>`. Verify by computing `HMAC-SHA256(webhook_secret, "<timestamp>.<raw_body>")`.

Common events:

- `verification.queued`
- `verification.printed`
- `verification.mailed`
- `verification.delivered`
- `verification.submitted`
- `verification.undeliverable`

Example webhook payload:

```json
{
  "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"
  }
}
```

## Discovery

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