Quickstart

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.

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..."
  }'

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.

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"
  }'

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

curl https://sendpaperplane.com/v1/orders/ord_test_2ea2f33a74206e2d

Poll this endpoint, or configure delivery webhooks to be pushed to instead.

4. Cancellation, tracking & reviews

Preview — GET /api/preview?text=... shows the exact PDF before you pay (guide).
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).
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.

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).

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), no page count, no PDF.

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.

Other surfaces

Embed — add the send flow to your own site with one script.
Send by email — forward an email and we mail it.
Send by text — text a recipient and a letter, confirm, done.
Templates — start from a proven letter at the gallery.

Get started

Guides

Tutorials

1. Price a letter

2. Create the order

3. Track it

4. Cancellation, tracking & reviews

5. Or send a postcard instead

6. Or send a notecard

Other surfaces

​1. Price a letter

​2. Create the order

​3. Track it

​4. Cancellation, tracking & reviews

​5. Or send a postcard instead

​6. Or send a notecard

​Other surfaces

1. Price a letter

2. Create the order

3. Track it

4. Cancellation, tracking & reviews

5. Or send a postcard instead

6. Or send a notecard

Other surfaces