Preview Order
preview-orderIdempotent
Preview a mail order before paying for it: renders proof images of exactly what will be printed and calculates the total price, without charging anything or creating an order. On Free and Business plans the proofs carry a "DRAFT" watermark that is not printed on the mail. The one exception is a recipient given an email but no street address: finding their address is a paid lead lookup, so it needs the account's "Allow lead purchases via MCP" permission and is refused without it. ALWAYS use this before any send tool. Show the user the proof image URLs and the total cost, and only call the matching send tool after they confirm. Accepts the same arguments as the send tools, plus type. A complete creative_id from list-creatives is the preferred way to say what to print.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"type": "<type>"
},
"name": "preview-order"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Postcard size, when type is "postcard". Defaults to the creative's own size when creative_id is given, otherwise the account default. | |
| type | Yes | The kind of mailer to preview. | |
| message | No | The handwritten message. Merge variables such as %FIRST_NAME% or %CITY% are filled per recipient from mailing list data; if you use one with ad-hoc recipients it must be replaced with real text first. | |
| realism | No | Realism mode: slight imperfections that make the handwriting look written by hand. Defaults to the message template's setting, then the account's. | |
| metadata | No | Optional key/value metadata stored on the order and echoed back by order tools and webhooks. Flat object of scalar values. | |
| qrcode_url | No | URL to encode as a QR code on the mailer. Strongly recommended: scans are tracked per piece, and this is what makes the send measurable later. A send without a qrcode_url (gift cards excepted, which are tracked by redemption) produces no result data at all and can never be evaluated by get-performance — warn the user before sending one blind. | |
| recipients | No | Addresses to mail to, supplied directly. Use this for one-off sends like "send a postcard to Jane at 123 Main St". Provide either recipients or mailing_lists. | |
| creative_id | No | ID of a complete creative from list-creatives: a saved front and message that send as one. The preferred way to send whenever the account has a creative for what the user wants to mail. It sends exactly as saved - its design, message, handwriting and background all come from the creative - so it cannot be combined with image_template_id, message_template_id, front_image_url, message, the handwriting parameters or pdf_only_url; qrcode_url and additional_pages_url may still be added. A postcard creative sends at its own size when size is left out. | |
| return_city | No | Custom return address city. | |
| return_name | No | Custom return address name. All five return address fields must be given together, and this is not available on the Enterprise plan. | |
| email_lookup | No | Whether a recipient given an email but no street address has their address looked up (a paid lead lookup that needs the "Allow lead purchases via MCP" permission). Defaults to true. Pass false to leave such recipients out instead; the order then mails only recipients with an address. | |
| pdf_only_url | No | URL of a PDF to mail AS THE ENTIRE LETTER. No message is written and no letterhead or creative is generated — only the pages of this PDF are printed. Use this when the user supplies a finished document to mail as-is. Maximum 12 pages, priced per page. Takes precedence over additional_pages_url, and makes message, front_image_url and the template parameters irrelevant. The recipient address comes from the recipient fields, never the PDF: for a windowed letter, thanks.io prints it in the upper-left envelope-window area of page 1, so that area of the PDF must be blank. A PDF that already contains an address gets a second one printed over it. A windowless letter's address goes on the envelope, so its PDF needs no blank area. | |
| return_state | No | Custom return address state or province. | |
| schedule_for | No | Date to mail on instead of immediately, e.g. "2026-09-01". | |
| mailing_lists | No | IDs of saved mailing lists to send to. Use list-mailing-lists to find them. Provide either recipients or mailing_lists. | |
| postage_class | No | Postage class. "first_class" delivers in 5-10 business days; "standard" is Standard Mail, also known as Marketing Mail: cheaper for US addresses, 10-20 business days, with no tracking status and no return-to-sender. Leave it out to use the account's default (get-account-info shows it as default_postage_class). "standard" needs a paid plan and is refused on a free one. Standard Mail only changes the price of US addresses, and nonprofit accounts always mail at their nonprofit rate. | |
| giftcard_brand | No | Gift card brand key, when type is "giftcard". Use list-giftcard-brands. | |
| return_address | No | Custom return street address. | |
| sub_account_id | No | Send on behalf of this sub-account. Use list-sub-accounts to find one. | |
| front_image_url | No | Publicly reachable image URL for the front of the mailer. PNG or JPG; SVG is not supported. | |
| return_address2 | No | Custom return address line 2. | |
| handwriting_size | No | Handwriting size. | |
| handwriting_color | No | Handwriting color: "black", "blue", "red", "green", "purple", or a hex code like "#FF5500". | |
| handwriting_style | No | Handwriting style ID. Use list-handwriting-styles to see the options and their sample images. | |
| image_template_id | No | ID of a saved image template (design) to use for the front. Use list-image-templates to find one. For a one-off combination: when the user already has the front and message saved together, pass creative_id (list-creatives) instead. | |
| return_address_id | No | ID of one of the account's saved return addresses to print as the return address; get-account-info lists them under saved_return_addresses. Use this or the return_* fields, not both. Not available on the Enterprise plan. | |
| return_postal_code | No | Custom return address postal code. | |
| message_template_id | No | ID of a saved message template to use instead of writing a message. Use list-message-templates to find one. A template also supplies its own handwriting settings. For a one-off combination: when the user already has the front and message saved together, pass creative_id (list-creatives) instead. | |
| additional_pages_url | No | URL of a PDF to append AFTER the generated letter. The handwritten message and letterhead are still printed as the first page. Maximum 10 pages, and each extra page adds to the cost. Do not combine with pdf_only_url. | |
| giftcard_amount_in_cents | No | Face value of each gift card in cents, when type is "giftcard". Must be one of the brand's available_amounts from list-giftcard-brands. |