Mail a letter from your terminal.

The short answer

npx paperplane send letter.pdf --to ... --sandbox runs the whole pipeline for free and mails nothing. Drop --sandbox and pay with a credit code or a paperplane payment link a human approves.

The math

What it takes to try it.

	paperplane CLI
Accounts to create	0
API keys to store	0
Cost to test	Free; the sandbox mails nothing

Send a letter

Upload a PDF and mail it. --from is required — USPS requires a return address on every letter — or set PAPERPLANE_FROM once so you don't have to pass it every time.

npx paperplane send letter.pdf \
  --to "Maria Alvarez, 1 Main St, Richmond VA 23220" \
  --from "Alex Rivera, 12 Grove Ave, Richmond VA 23221" \
  --sandbox

--sandbox runs the entire flow — upload, screening, simulated fulfillment, a tracking number — instantly and free, and mails nothing.

The paperplane CLI is a thin wrapper over the same public REST API the website and every integration use — quote a letter, send it, and check its status without leaving your terminal or scripts. No install step required with npx, no account, no API key.

Install

Run it directly with npx, or install it globally:

npm install -g paperplane

Quote a letter

Price a letter before sending anything. Free, one all-in total:

npx paperplane quote \
  --to "Maria Alvarez, 1 Main St, Richmond VA 23220" \
  --text "Dear Maria, ..." \
  --class certified

Check status

npx paperplane status ord_abc123

Configuration

PAPERPLANE_FROM — a default --from address, same one-line shorthand format.
PAPERPLANE_API_URL — override the API base URL (for testing against a local or staging server).

Addresses

Addresses are one line: "Name, Street, City ST ZIP", or with a second line: "Name, Street, Line2, City ST ZIP".

Payment

Every order carries its own payment — a prepaid credit code (--credit-code pp-xxxx-xxxx-xxxx) for hands-off scripts, or a paperplane payment link a human approves. Sandbox orders need neither.

The CLI covers quoting, sending, and status — for everything else (webhooks, cancellation, uploads from outside the CLI, MCP for agents), see the full API documentation.

Questions before you integrate

Can my agent spend money without me?

Not in one step. A send needs a single-use confirmation token from the quote step, bound to the exact recipient, content, class and price. A live send returns a paperplane payment link a human approves, or uses a credit code you supplied.

Is the sandbox the real pipeline?

Yes. It runs address checks, content screening and simulated printing, and it mails nothing and charges nothing.

Do I need an API key?

No. Every order carries its own payment: a credit code, or a paperplane payment link a human approves.