Send real pen-written letters, cards and postcards: quote, preview, order and track by mail.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer <your Premier Letters API key> (create one at https://www.premierletters.com/settings/api-keys). Optional for get_pricing, list_handwriting_styles and verify_address.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Check whether the user approved a connect_account request. Returns status pending, denied, expired or claimed, or, exactly once, status approved with the api_key. Poll every 10-30 seconds.
request_id from connect_account.
poll_secret from connect_account.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Check whether the user approved a connect_account request. Returns status pending, denied, expired or claimed, or, exactly once, status approved with the api_key. Poll every 10-30 seconds.
| Argument | Type | Description |
|---|---|---|
| request_id* | string | request_id from connect_account. |
| poll_secret* | string | poll_secret from connect_account. |
{
"type": "object",
"required": [
"request_id",
"poll_secret"
],
"properties": {
"request_id": {
"type": "string",
"description": "request_id from connect_account."
},
"poll_secret": {
"type": "string",
"description": "poll_secret from connect_account."
}
}
}Get a Premier Letters API key without the user copying one by hand. Pass the user's email and your name; we email them a link to approve (they can sign up from it if they have no account). Then call check_connection with the returned request_id and poll_secret every 10-30 seconds until it returns the api_key (returned once). Show the returned user_code to the user so they can match it on the approval page. No account or key needed to call this.
| Argument | Type | Description |
|---|---|---|
| mode | string | Key mode. Defaults to "live". |
| email* | string | The account owner's email address. The approval link is sent here. |
| agent_name* | string | Your name as the user will see it, 1-80 characters: letters, digits, spaces and . , ' & ( ) - _ only (no links), e.g. "Claude". |
{
"type": "object",
"required": [
"email",
"agent_name"
],
"properties": {
"mode": {
"enum": [
"live",
"test"
],
"type": "string",
"description": "Key mode. Defaults to \"live\"."
},
"email": {
"type": "string",
"description": "The account owner's email address. The approval link is sent here."
},
"agent_name": {
"type": "string",
"description": "Your name as the user will see it, 1-80 characters: letters, digits, spaces and . , ' & ( ) - _ only (no links), e.g. \"Claude\"."
}
}
}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, "card_on_file" charges the caller's saved card immediately, "balance" pays from the prepaid account balance (no small-order handling fee; fails with insufficient_balance when short), or "checkout_session" returns a checkout_url for the human to complete payment in a browser. Envelope return address: an explicit no_return_address_ack: true always wins; otherwise a supplied return_address, else the account default. With neither address, set no_return_address_ack: true to send without one.
| Argument | Type | Description |
|---|---|---|
| message* | string | The letter text. Supports {{first_name}}, {{last_name}}, {{greeting}} merge fields per-recipient. |
| options | object | handwriting_style, paper_type, product_type, mailing_option, authenticity_preset, include_letter, include_envelope, copies, output_mode ("handwritten" default, or "printed_bw" / "printed_color" to print the letter body) and envelope_output_mode (null default = hand-addressed, or "printed_bw" / "printed_color") — see /openapi.json for the full field list. |
| payment | object | |
| recipients | array | One or more recipients. At least one is required unless options.product_type is a letter/card with no envelope. |
| skip_invalid | boolean | When true, invalid recipients are skipped instead of failing the whole order. |
Create a Stripe Checkout link that adds prepaid credit (plus any bonus tier) to the authenticated account. Give checkout_url to the human to pay in a browser; the balance updates once they pay (check with get_balance). amount_cents must be a whole number between min_cents and max_cents from get_balance.
| Argument | Type | Description |
|---|---|---|
| amount_cents* | integer | Amount to add, in cents (e.g. 5000 for $50.00). |
{
"type": "object",
"required": [
"amount_cents"
],
"properties": {
"amount_cents": {
"type": "integer",
"description": "Amount to add, in cents (e.g. 5000 for $50.00)."
}
}
}Get the authenticated account's prepaid balance (balance_cents) and the top-up rules: minimum and maximum top-up, bonus tiers and suggested amounts. Orders paid with payment.method "balance" skip the small-order handling fee. Use create_topup_link to add funds.
No arguments.
{
"type": "object",
"properties": {}
}Get an order's status, delivery/tracking summary, and per-recipient mail status.
| Argument | Type | Description |
|---|---|---|
| order_id* | string | The order UUID returned by create_order. |
{
"type": "object",
"required": [
"order_id"
],
"properties": {
"order_id": {
"type": "string",
"description": "The order UUID returned by create_order."
}
}
}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. Orders under 5 pieces carry a $0.99 per-piece handling fee (included in total_cents), waived when paid from a prepaid balance. Pass output_mode (printed_bw / printed_color) to quote a printed letter body instead of a pen-written one, and envelope_output_mode to quote a printed envelope.
| Argument | Type | Description |
|---|---|---|
| char_count | number | Length of the letter message in characters. Longer letters cost more (character meter). |
| paper_type | string | Paper quality. Defaults to "standard". |
| output_mode | string | Defaults to "handwritten". printed_bw / printed_color print the letter body instead of pen-writing it; the envelope stays hand-addressed unless envelope_output_mode is set. |
| letter_count | number | Number of recipients / pieces. Defaults to 1. |
| product_type | string | Product type (letter, card, postcard, etc). Informational only — does not change pricing components beyond envelope inclusion. |
| mailing_option | string | Delivery option. Defaults to "we_mail" (we write, stamp, and mail it for you). |
| envelope_output_mode | string |
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.
No arguments.
{
"type": "object",
"properties": {}
}List the authenticated user's recent orders.
| Argument | Type | Description |
|---|---|---|
| limit | number | Max orders to return (1-100). Defaults to 20. |
| status | string | Optional status filter (pending_payment, paid, in_production, mailed, delivered, cancelled, refunded). |
{
"type": "object",
"properties": {
"limit": {
"type": "number",
"description": "Max orders to return (1-100). Defaults to 20."
},
"status": {
"type": "string",
"description": "Optional status filter (pending_payment, paid, in_production, mailed, delivered, cancelled, refunded)."
}
}
}List the authenticated user's saved letter templates.
| Argument | Type | Description |
|---|---|---|
| sort | string | Sort order. Defaults to "recent". |
| search | string | Filter templates by name or content substring. |
| favorites_only | boolean | Only return favorited templates. |
{
"type": "object",
"properties": {
"sort": {
"enum": [
"recent",
"most_used",
"name"
],
"type": "string",
"description": "Sort order. Defaults to \"recent\"."
},
"search": {
"type": "string",
"description": "Filter templates by name or content substring."
},
"favorites_only": {
"type": "boolean",
"description": "Only return favorited templates."
}
}
}Render a preview of a handwritten letter (as an SVG image) and get its price, before creating an order. Does not save anything.
| Argument | Type | Description |
|---|---|---|
| message* | string | The letter text to render. |
| recipient | object | Optional recipient info, used only to personalize {{merge fields}} in the message before rendering. |
| product_type | string | Product slug: letter, card, postcard, etc. Defaults to "letter". |
| handwriting_style | string | Font UUID from list_handwriting_styles. Defaults to the house font. |
{
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "The letter text to render."
},
"recipient": {
"type": "object",
"properties": {
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
}
},
"description": "Optional recipient info, used only to personalize {{merge fields}} in the message before rendering."
},
"product_type": {
"type": "string",
"description": "Product slug: letter, card, postcard, etc. Defaults to \"letter\"."
},
"handwriting_style": {
"type": "string",
"description": "Font UUID from list_handwriting_styles. Defaults to the house font."
}
}
}Verify and standardize a US mailing address via USPS. Use before create_order to catch typos and get the USPS-standardized form.
| Argument | Type | Description |
|---|---|---|
| zip* | string | 5-digit or ZIP+4 postal code |
| city* | string | |
| state* | string | Two-letter US state code |
| address_line1* | string | Street address |
| address_line2 | string | Apt/suite/unit (optional) |
{
"type": "object",
"required": [
"address_line1",
"city",
"state",
"zip"
],
"properties": {
"zip": {
"type": "string",
"description": "5-digit or ZIP+4 postal code"
},
"city": {
"type": "string"
},
"state": {
"type": "string",
"description": "Two-letter US state code"
},
"address_line1": {
"type": "string",
"description": "Street address"
},
"address_line2": {
"type": "string",
"description": "Apt/suite/unit (optional)"
}
}
}| return_address |
| object |
| Return address written on the envelope. Omit to use the account's default return address. Required unless the account has a default or no_return_address_ack is true. An explicit no_return_address_ack: true always wins; otherwise a supplied return_address, else the account default. name, address_line1, city, state and zip are required unless return_address_partial_ok is true. |
| idempotency_key | string | Client-supplied key (1–255 chars). Repeating a call with the same key returns the original order instead of creating a second one. Always set this when you might retry. |
| no_return_address_ack | boolean | Send with no return address at all. An explicit no_return_address_ack: true always wins; otherwise a supplied return_address, else the account default. Undeliverable mail is then destroyed. |
| return_address_partial_ok | boolean | Send return_address exactly as written although it is incomplete: at least one of name, company, address_line1, city, state, zip. Only the filled lines print (a name alone is fine). Without it an incomplete return_address is refused. |
{
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "The letter text. Supports {{first_name}}, {{last_name}}, {{greeting}} merge fields per-recipient."
},
"options": {
"type": "object",
"description": "handwriting_style, paper_type, product_type, mailing_option, authenticity_preset, include_letter, include_envelope, copies, output_mode (\"handwritten\" default, or \"printed_bw\" / \"printed_color\" to print the letter body) and envelope_output_mode (null default = hand-addressed, or \"printed_bw\" / \"printed_color\") — see /openapi.json for the full field list."
},
"payment": {
"type": "object",
"properties": {
"method": {
"enum": [
"card_on_file",
"checkout_session",
"balance"
],
"type": "string",
"description": "Defaults to \"checkout_session\"."
},
"return_url": {
"type": "string"
}
}
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"address_line1": {
"type": "string"
},
"address_line2": {
"type": "string"
},
"custom_fields": {
"type": "object"
}
}
},
"description": "One or more recipients. At least one is required unless options.product_type is a letter/card with no envelope."
},
"skip_invalid": {
"type": "boolean",
"description": "When true, invalid recipients are skipped instead of failing the whole order."
},
"return_address": {
"type": "object",
"properties": {
"zip": {
"type": "string",
"description": "5-digit ZIP or ZIP+4."
},
"city": {
"type": "string"
},
"name": {
"type": "string"
},
"state": {
"type": "string",
"description": "2-letter US state code."
},
"company": {
"type": "string"
},
"address_line1": {
"type": "string"
},
"address_line2": {
"type": "string"
}
},
"description": "Return address written on the envelope. Omit to use the account's default return address. Required unless the account has a default or no_return_address_ack is true. An explicit no_return_address_ack: true always wins; otherwise a supplied return_address, else the account default. name, address_line1, city, state and zip are required unless return_address_partial_ok is true."
},
"idempotency_key": {
"type": "string",
"description": "Client-supplied key (1–255 chars). Repeating a call with the same key returns the original order instead of creating a second one. Always set this when you might retry."
},
"no_return_address_ack": {
"type": "boolean",
"description": "Send with no return address at all. An explicit no_return_address_ack: true always wins; otherwise a supplied return_address, else the account default. Undeliverable mail is then destroyed."
},
"return_address_partial_ok": {
"type": "boolean",
"description": "Send return_address exactly as written although it is incomplete: at least one of name, company, address_line1, city, state, zip. Only the filled lines print (a name alone is fine). Without it an incomplete return_address is refused."
}
}
}| Omit (or null) for a hand-addressed envelope, the default. printed_bw / printed_color print the envelope instead. |
{
"type": "object",
"properties": {
"char_count": {
"type": "number",
"description": "Length of the letter message in characters. Longer letters cost more (character meter)."
},
"paper_type": {
"enum": [
"standard",
"premium"
],
"type": "string",
"description": "Paper quality. Defaults to \"standard\"."
},
"output_mode": {
"enum": [
"handwritten",
"printed_bw",
"printed_color"
],
"type": "string",
"description": "Defaults to \"handwritten\". printed_bw / printed_color print the letter body instead of pen-writing it; the envelope stays hand-addressed unless envelope_output_mode is set."
},
"letter_count": {
"type": "number",
"description": "Number of recipients / pieces. Defaults to 1."
},
"product_type": {
"enum": [
"letter",
"card",
"a7",
"postcard",
"card_5x7",
"postcard_5x7",
"a4",
"a5",
"a6"
],
"type": "string",
"description": "Product type (letter, card, postcard, etc). Informational only — does not change pricing components beyond envelope inclusion."
},
"mailing_option": {
"enum": [
"we_mail",
"you_mail_stamped",
"you_mail_no_stamp"
],
"type": "string",
"description": "Delivery option. Defaults to \"we_mail\" (we write, stamp, and mail it for you)."
},
"envelope_output_mode": {
"enum": [
"printed_bw",
"printed_color"
],
"type": "string",
"description": "Omit (or null) for a hand-addressed envelope, the default. printed_bw / printed_color print the envelope instead."
}
}
}