# Handwrytten — how to use (mcp.ai)

Connect your Handwrytten account and use 48 tools for marketing automation straight from your AI agent. Connect with your own API key. Automate your handwritten correspondence. Send real notes with your message written in pen by robots.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_handwrytten?ms=1787293560000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `handwrytten_add_recipient`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/handwrytten`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/handwrytten/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/handwrytten/add/recipient` — Tool to add a recipient address to the user's addressbook in Handwrytten. Use when you need to store a new recipient for sending handwritten cards.
  - body: { zip: string, city: string, name?: string, state?: string, address1: string, address2?: string, birthday?: string, last_name?: string, country_id: string, first_name?: string, validate_address?: boolean }
- `POST https://api.mcp.ai/api/handwrytten/calculate/order/taxes` — Tool to calculate taxes for Handwrytten basket orders. Use without any parameters for basket orders, or optionally provide order details to calculate taxes for a specific order (experimental).
  - body: { card_id?: integer, insert_id?: integer, address_id?: integer, denomination_id?: integer }
- `POST https://api.mcp.ai/api/handwrytten/check/auth` — Tool to verify API key authentication validity for Handwrytten. Use when you need to test if the API credentials are valid and properly configured.
- `POST https://api.mcp.ai/api/handwrytten/clear/basket` — Tool to clear all items from the shopping basket. Use when you need to empty the basket and remove all pending items before starting a new order or canceling the current selection.
- `POST https://api.mcp.ai/api/handwrytten/create/template` — Tool to create a new template for the current user. Use when you need to save a new message template for sending handwritten cards.
  - body: { name: string, message: string }
- `POST https://api.mcp.ai/api/handwrytten/create/user/address` — Tool to create a new user address in Handwrytten. Use when adding a new return address to a user's profile for sending handwritten cards.
  - body: { zip: string, city: string, name?: string, state?: string, default?: boolean, address1: string, address2?: string, last_name?: string, country_id: string, first_name?: string, business_name?: string, validate_address?: boolean }
- `POST https://api.mcp.ai/api/handwrytten/delete/custom/image` — Tool to delete a custom image/logo from Handwrytten. Use when you need to remove a previously uploaded custom image or logo from your account.
  - body: { image_id: integer }
- `POST https://api.mcp.ai/api/handwrytten/delete/recipient` — Tool to delete one or more recipient addresses from user's profile. Use when you need to remove saved recipient addresses. Provide either address_id for single deletion or address_ids for bulk deletio
  - body: { address_id?: integer, address_ids?: integer[] }
- `POST https://api.mcp.ai/api/handwrytten/delete/template` — Tool to delete a user's template by its ID. Use when you need to remove a saved template from the user's account.
  - body: { template_id: integer }
- `POST https://api.mcp.ai/api/handwrytten/get/basket/all/new` — Tool to retrieve the user's basket using the new method. Use when you need to fetch the current state of the shopping basket with all items, billing information, and totals.
- `POST https://api.mcp.ai/api/handwrytten/get/basket/count` — Tool to retrieve the count of items currently in the basket. Use when you need to check how many items are in the shopping basket before proceeding with checkout or additional operations.
- `POST https://api.mcp.ai/api/handwrytten/get/basket/item` — Tool to retrieve a basket item by its ID from Handwrytten. Use when you need to get details of a specific basket item.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/handwrytten/get/card/details` — Tool to get detailed information about a specific card in the Handwrytten catalog. Use when you need comprehensive details about a card including pricing, dimensions, images, and customization options
  - body: { lowres?: boolean, card_id: integer }
- `POST https://api.mcp.ai/api/handwrytten/get/list/addresses` — Tool to retrieve a list of all addresses associated with the user's account. Use when you need to view or select from saved addresses for sending handwritten cards.
- `POST https://api.mcp.ai/api/handwrytten/get/random/cards` — Tool to retrieve random cards from Handwrytten. Use when you need to get a random selection of greeting cards from the Handwrytten catalog.
  - body: { html?: boolean, card_number?: integer, orientation?: string }
