Premier Letters

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.

{
  "type": "object",
  "properties": {
    "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\"."
    },
    "mode": {
      "type": "string",
      "enum": [
        "live",
        "test"
      ],
      "description": "Key mode. Defaults to \"live\"."
    }
  },
  "required": [
    "email",
    "agent_name"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "description": "request_id from connect_account."
    },
    "poll_secret": {
      "type": "string",
      "description": "poll_secret from connect_account."
    }
  },
  "required": [
    "request_id",
    "poll_secret"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "char_count": {
      "type": "number",
      "description": "Length of the letter message in characters. Longer letters cost more (character meter)."
    },
    "letter_count": {
      "type": "number",
      "description": "Number of recipients / pieces. Defaults to 1."
    },
    "mailing_option": {
      "type": "string",
      "enum": [
        "we_mail",
        "you_mail_stamped",
        "you_mail_no_stamp"
      ],
      "description": "Delivery option. Defaults to \"we_mail\" (we write, stamp, and mail it for you)."
    },
    "paper_type": {
      "type": "string",
      "enum": [
        "standard",
        "premium"
      ],
      "description": "Paper quality. Defaults to \"standard\"."
    },
    "product_type": {
      "type": "string",
      "enum": [
        "letter",
        "card",
        "a7",
        "postcard",
        "card_5x7",
        "postcard_5x7",
        "a4",
        "a5",
        "a6"
      ],
      "description": "Product type (letter, card, postcard, etc). Informational only — does not change pricing components beyond envelope inclusion."
    },
    "output_mode": {
      "type": "string",
      "enum": [
        "handwritten",
        "printed_bw",
        "printed_color"
      ],
      "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."
    },
    "envelope_output_mode": {
      "type": "string",
      "enum": [
        "printed_bw",
        "printed_color"
      ],
      "description": "Omit (or null) for a hand-addressed envelope, the default. printed_bw / printed_color print the envelope instead."
    }
  }
}

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.

{
  "type": "object",
  "properties": {}
}

List the authenticated user's saved letter templates.

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter templates by name or content substring."
    },
    "favorites_only": {
      "type": "boolean",
      "description": "Only return favorited templates."
    },
    "sort": {
      "type": "string",
      "enum": [
        "recent",
        "most_used",
        "name"
      ],
      "description": "Sort order. Defaults to \"recent\"."
    }
  }
}

Verify and standardize a US mailing address via USPS. Use before create_order to catch typos and get the USPS-standardized form.

{
  "type": "object",
  "properties": {
    "address_line1": {
      "type": "string",
      "description": "Street address"
    },
    "address_line2": {
      "type": "string",
      "description": "Apt/suite/unit (optional)"
    },
    "city": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "description": "Two-letter US state code"
    },
    "zip": {
      "type": "string",
      "description": "5-digit or ZIP+4 postal code"
    }
  },
  "required": [
    "address_line1",
    "city",
    "state",
    "zip"
  ]
}

Render a preview of a handwritten letter (as an SVG image) and get its price, before creating an order. Does not save anything.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The letter text to render."
    },
    "handwriting_style": {
      "type": "string",
      "description": "Font UUID from list_handwriting_styles. Defaults to the house font."
    },
    "product_type": {
      "type": "string",
      "description": "Product slug: letter, card, postcard, etc. Defaults to \"letter\"."
    },
    "recipient": {
      "type": "object",
      "description": "Optional recipient info, used only to personalize {{merge fields}} in the message before rendering.",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "message"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The letter text. Supports {{first_name}}, {{last_name}}, {{greeting}} merge fields per-recipient."
    },
    "recipients": {
      "type": "array",
      "description": "One or more recipients. At least one is required unless options.product_type is a letter/card with no envelope.",
      "items": {
        "type": "object",
        "properties": {
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "address_line1": {
            "type": "string"
          },
          "address_line2": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "custom_fields": {
            "type": "object"
          }
        }
      }
    },
    "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": {
          "type": "string",
          "enum": [
            "card_on_file",
            "checkout_session",
            "balance"
          ],
          "description": "Defaults to \"checkout_session\"."
        },
        "return_url": {
          "type": "string"
        }
      }
    },
    "skip_invalid": {
      "type": "boolean",
      "description": "When true, invalid recipients are skipped instead of failing the whole order."
    },
    "return_address": {
      "type": "object",
      "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.",
      "properties": {
        "name": {
          "type": "string"
        },
        "company": {
          "type": "string"
        },
        "address_line1": {
          "type": "string"
        },
        "address_line2": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "description": "2-letter US state code."
        },
        "zip": {
          "type": "string",
          "description": "5-digit ZIP or ZIP+4."
        }
      }
    },
    "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."
    },
    "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."
    },
    "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."
    }
  },
  "required": [
    "message"
  ]
}

Get an order's status, delivery/tracking summary, and per-recipient mail status.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order UUID returned by create_order."
    }
  },
  "required": [
    "order_id"
  ]
}

List the authenticated user's recent orders.

{
  "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)."
    }
  }
}

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.

{
  "type": "object",
  "properties": {}
}

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.

{
  "type": "object",
  "properties": {
    "amount_cents": {
      "type": "integer",
      "description": "Amount to add, in cents (e.g. 5000 for $50.00)."
    }
  },
  "required": [
    "amount_cents"
  ]
}