Premier Letters

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.

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

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

{
  "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 — see /openapi.json for the full field list."
    },
    "payment": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "enum": [
            "card_on_file",
            "checkout_session"
          ],
          "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."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional client-supplied key. Not yet enforced server-side; reserved for future use."
    }
  },
  "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)."
    }
  }
}