- `POST https://api.mcp.ai/api/handwrytten/get/template/details` — Tool to get detailed information about a card text template in the Handwrytten catalog. Use when you need to view the template message content and details.
  - body: { template_id: integer }
- `POST https://api.mcp.ai/api/handwrytten/get/user` — Tool to retrieve information about the currently authenticated user. Use when you need to fetch user profile details, account information, or verify authentication status.
- `POST https://api.mcp.ai/api/handwrytten/get/user/address` — Tool to retrieve the authenticated user's address and billing information. Use when you need to access user profile address details.
- `POST https://api.mcp.ai/api/handwrytten/list/basket/orders/grouped` — Tool to list all basket orders grouped by basket. Use when you need to retrieve all items currently in the user's basket or review pending orders.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/handwrytten/list/baskets` — Tool to retrieve a list of user's past baskets. Use when you need to view historical basket information including orders, recipients, and totals.
  - body: { page?: integer }
- `POST https://api.mcp.ai/api/handwrytten/list/cards` — Tool to retrieve a list of available Handwrytten cards with optional filtering and pagination. Use when browsing card catalog or searching for specific card types.
  - body: { page?: integer, lowres?: boolean, category_id?: integer, with_images?: boolean }
- `POST https://api.mcp.ai/api/handwrytten/list/categories` — Tool to retrieve the list of available card categories from Handwrytten. Use when you need to display category options or filter cards by category.
- `POST https://api.mcp.ai/api/handwrytten/list/countries` — Tool to retrieve the list of countries available in Handwrytten. Use when you need to get available countries for sending handwritten cards.
- `POST https://api.mcp.ai/api/handwrytten/list/credit/cards` — Tool to list all credit cards associated with the Handwrytten account. Use when you need to retrieve stored payment methods and billing information.
- `POST https://api.mcp.ai/api/handwrytten/list/fonts` — Tool to retrieve the list of available handwriting fonts. Use when you need to display font options or select a font for a handwritten message.
- `POST https://api.mcp.ai/api/handwrytten/list/fonts/for/customizer` — Tool to list fonts available for use with the card customizer. Use when you need to retrieve available font options for customizing handwritten cards.
- `POST https://api.mcp.ai/api/handwrytten/list/gcards` — Tool to retrieve the list of available gift cards with their denominations and pricing. Use when you need to see what gift card options are available for purchase through the Handwrytten API.
- `POST https://api.mcp.ai/api/handwrytten/list/images` — Tool to retrieve a list of custom user images uploaded to Handwrytten. Use when you need to browse or manage custom cover images or logos.
  - body: { type?: string }
- `POST https://api.mcp.ai/api/handwrytten/list/inserts` — Tool to retrieve a list of available inserts from Handwrytten. Use when you need to view all inserts that can be included with handwritten cards.
- `POST https://api.mcp.ai/api/handwrytten/list/orders` — Tool to retrieve a list of user's past orders from Handwrytten. Use when you need to view order history or check the status of previously placed orders.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/handwrytten/list/orders/grouped` — Tool to retrieve the user's order history grouped by basket. Use when you need to view or analyze past orders.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/handwrytten/list/past/orders` — Tool to retrieve a list of user's past orders from Handwrytten API. Use when you need to view order history or check the status of previously placed orders.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/handwrytten/list/recipients` — Tool to retrieve a list of recipient addresses that the user has previously saved. Use when you need to view or select from saved recipient addresses for sending handwritten cards.
- `POST https://api.mcp.ai/api/handwrytten/list/signatures` — Tool to retrieve the list of available signatures for use in card orders. Use when you need to display signature options or select a signature for a handwritten message.
- `POST https://api.mcp.ai/api/handwrytten/list/states` — Tool to retrieve the list of states/provinces available in Handwrytten. Use when you need to get available states for addressing handwritten cards.
  - body: { country_id?: integer }
- `POST https://api.mcp.ai/api/handwrytten/list/template/categories` — Tool to retrieve the list of available template categories from Handwrytten. Use when you need to display template category options or filter templates by category.
- `POST https://api.mcp.ai/api/handwrytten/list/templates` — Tool to retrieve a list of card text templates from Handwrytten. Use when you need to display available templates or filter templates by category.
  - body: { category_id?: integer }
