Skip to main content
Whatever surface you send from — API, MCP, the web composer, an embed widget, a CSV bulk import, or a forwarded email — every letter moves through the same four phases. This page is the map. Each phase links to the guide that covers it in depth; nothing below duplicates that detail. Order states in order: pending_payment, screening, held_for_review (only if flagged), submitted, mailed, delivered. Before submitted an order can end as canceled, held_for_review can end as refused, and submitted can end as failed. Order states in order: pending_payment, screening, held_for_review (only if flagged), submitted, mailed, delivered. Before submitted an order can end as canceled, held_for_review can end as refused, and submitted can end as failed. See the error contract’s lifecycle table for the full state-by-state breakdown.

​
Compose

Assemble a recipient and content into something ready to price. There’s no order yet — nothing here costs anything or touches USPS. Content can come from raw text or a pdf_url on the API, the composer at /send, a template pre-filled from the gallery, an embedded widget on someone else’s site, a row from a CSV import, a forwarded email, or a text (SMS) conversation.
  • Endpoint — none required yet; GET /v1/address/autocomplete helps fill in the recipient as they type (see Addresses).
  • UI surfaces — the /send composer, template-embed.js / paperplane.js, the CSV mapper (POST /v1/csv-map).
Go deeper: Letter templates · Embed the send flow · Bulk sending · Send by email · Send by text

​
Proof

Confirm what will actually print and what it will cost — before any money moves. Two things happen here, together:
  1. See the exact PDF. The composer’s “See the exact PDF before you pay” link renders the letter through the same renderTextToPdf the order path uses, so preview can never diverge from what mails.
  2. Price it and mint a confirmation_token. POST /v1/quotes returns the all-in price plus a single-use, 30-minute token bound to the exact recipient, content, class, and price. On the agent surface, POST /v1/orders requires that token — a send can never be the first call.
  • Endpoint — GET /api/preview, POST /v1/quotes (or the quote_letter MCP tool).
  • UI surface — the composer’s preview link.
Go deeper: Preview before you pay · Core concepts for how confirmation tokens work

​
Dispatch

Turn the proofed letter into a real, paid, mailed piece. POST /v1/orders does all of it in one call:
  1. USPS verifies both addresses (correcting casing/formatting where needed).
  2. Payment settles — a paperplane payment link the human approves, a prepaid credit code, or (sandbox) nothing at all.
  3. Content is screened; a flagged letter goes to held_for_review instead of printing.
  4. The print facility accepts it (submitted) and hands it to the carrier (mailed).
  • Endpoint — POST /v1/orders (or send_letter over MCP).
  • UI surface — the order page while payment or review is pending.
Go deeper: Payments & confirmation · Address handling · Error contract for what can go wrong here

​
Track

Once it’s mailed, watch it move and step in if you still can.
  • Poll GET /v1/orders/{id}, or pass webhook_url at order creation to get pushed on every transition instead.
  • Share the public timeline at /track/{trackingNumber} — no login, safe to hand to the recipient or a lawyer.
  • Cancel with DELETE /v1/orders/{id} and the order’s cancel_token, while it’s still pending_payment, screening, or held_for_review. Once submitted, it’s in the pipe.
  • Review with POST /v1/reviews and the review_token, once delivered.
  • Endpoint — GET /v1/orders/{id}, DELETE /v1/orders/{id}, POST /v1/reviews.
  • UI surface — the order page (private) and /track/{trackingNumber} (public).
Go deeper: Cancel & track · Delivery webhooks
Last modified on September 28, 2026