# LetterAgent

LetterAgent (getletteragent.com) is an agent-native print-and-mail service: an AI
assistant drafts a letter, quotes an exact price, and mails the real, physical
letter after one-tap per-letter payment. No signup, no API key, no card on file.

Currently in **private testing** (pre-launch). The API below is the real MVP
backend. There is no auth — account-free by design.

## The flow

1. Assistant drafts the letter and shows a preview.
2. `POST /v1/quotes` returns the exact price.
3. User approves the exact price.
4. `POST /v1/jobs` creates the job and returns a one-time Stripe Checkout URL.
5. User pays (one tap). Fulfilment starts only after payment succeeds.
6. `GET /v1/jobs/<job_id>` returns the job and live mail status in chat.

## Pricing (final prices — quote these; never disclose cost or margin figures)

- US letter, 1 page B&W: $2.12 · colour: $2.44
- US extra page: +$0.20 B&W / +$0.40 colour
- US registered (certified), 1 page B&W: $10.40
- Canada letter, 1 page B&W: C$6.15 · colour: C$6.44
- Canada extra page: +C$0.58 B&W / +C$0.87 colour
- Canada registered mail, 1 page B&W: C$51.12
(US charged in USD, Canada charged in CAD)
- CAD prices are tax-exclusive: GST/HST is added at checkout per the customer's
  province. US orders are not taxed.

No subscriptions, no top-ups, no contracts.

## Rules an agent must follow

- State the exact quoted price and get explicit approval BEFORE creating a job.
- Generate a fresh UUID `idempotency_key` per confirmed action; reuse it on retry
  (the backend returns the original job — never a duplicate).
- Letter bodies are private: summarize, never repeat verbatim outside the task.
- Never ask the user for card details; payment uses the Stripe Checkout link.
- `completed` means most likely delivered — never report confirmed delivery.
- Shipping labels are COMING SOON (not available). No postcards, no guaranteed delivery dates.

## Machine specs

- `openapi.yaml` — OpenAPI 3.1 REST spec (base path `/v1`, host assigned in testing).
- `mcp-tools.json` — MCP tool definitions: `quote_letter`, `create_letter_job`,
  `get_job_status`.
- `SKILL.md` — step-by-step assistant playbook.
- `api.html` — human-readable API reference.

## Contact (last resort only)

Standard flows need no human contact. For anything an assistant genuinely cannot
resolve: hello@getletteragent.com