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 (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.
View input schema
{
"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; \"facsimile\" prints the handwriting on a laser printer; \"printed_bw\" / \"printed_color\" print typed text) and envelope_output_mode (null default = hand-addressed, or \"facsimile\" / \"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."
},
"mailing": {
"type": "object",
"description": "Optional: a built mailing instead of piecing together options + extras. Either a tier {\"tier\":\"essential\"} (luxe = pen letter + pen envelope; signature = pen-addressed envelope, printed-handwriting letter; essential = printed handwriting throughout; print = printed type) or a full mailing: {\"tier\":\"signature\",\"main\":{\"format\":\"card\",\"size\":\"card\",\"design\":\"thank_you\"},\"contents\":[{\"item\":\"business_card\",\"qty\":1}],\"addons\":[{\"id\":\"foil_seal\"}],\"envelopeStock\":\"premium_cream\"}. It sets product_type, output modes, paper, envelope and mailing_option, and adds its pieces to extras. Price it first with get_pricing (same mailing). Item ids: /llms-full.txt \"Build a mailing\"."
},
"extras": {
"type": "array",
"description": "Optional extra pieces for each envelope (printed insert, printed letter, your own insert, flyer, business card…). Call list_extras for pieces, options and prices. \"instant\" pieces are charged with the order; \"request\" pieces are priced by staff afterwards and cost nothing now.",
"items": {
"type": "object",
"properties": {
"piece": {
"type": "string",
"description": "Piece key from list_extras."
},
"options": {
"type": "object",
"description": "Option choices, e.g. { \"size\": \"small\", \"color\": \"bw\" }. Omitted options take the first choice."
},
"quantity": {
"type": "integer",
"minimum": 1,
"description": "Per recipient (default) or in total when scope is \"flat\". Default 1."
},
"scope": {
"type": "string",
"enum": [
"per_recipient",
"flat"
]
},
"artwork_url": {
"type": "string",
"description": "https URL of print-ready artwork (PDF/PNG/JPEG). Required for instant printed pieces."
},
"note": {
"type": "string",
"description": "Anything staff should know about this piece."
},
"role": {
"type": "string",
"enum": [
"pen_stock"
],
"description": "Write the handwritten letter ON this printed piece (printed letter, letter flyer, 4x6 postcard). Needs a pen-written letter of the matching product type."
}
},
"required": [
"piece"
]
}
}
},
"required": [
"message"
]
}