Skip to main content

create_postcard

string
default:"4x6"
4x6, 6x9 or 6x11.
Address
Recipient: name, line1, optional line2, city, two-letter state, zip. US only. Send this or recipients.
Address[]
Send the same card to several people: 2 to 25 addresses, instead of to. Each gets its own order; one payment covers all. See Send to several people.
SenderAddress
required
Return address, printed on the card. It can be outside the US: add a two-letter country (e.g. GB); then state is the region and zip the postcode, both optional. Without country it’s a US address.
string
headline, photo, photo_caption or collage. Inferred from the fields you send when omitted.
string
headline layout: up to 60 characters of big text, with front_theme: ink, sky, sunset, forest, rose, sand, night or mint.
string
photo and photo_caption layouts: https URL of a JPG or PNG.
string
photo_caption layout: up to 80 characters over a band at the bottom of the photo.
string[]
collage layout: 2 to 4 https photo URLs, arranged in a grid.
string
default:"serif"
Headline or caption font: serif, sans or script.
string
required
The message on the back, up to 600 characters.
string
default:"handwriting"
handwriting, serif or sans.
boolean
default:"false"
USPS Priority Mail, usually 2–3 days with tracking, for an extra charge (see get_pricing).
string
Any unique string; a retry with the same key returns the original order.

create_letter

Same to or recipients, from and idempotency_key, plus:
string
Plain text, blank lines between paragraphs, up to about 3 pages. Send this or content.pdf_url.
string
Mail your own document: a public https link to a PDF of up to 6 pages. Any page size is fitted to 8.5×11, and a blank address page is added in front.
boolean
PDF letters: print in color for $1.00 more.</ParamField> <ParamField path="content.font" type="string" default="serif">`serif` or `sans`.</ParamField> <ParamField path="content.image_url" type="string">Optional https URL of a JPG or PNG printed under the date. A letter with a photo prints in color and costs $1.00 more.
string
default:"none"
none ($4.99), `certified` ($14.99, USPS tracking and proof of delivery) or certified_return_receipt ($19.99, adds the recipient’s signature).
boolean
default:"false"
USPS Priority Mail (2–3 days, tracked) for an extra charge. Can’t be combined with certified.

pay_order

string
required
The order to pay (ord_…).
string
required
A Stripe shared payment token (spt_…) scoped to at least the order amount in USD. For an order created with recipients, this pays for the whole group: scope the token to batch.price.

What the agent gets back

Both create tools return a sentence telling the agent what to do next, followed by the order as JSON:
With recipients, the result also carries batch (the group: count, url, one checkout_url and the total price) and orders (one per recipient). The top-level fields describe the first recipient’s order.
The server also sends instructions at connection time telling the agent to confirm addresses and wording with the user before creating an order.