# MailPulse API — Pricing

MailPulse sends real physical letters via x402 pay-per-call (USDC on Base). Unlike a data API,
this is a **quote → confirm → execute** flow: quoting is free, sending is paid, and once a
letter is accepted for print it cannot be refunded (see [/terms.html](/terms.html)).

| Endpoint | What it does | Price/call |
|---|---|---|
| `POST /api/quote` | Price + signed quote_id for a letter — no Lob call, no charge | **Free** |
| `POST /api/verify-address` | Deliverability check (Lob US/international verification) | $0.01 |
| `GET /api/letters/{id}` | Status / USPS tracking poll for a previously sent letter | $0.005 |
| `POST /api/letters` | **Send the letter** — the paid action, price depends on service | see below |

## Letter pricing (flat per piece, 1–6 pages, no per-page charge in v1)

| Service | What it is | Price |
|---|---|---|
| `standard` | US First-Class letter | **$3.00** |
| `certified` | US Certified Mail (USPS tracking) | **$12.00** |
| `certified_return_receipt` | US Certified Mail + electronic return receipt (signature proof) | **$14.00** |
| `international` | First-Class international letter (240+ countries) | **$5.00** |

Prices are all-in: Lob's print, envelope, and postage costs (including the USPS certified-mail
and return-receipt surcharges) plus a flat processing margin. There is no subscription, no
per-month minimum, and no volume commitment — you pay exactly for the letters you send.

**Hard cap:** every order is capped at **$25.00** total, enforced server-side before payment is
ever requested. This is a safety rail (`MAX_ORDER_USD`), not a purchasable tier.

## How payment works

1. `POST /api/quote` (free) — submit `to`, `from`, `content`, `service`. Get back an exact price,
   a signed `quote_id`, and a 15-minute expiry.
2. `POST /api/letters` (paid, x402) — resubmit the same order plus the `quote_id`/`issued_at`
   from step 1, a `client_request_id` (for idempotency), and pay the exact price quoted. Lob
   prints and mails the letter; you get back a Lob letter id, expected delivery date, and (for
   certified mail) a tracking number.
3. `GET /api/letters/{id}` ($0.005) — optional status/tracking poll any time after sending.

- Machine-readable spec: [/openapi.json](/openapi.json) · agent card: [/.well-known/agent.json](/.well-known/agent.json) · [/llms.txt](/llms.txt)
- Terms (accepted by paying): [/terms.html](/terms.html)
- Part of [PulseNetwork](https://pulse.theaslangroupllc.com) — The Aslan Group LLC · info@theaslangroupllc.com