- `POST https://api.mcp.ai/api/handwrytten/logout` — Tool to logout user from Handwrytten application. Use when you need to terminate the current user session and invalidate the authentication token.
- `POST https://api.mcp.ai/api/handwrytten/place/basket` — Tool to add an order to the basket in Handwrytten. Use when you need to create a new handwritten card order with specified recipients, card design, message, and delivery details. The order can be plac
  - body: { font?: string, wishes?: string, card_id?: integer, message?: string, for_free?: boolean, quantity?: integer, addresses?: object[], date_send?: string, font_size?: integer, insert_id?: integer, address_id?: integer, address_ids?: integer[], coupon_code?: string, signature_id?: integer, signature2_id?: integer, auto_font_size?: boolean, check_quantity?: boolean, denomination_id?: integer, return_address_id?: integer }
- `POST https://api.mcp.ai/api/handwrytten/register/user` — Tool to register a new Handwrytten user account. Use when creating a new user with email and password. Sends activation email to user; user status is not_active until email is confirmed.
  - body: { fname: string, lname: string, login: string, silent?: boolean, fullname?: string, password: string, silent_add?: boolean, discount_code?: string, password_confirmation: string }
- `POST https://api.mcp.ai/api/handwrytten/request/reset/password` — Tool to request a password reset email for a Handwrytten account. Use when a user needs to reset their password and requires an email with reset instructions. The API will send an email with a passwor
  - body: { login: string, g_recaptcha_response: string }
- `POST https://api.mcp.ai/api/handwrytten/set/default/address` — Tool to set a default return address for the user in Handwrytten. Use when you need to designate a specific address as the default return address for sending handwritten cards.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/handwrytten/set/test/mode` — Tool to set test mode for the current Handwrytten user. Use when you need to enable or disable test mode for testing purposes. When enabled, cards will not be sent and money will be returned to the cr
  - body: { test_mode: integer }
- `POST https://api.mcp.ai/api/handwrytten/update/basket` — Tool to update an existing basket item in Handwrytten. Use when you need to modify card details, recipient addresses, messages, or other basket item properties.
  - body: { id: integer, font?: string, wishes?: string, card_id?: integer, message?: string, for_free?: boolean, quantity?: integer, addresses?: object[], date_send?: string, font_size?: integer, insert_id?: integer, address_id?: integer, couponCode?: string, address_ids?: integer[], signature_id?: integer, signature2_id?: integer, auto_font_size?: boolean, check_quantity?: boolean, denomination_id?: integer, return_address_id?: integer }
- `POST https://api.mcp.ai/api/handwrytten/update/billing/info` — Tool to update user billing information (country, zip, address) for tax calculations in Handwrytten. Use when updating billing address details for accurate tax computation.
  - body: { zip: string, address: string, country_id: integer }
- `POST https://api.mcp.ai/api/handwrytten/update/recipient` — Tool to update a recipient address in the user's addressbook in Handwrytten. Use when you need to modify an existing recipient's address details.
  - body: { zip: string, city: string, name?: string, state?: string, address1: string, address2?: string, birthday?: string, last_name?: string, address_id: integer, country_id: string, first_name?: string, business_name?: string, validate_address?: boolean }
- `POST https://api.mcp.ai/api/handwrytten/update/template` — Tool to update an existing user template in Handwrytten. Use when you need to modify a template's name or message content.
  - body: { name: string, message: string, template_id: integer }
- `POST https://api.mcp.ai/api/handwrytten/upload/custom/logo` — Tool to upload a custom image (logo or cover) to Handwrytten for use with custom cards. Use when you need to add a custom logo or cover image that can be referenced in future card creation requests.
  - body: { file: object, type?: string }

## Example prompts
- "What can I do in Handwrytten?"
- "Show me a summary of my Handwrytten account"

## More
- Page: https://mcp.ai/handwrytten
- Agent spec (llms.txt): https://mcp.ai/handwrytten/llms.txt
- Postman collection: https://mcp.ai/handwrytten/postman.json