> ## Documentation Index > Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Core concepts > Tokens, security, and the mental model for how paperplane works. ## One transaction, no accounts paperplane has **no accounts, no API keys, and no subscription**. Every letter is an independent transaction, paid for individually with a Stripe link or a prepaid credit code. This keeps integration trivial and removes any provisioning step. This shapes everything about the API: you never authenticate a caller — you prove **ownership of a specific order** when doing something sensitive to it. ## The two kinds of signed tokens Because there are no accounts, sensitive actions are guarded by HMAC-signed tokens minted by the server. ### Confirmation tokens (`ppq_`) `POST /v1/quotes` or the `quote_letter` MCP tool. Free, creates nothing. The quote returns a `confirmation_token` bound to the exact recipient, content, class, and price. `POST /v1/orders` requires that token; any change invalidates it. Single-use, 30-minute TTL. This guarantees **a send is never the first call** — an agent must quote first, and cannot send a letter for content it never priced. ### Capability tokens (`ppc_`) Minted at order creation and returned under `capability`: | Token | Grants | Required by | | -------------- | ------------------------------------------------ | ------------------------------------------------- | | `cancel_token` | Cancel the order + release any payment hold | `DELETE /v1/orders/{id}` via `X-Capability-Token` | | `review_token` | Post a review attributed from the return address | `POST /v1/reviews` | Both are bound to the order id and the action, and expire after **7 days**. Possession of an order id alone is never enough for these actions. ## Order lifecycle ``` draft → pending_payment → screening → held_for_review ─┬─ allowed → submitted → mailed → delivered (payment) └─ refused → refunded ``` | State | You can | | ----------------- | -------------------------- | | `draft` | Cancel | | `pending_payment` | Cancel (releases hold) | | `screening` | Cancel | | `held_for_review` | Cancel | | `submitted` | Track. Too late to cancel. | | `mailed` | Track | | `delivered` | Review | | `refused` | Re-create the order | | `canceled` | — | | `failed` | Re-create the order | ## Mail formats `mail_class` (above) is the USPS *service level* — how a piece travels. A separate `format` field on `POST /v1/orders` (and, as of this page, on `quote_letter`/`send_letter` too — see [MCP](/docs/guides/mcp)) picks the physical *piece* itself, and defaults to `letter` so every existing integration is unaffected. | `format` | Price | What it is | | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `letter` (default) | from \$1.99 | Typed or uploaded, sealed envelope. The only format that can go `certified`/`priority`. | | `letter_windowed` | \$1.99 | Same sealed envelope, typed or uploaded, up to 12 pages — the address shows through a window instead of being printed separately. `first_class` only, same as the message-only formats below, but this one is NOT message-only: it takes the same `text`/PDF input as `letter`. | | `notecard` | \$5.99 | Folded card, message only — see below. Enclosed like a greeting card, not open-face. | | `postcard_4x6` | \$1.99 | Open-face postcard, message only — see below. | | `postcard_6x9` | \$2.99 | Larger postcard, same rules. | | `postcard_6x11` | \$3.49 | The biggest postcard. | Postcards and the notecard are **message-only today**: the `text` you send prints directly onto the piece in a real handwriting font — there's no custom photo or artwork side, and no PDF/upload path for either format. Printing and First-Class postage are both bundled into the flat price shown above, so an order for either one carries no separate USPS postage line. Both allow only `mail_class: "first_class"` — they cannot go certified, priority, or carry tracking; send a `letter` instead if you need proof of delivery. The difference between them is privacy: a postcard is open-face (readable by anyone who handles it in transit), while the notecard is folded and enclosed like an ordinary greeting card. ```json theme={null} { "mail_class": "first_class", "format": "postcard_4x6", "text": "Wish you were here! See you next week.", "to": { "name": "Sam Rivera", "line1": "12 Grove Ave", "city": "Richmond", "state": "VA", "zip": "23221" }, "from": { "name": "Alex Rivera", "line1": "1 Main St", "city": "Richmond", "state": "VA", "zip": "23220" } } ``` ```json theme={null} { "mail_class": "first_class", "format": "notecard", "text": "Happy birthday! Hope your day is a great one.", "to": { "name": "Sam Rivera", "line1": "12 Grove Ave", "city": "Richmond", "state": "VA", "zip": "23221" }, "from": { "name": "Alex Rivera", "line1": "1 Main St", "city": "Richmond", "state": "VA", "zip": "23220" } } ``` ## The error contract Every failure returns a machine-readable envelope: ```json theme={null} { "status": "failed", "code": "file_too_large", "reason": "PDF is 12.3MB; limit is 10MB", "next": ["Compress the PDF or split it into smaller documents."] } ``` * `code` — stable. Never parse the `reason` string. * `next` — the recovery playbook. An agent can act on it directly. ## Sandbox vs live [Sandbox mode](/docs/sandbox) runs the complete flow — rendering, screening, simulated fulfillment with tracking — instantly and free, with zero keys. The whole API is testable before a real card or real mail is involved. You never have to infer which mode a request ran in: it's the `sandbox` flag you passed, echoed back unambiguously on every order as `order.sandbox` (`true`/`false`), and sandbox order ids carry an `ord_test_` prefix instead of `ord_`. ## Glossary Postal and mail-industry terms used throughout this API (CASS certification, Certified Mail, the Intelligent Mail barcode (IMb), NCOALink, and more) are defined in the public [glossary](https://sendpaperplane.com/glossary) — the same terminology this documentation uses.