# Premier Letters — full agent reference

> Premier Letters writes your letters, cards and postcards with a pen and mails them for you — from one thank-you note to a 10,000-piece campaign.

## Positioning

Real pen. Real paper. Real stamp.

- **It gets opened.** Direct mail is read far more often than email, per ANA and USPS research.
- **It gets remembered.** Pen on paper, a hand-addressed envelope, a real Forever stamp — never printed indicia.
- **It is effortless.** Write it like an email. We handle the pen, the paper, the stamp, and the mailbox.
- **Honest pricing.** One all-in price per piece. Longer letters cost more because the pen writes every character.
- **Automate it.** API, Zapier, Gmail, and AI agents through MCP.

## FAQ

**Is it actually handwritten?** Yes — a robotically-driven pen physically writes every letter, card and envelope. Nothing is printed except optional printed-mailpiece add-ons a customer explicitly chooses.

**How much does it cost?** From $4.60 per letter plus postage (We Mail It), postage passed through at face value. The first 300 characters are included; every additional 100 characters adds $0.75 per piece. Paper quality, delivery option (we mail it vs. ship to you) and volume all affect the final price — see /openapi.json or POST /api/v1/validate for an exact quote.

**How long does it take?** We write and mail within 2 business days; USPS First-Class delivery then typically takes 3–5 business days. Letters travel with a real Forever stamp, exactly like personal mail, so there is no tracking number. We tell you the day it goes into the mailbox and the window it should arrive in.

**Can an AI agent place an order on a user's behalf?** Yes, via the MCP server below. Quoting, previewing and address verification work without an account; creating an order requires the user's Premier Letters API key.

## REST API summary

Base URL: `https://www.premierletters.com/api/v1`. Full machine-readable spec: [/openapi.json](https://www.premierletters.com/openapi.json).

| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/config | Public pricing tiers, char meter, service levels |
| GET | /api/v1/auth/verify | Verify an API key |
| GET | /api/v1/styles | List handwriting styles |
| POST | /api/v1/validate | Dry-run price + validation for an order |
| POST | /api/v1/preview | Render a letter to SVG + price, no order created |
| GET/POST | /api/v1/orders | List / create orders |
| GET | /api/v1/orders/{id} | Order detail |
| GET | /api/v1/orders/{id}/tracking | Per-recipient tracking |

## MCP server

Endpoint: `https://www.premierletters.com/api/mcp` (Streamable HTTP, stateless JSON-RPC 2.0, no SSE). Auth: `Authorization: Bearer pl_live_...`. `initialize`, `ping` and `tools/list` work without a key; `tools/call` requires one except for: get_pricing, list_handwriting_styles, verify_address.

### Tools

- **get_pricing** (no key required) — Get a live price quote for a Premier Letters order. Pass char_count (or letter_count for a rough estimate) plus optional mailing_option and paper_type to get a per-piece and total price, in cents. No account needed.
- **list_handwriting_styles** (no key required) — List available handwriting styles (fonts) for a letter order. Use the returned "id" as options.handwriting_style / handwriting_style when creating an order or previewing.
- **list_templates** (requires API key) — List the authenticated user's saved letter templates.
- **verify_address** (no key required) — Verify and standardize a US mailing address via USPS. Use before create_order to catch typos and get the USPS-standardized form.
- **preview_letter** (requires API key) — Render a preview of a handwritten letter (as an SVG image) and get its price, before creating an order. Does not save anything.
- **create_order** (requires API key) — Create and pay for a Premier Letters order — a real, handwritten letter mailed via USPS. Requires a Premier Letters API key. Use get_pricing or preview_letter first to confirm the price. For payment, either "card_on_file" charges the caller's saved card immediately, or "checkout_session" returns a checkout_url for the human to complete payment in a browser.
- **get_order_status** (requires API key) — Get an order's status, delivery/tracking summary, and per-recipient mail status.
- **list_orders** (requires API key) — List the authenticated user's recent orders.

## Add to an MCP client

**Claude:** claude.ai → Settings → Connectors → Add custom connector → URL `https://www.premierletters.com/api/mcp` → paste your Premier Letters API key as the bearer token.
**ChatGPT:** Settings → Connectors (developer mode) → Add MCP server → URL `https://www.premierletters.com/api/mcp`.

## More

- [Pricing](https://www.premierletters.com/pricing)
- [FAQ](https://www.premierletters.com/faq)
- [How it works](https://www.premierletters.com/how-it-works)
- [Developers](https://www.premierletters.com/developers)
- [OpenAPI spec](https://www.premierletters.com/openapi.json)