Skip to main content
Glama
Sign In

thanks.io

by io.thanks
OverviewDiscussionsAdmin

Send Letter

send-letter
Destructive

Send a real letter in a windowed envelope, where the recipient address shows through a window in the envelope. Can either print a handwritten message on letterhead, or mail a supplied PDF as the entire letter (pass pdf_only_url). THIS SPENDS MONEY: it charges the account and physically prints and mails the letter, and it cannot be undone once printing starts. Always call preview-order first with the same arguments, show the user the proof image and the price, and get their explicit confirmation before calling this. The preferred way to say what to print is a complete creative_id from list-creatives, which carries the saved design and message as one.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "send-letter"
  }
}

Input Schema

NameRequiredDescriptionDefault
messageNoThe 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.
realismNoRealism mode: slight imperfections that make the handwriting look written by hand. Defaults to the message template's setting, then the account's.
metadataNoOptional key/value metadata stored on the order and echoed back by order tools and webhooks. Flat object of scalar values.
qrcode_urlNoURL 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.
recipientsNoAddresses 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_idNoID 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_cityNoCustom return address city.
return_nameNoCustom return address name. All five return address fields must be given together, and this is not available on the Enterprise plan.
email_lookupNoWhether 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_urlNoURL 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_stateNoCustom return address state or province.
schedule_forNoDate to mail on instead of immediately, e.g. "2026-09-01".
mailing_listsNoIDs of saved mailing lists to send to. Use list-mailing-lists to find them. Provide either recipients or mailing_lists.
postage_classNoPostage 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.
return_addressNoCustom return street address.
sub_account_idNoSend on behalf of this sub-account. Use list-sub-accounts to find one.
front_image_urlNoPublicly reachable image URL for the front of the mailer. PNG or JPG; SVG is not supported.
return_address2NoCustom return address line 2.
handwriting_sizeNoHandwriting size.
handwriting_colorNoHandwriting color: "black", "blue", "red", "green", "purple", or a hex code like "#FF5500".
handwriting_styleNoHandwriting style ID. Use list-handwriting-styles to see the options and their sample images.
image_template_idNoID 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_idNoID 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_codeNoCustom return address postal code.
message_template_idNoID 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_urlNoURL 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / message / description
      Previous value: -"The handwritten message. Merge variables such as {{first_name}} are filled per recipient from mailing list data; if you use one with ad-hoc recipients it must be replaced with real text first."New value: +"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."
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the destructiveHint=true annotation by naming the concrete consequences: it charges the account, physically prints and mails, and 'cannot be undone once printing starts', plus a spend warning in caps. The irreversibility trigger point (printing start) is unusual and important context an agent could not infer from annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, each carrying distinct load: what it does, how it costs/irreversibility, the mandatory preview-and-confirm flow, and the preferred parameter path. The money warning is front-loaded near the start where it will be read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 26-parameter, irreversible, no-output-schema tool this covers the high-risk decision points well: cost, irreversibility, preview-first, and the creative_id vs. PDF fork. Minor gap is the absence of any statement about what a successful call returns (order id?) or how to follow up, which matters given there is no output schema — though sibling names like get-order partially fill that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so 3 is the floor; the description earns a bump by explaining the composition rule that creative_id cannot be combined with template/message/PDF parameters and that it is the preferred route. It also clarifies when pdf_only_url is appropriate rather than merely what it is, though it doesn't touch the many recipient or return-address fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Send a real letter in a windowed envelope') and immediately clarifies the window-address mechanic, which separates it from send-windowlessletter among the siblings. It also states the two mutually exclusive content modes (handwritten-on-letterhead vs. supplied PDF), so an agent can identify the tool's scope without reading the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes the workflow: 'Always call preview-order first with the same arguments', show the proof image and price, and get explicit confirmation. It also routes between alternatives — 'the preferred way to say what to print is a complete creative_id from list-creatives' — and names the condition for pdf_only_url ('when the user supplies a finished document').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All thanks.io toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources