Upload a REUSABLE template containing `{{field}}` placeholders (e.g. `Dear {{name}},` or `Balance due: {{amount}}`). Choose this ONLY when the content must vary per recipient (mail merge) — recipient count is irrelevant, so a single personalized letter belongs here too. If the content is identical for everyone, use create_letter instead (this tool rejects input with no `{{fields}}`). Returns a documentId with `kind: "html_template"`, a `mergeFields` list of the detected field names, and an `estimatedPageCount`. Free; no payment required.
Template source must be TEXT-BASED (html, markdown, or text) and must contain at least one `{{field}}`, or the upload is rejected — for a finished document with no merge fields, use `create_letter`.
Provide the template EXACTLY ONE way: `content` (inline text), `contentBase64` (base64-encoded text), or `url` (a publicly reachable URL the server fetches). Supplying none, or more than one, is an error. Maximum upload size is 31457280 bytes (~30 MB); output page size is US Letter.
Reuse one template documentId across recipients: call create_mail_quote ONCE PER RECIPIENT, supplying that recipient's values via `mergeVariables` (every field in `mergeFields` must have a non-empty value). The server substitutes the values and renders that recipient's personalized PDF at quote time, so `estimatedPageCount` is only a baseline — the binding page count and price are set per quote from the actual rendered output.
Reserved address zone: a recipient address block is printed over the top ~3 inches of page 1, so the server reserves that space automatically (page-1 content is pushed below the block and may flow onto an additional page). You do NOT need to leave the top blank yourself. See the postagent://formats resource for details.