Handwrytten — Send Real Handwritten Notes
You have access to the Handwrytten API, which sends real handwritten notes using robots with actual pens writing on physical cards that get mailed to recipients.
Typical Workflow
- 1. Browse options first: Call
list_cards and list_fonts to discover available card templates and handwriting styles before sending. - Send the note: Call
send_order with a card ID, font ID, message, and sender address and recipient address. If you want the sign-off on the right side of the card, include the wishes parameter with the sign-off message. - Confirm to the user: Always tell the user what card, font, and message you selected, and confirm before placing an order that costs money.
Key Tools
Sending Notes (Core)
- -
send_order — The primary tool. Sends a handwritten note. Supports single recipients (address object or saved ID) and bulk sends (array of recipients with optional per-recipient message overrides). Always call list_cards and list_fonts first. - INLINECODE7 /
list_orders — Check order status and history.
Browsing Cards & Fonts
- -
list_cards — Browse card templates. Supports filtering by category name/ID and search by name. Use list_card_categories to discover category IDs. Results are paginated (default 20/page). - INLINECODE11 — Browse handwriting styles for the order message.
- INLINECODE12 — Browse printed/typeset fonts (only needed for custom card text zones, not for order messages).
Address Book
- -
list_recipients / add_recipient / update_recipient / delete_recipient — Manage saved recipient addresses. - INLINECODE17 /
add_sender / delete_sender — Manage saved return addresses. - INLINECODE20 /
list_states — Look up supported countries and state codes.
Extras
- -
list_gift_cards — Browse gift cards to attach to orders (pass denominationId to send_order). - INLINECODE25 — Browse physical inserts (business cards, flyers) to include in orders.
- INLINECODE26 — List saved handwriting signatures.
- INLINECODE27 — Prospect mailing targets by ZIP code and radius.
Custom Cards (Advanced)
For creating custom card designs with logos, images, and printed text:
- 1.
list_custom_card_dimensions — Get available card formats (flat/folded, portrait/landscape). - INLINECODE29 — Upload a cover or logo image (JPEG/PNG/GIF via public URL).
- INLINECODE30 — Build the card design with zones (header, main, footer, back). Each zone has a
type field: set type='logo' when using a logo image, type='text' for printed text. - Use the resulting card ID with
send_order to mail it.
QR Codes
- -
create_qr_code / list_qr_codes / delete_qr_code — Manage QR codes that can be placed on custom cards. - INLINECODE38 — Browse decorative frames for QR codes.
Basket (Multi-Step Orders)
For building up multiple orders before submitting them together:
- -
basket_add_order → basket_list → INLINECODE41 - Use
send_order instead for simple single-step sends.
Important Guidelines
- - Always browse before sending. Call
list_cards and list_fonts before send_order so you use valid IDs. - Confirm before ordering. Sending a note costs money and results in a physical card being mailed. Always confirm the details with the user before calling
send_order. - Addresses require: firstName, lastName, street1, city, state, zip. Country defaults to US.
- Bulk sends: Pass an array of recipients to
send_order. Each recipient can have per-recipient message and wishes overrides. - Scheduling: Use the
dateSend parameter (YYYY-MM-DD) to schedule a future send. - Account balance: Call
get_user to check the user's credits balance.
Handwrytten — 发送真实手写便条
您可以使用 Handwrytten API，通过机器人用真实笔在实体卡片上书写，并将卡片邮寄给收件人，从而发送真实手写便条。
典型工作流程
- 1. 先浏览选项：在发送前，调用 listcards 和 listfonts 来查看可用的卡片模板和手写风格。
- 发送便条：调用 send_order，传入卡片ID、字体ID、留言内容、发件人地址和收件人地址。如果希望签名位于卡片右侧，请使用 wishes 参数传入签名内容。
- 向用户确认：始终告知用户您选择的卡片、字体和留言内容，并在下单（需付费）前进行确认。
关键工具
发送便条（核心功能）
- - sendorder — 主要工具。发送手写便条。支持单个收件人（地址对象或已保存的ID）和批量发送（收件人数组，可对每个收件人单独覆盖留言内容）。请始终先调用 listcards 和 listfonts。
- getorder / list_orders — 查看订单状态和历史记录。
浏览卡片与字体
- - listcards — 浏览卡片模板。支持按类别名称/ID筛选和按名称搜索。使用 listcardcategories 查看类别ID。结果分页显示（默认每页20条）。
- listfonts — 浏览订单留言的手写风格。
- listcustomizerfonts — 浏览印刷/排版字体（仅用于自定义卡片文字区域，不用于订单留言）。
地址簿
- - listrecipients / addrecipient / updaterecipient / deleterecipient — 管理已保存的收件人地址。
- listsenders / addsender / deletesender — 管理已保存的退件地址。
- listcountries / list_states — 查询支持的国家和州代码。
附加功能
- - listgiftcards — 浏览可附加到订单的礼品卡（通过 denominationId 参数传入 sendorder）。
- listinserts — 浏览可放入订单的实体插页（名片、传单）。
- listsignatures — 列出已保存的手写签名。
- calculatetargets — 按邮政编码和半径预估邮寄目标。
自定义卡片（高级功能）
用于创建带有Logo、图片和印刷文字的自定义卡片设计：
- 1. listcustomcarddimensions — 获取可用的卡片格式（平面/折叠、竖版/横版）。
- uploadcustomimage — 上传封面或Logo图片（通过公开URL上传JPEG/PNG/GIF格式）。
- createcustomcard — 构建卡片设计，包含多个区域（页眉、主体、页脚、背面）。每个区域都有 type 字段：使用Logo图片时设置 type=logo，使用印刷文字时设置 type=text。
- 将生成的卡片ID与 sendorder 配合使用进行邮寄。
二维码
- - createqrcode / listqrcodes / deleteqrcode — 管理可放置在自定义卡片上的二维码。
- listqrcode_frames — 浏览二维码的装饰边框。
购物篮（多步骤订单）
用于在提交前构建多个订单：
- - basketaddorder → basketlist → basketsend
- 简单的一步式发送请使用 send_order。
重要指南
- - 发送前务必先浏览。 在调用 sendorder 前先调用 listcards 和 listfonts，以确保使用有效的ID。
- 下单前先确认。 发送便条需要付费，并会实际邮寄实体卡片。在调用 sendorder 前，务必与用户确认所有细节。
- 地址要求： firstName、lastName、street1、city、state、zip。国家默认为美国。
- 批量发送： 向 sendorder 传入收件人数组。每个收件人可单独覆盖 message 和 wishes 参数。
- 定时发送： 使用 dateSend 参数（格式：YYYY-MM-DD）设置未来发送时间。
- 账户余额： 调用 getuser 查看用户的积分余额。
