> ## 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.
# Quickstart
> Send your first letter in about two minutes, for free.
Send your first letter in about two minutes. This quickstart uses **sandbox** mode (free, instant, nothing real mailed).
## 1. Price a letter
Free, creates nothing. Returns the all-in price and a `confirmation_token` bound to this exact letter.
```bash curl theme={null}
curl -X POST https://sendpaperplane.com/v1/quotes \
-H 'Content-Type: application/json' \
-d '{
"mail_class": "certified",
"page_count": 1,
"to": { "name": "Property LLC", "line1": "1 Main St",
"city": "Richmond", "state": "VA", "zip": "23220" },
"from": { "name": "Alex Rivera", "line1": "12 Grove Ave",
"city": "Richmond", "state": "VA", "zip": "23221" },
"text": "Formal demand for return of my security deposit within 14 days..."
}'
```
```python Python theme={null}
import requests
quote = requests.post(
"https://sendpaperplane.com/v1/quotes",
json={
"mail_class": "certified",
"page_count": 1,
"to": {"name": "Property LLC", "line1": "1 Main St", "city": "Richmond", "state": "VA", "zip": "23220"},
"from": {"name": "Alex Rivera", "line1": "12 Grove Ave", "city": "Richmond", "state": "VA", "zip": "23221"},
"text": "Formal demand for return of my security deposit within 14 days...",
},
).json()
```
## 2. Create the order
Sandbox `true` runs the whole pipeline for free and returns a completed order.
```bash curl theme={null}
curl -X POST https://sendpaperplane.com/v1/orders \
-H 'Content-Type: application/json' \
-d '{
"mail_class": "certified",
"sandbox": true,
"text": "Formal demand for return of my security deposit within 14 days...",
"to": { "name": "Property LLC", "line1": "1 Main St",
"city": "Richmond", "state": "VA", "zip": "23220" },
"from": { "name": "Alex Rivera", "line1": "12 Grove Ave",
"city": "Richmond", "state": "VA", "zip": "23221" },
"email": "alex@example.com"
}'
```
```python Python theme={null}
order = requests.post(
"https://sendpaperplane.com/v1/orders",
json={
"mail_class": "certified",
"sandbox": True,
"text": "Formal demand for return of my security deposit within 14 days...",
"to": {"name": "Property LLC", "line1": "1 Main St", "city": "Richmond", "state": "VA", "zip": "23220"},
"from": {"name": "Alex Rivera", "line1": "12 Grove Ave", "city": "Richmond", "state": "VA", "zip": "23221"},
"email": "alex@example.com",
},
).json()
```
Live mode (no `sandbox`) returns a `payment_url` for the human to approve instead. Sandbox skips payment and simulates fulfillment with a mock tracking number.
## 3. Track it
```bash theme={null}
curl https://sendpaperplane.com/v1/orders/ord_test_2ea2f33a74206e2d
```
Poll this endpoint, or configure [delivery webhooks](/docs/guides/webhooks) to be pushed to instead.
## 4. Cancellation, tracking & reviews
* **Preview** — `GET /api/preview?text=...` shows the exact PDF before you pay ([guide](/docs/guides/print-preflight)).
* **Cancel** (`DELETE`) releases any payment hold, and requires the `cancel_token`. Also available as a button on the web order page.
* **Track** — share the public page at `/track/{trackingNumber}` once mailed ([guide](/docs/guides/cancel-track)).
* **Review** (`POST /v1/reviews`) publishes feedback from your return address, and requires the `review_token`.
The `cancel_token` and `review_token` come back under `capability` at order creation, are bound to the order id + action, and expire after 7 days. See [Core concepts](/docs/concepts).
## 5. Or send a postcard instead
Postcards are a real, live format — not just letters. Add `format` and drop
straight to `text`; no PDF, no page count, one flat price ($1.99 for 4x6;
$2.99 for 6x9; \$3.49 for 6x11 — see [Mail formats](/docs/concepts#mail-formats)).
```bash theme={null}
curl -X POST https://sendpaperplane.com/v1/orders \
-H 'Content-Type: application/json' \
-d '{
"mail_class": "first_class",
"format": "postcard_4x6",
"sandbox": true,
"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" }
}'
```
Postcards are message-only right now: the `text` prints directly on the
card, no custom photo or artwork side yet.
## 6. Or send a notecard
The notecard is the private counterpart to a postcard: same message-only,
flat-price shape, but folded and enclosed like a greeting card rather than
open-face — nobody handling it in transit can read it. One flat price
(\$5.99 — see [Mail formats](/docs/concepts#mail-formats)), no page count, no PDF.
```bash theme={null}
curl -X POST https://sendpaperplane.com/v1/orders \
-H 'Content-Type: application/json' \
-d '{
"mail_class": "first_class",
"format": "notecard",
"sandbox": true,
"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 MCP tools take the same `format` argument — `quote_letter`/`send_letter`
can quote and send a notecard or postcard, not only a letter. See
[MCP](/docs/guides/mcp).
## Other surfaces
* **[Embed](/docs/guides/embed)** — add the send flow to your own site with one script.
* **[Send by email](/docs/guides/email-to-send)** — forward an email and we mail it.
* **[Send by text](/docs/guides/imessage-to-send)** — text a recipient and a letter, confirm, done.
* **[Templates](/docs/guides/templates)** — start from a proven letter at the [gallery](https://sendpaperplane.com/templates).