# Handwrytten

Automate your handwritten correspondence. Send real notes with your message written in pen by robots.

- **Category:** marketing automation
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 48
- **Triggers:** 0
- **Slug:** `HANDWRYTTEN`
- **Version:** 20260307_00

## Tools

### Add Recipient

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `zip` | string | Yes | ZIP or postal code. Required for recipient. |
| `city` | string | Yes | City name. Required for recipient. |
| `name` | string | No | Full name or company name if different from first_name/last_name. |
| `state` | string | No | State or province code (e.g., 'NY', 'CA'). |
| `address1` | string | Yes | Primary street address line. Required for recipient. |
| `address2` | string | No | Secondary street address line (apartment, suite, etc.). |
| `birthday` | string | No | Recipient's birthday in MM/DD/YYYY format. |
| `last_name` | string | No | Recipient's last name. |
| `country_id` | string | Yes | Country identifier. Use '1' for USA. Required for recipient. |
| `first_name` | string | No | Recipient's first name. |
| `validate_address` | boolean | No | If true, validate the address before adding. Default: false. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Calculate Order Taxes

**Slug:** `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).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `card_id` | integer | No | The id of the card you want to send |
| `insert_id` | integer | No | The insert id for the order. Only if card_id is present |
| `address_id` | integer | No | The id of the address, required if card_id is present |
| `denomination_id` | integer | No | Optional. Use if sending a gift card. Only if card_id is present |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Check Authentication

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Clear Basket

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Template

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name of the template to create |
| `message` | string | Yes | Message content for the template |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create User Address

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `zip` | string | Yes | ZIP or postal code (required) |
| `city` | string | Yes | City name (required) |
| `name` | string | No | Full name (alternative to first_name and last_name) |
| `state` | string | No | State or province code (required for US and Canada addresses). Use two-letter state abbreviation. |
| `default` | boolean | No | Set this return address as default |
| `address1` | string | Yes | Street address (required) |
| `address2` | string | No | Additional address information like apartment, suite, unit number |
| `last_name` | string | No | Last name (required if first_name is not present) |
| `country_id` | string | Yes | Country ID (required if country is not present). Use 1 for United States. |
| `first_name` | string | No | First name (required if last_name is not present) |
| `business_name` | string | No | Business name if this is a business address |
| `validate_address` | boolean | No | Whether to validate the address |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Custom Image

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image_id` | integer | Yes | The ID of the custom image to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Recipient Address

**Slug:** `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 deletion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address_id` | integer | No | The unique identifier of a single recipient address to delete. Provide either address_id (for single deletion) or address_ids (for bulk deletion), but not both. Use this when deleting one recipient at a time. |
| `address_ids` | array | No | A list of recipient address identifiers to delete in bulk. Provide either address_id (for single deletion) or address_ids (for bulk deletion), but not both. Use this when deleting multiple recipients at once. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Template

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | integer | Yes | The unique identifier of the template to delete |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Basket (New Method)

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Basket Count

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Basket Item

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Basket item id (basket_id). The unique identifier for the basket item to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Card Details

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `lowres` | boolean | No | Optional flag to request low-resolution images. When true, returns smaller image URLs to reduce bandwidth. |
| `card_id` | integer | Yes | The unique identifier of the card to retrieve details for. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get List of Addresses

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Random Cards

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `html` | boolean | No | If true, the API will render HTML instead of JSON. Set to false or omit for JSON response. |
| `card_number` | integer | No | Number of random cards to retrieve. If not specified, the API will return a default number of cards. |
| `orientation` | string ("L" | "P" | "F") | No | Orientation options for cards. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Template Details

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | integer | Yes | The unique identifier of the template to retrieve details for. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Current User Info

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get User Address

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Basket Orders Grouped

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Past Baskets

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number, numeration starts with 1, 50 items per page. If not set, 250 items are returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Cards

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number for pagination, starting from 0. Used to retrieve different pages of card results. |
| `lowres` | boolean | No | Request low-resolution images instead of full resolution. Set to true for smaller image files. |
| `category_id` | integer | No | Filter cards by category ID. If not provided, returns cards from all categories. |
| `with_images` | boolean | No | Include card images in the response. Set to true to retrieve card image URLs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Categories

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Countries

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Credit Cards

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Fonts

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Fonts for Customizer

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Gift Cards

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Custom User Images

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string ("cover" | "logo") | No | Enum for image types supported by Handwrytten. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Inserts

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Orders

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Orders Grouped

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Past Orders

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Recipients

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Signatures

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List States

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `country_id` | integer | No | Country ID to filter states by. If not provided, returns states for all countries. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Template Categories

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Templates

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category_id` | integer | No | Filter templates by category ID. If not provided, returns templates from all categories. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Logout User

**Slug:** `HANDWRYTTEN_LOGOUT`

Tool to logout user from Handwrytten application. Use when you need to terminate the current user session and invalidate the authentication token.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Place Order in Basket

**Slug:** `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 placed immediately or scheduled for future delivery.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `font` | string | No | Font ID for handwriting style. Examples: hwJeff, astDunn, hwMercy. |
| `wishes` | string | No | Wishes text as part of the signature block in the letter. |
| `card_id` | integer | No | The ID of the card design to use for the order. |
| `message` | string | No | General message to include in all cards. Can be overridden per address in the addresses list. |
| `for_free` | boolean | No | Whether this order should be placed for free (requires appropriate permissions). |
| `quantity` | integer | No | Quantity of identical cards to send. Use when sending the same card to multiple recipients. |
| `addresses` | array | No | List of recipient addresses with their details. Required if address_ids is not provided. Each address can have its own message. |
| `date_send` | string | No | Scheduled send date and time in YYYY-MM-DD HH:MM:SS format. Leave empty for immediate sending. |
| `font_size` | integer | No | Font size for the handwriting. Typically ranges from 8 to 16. |
| `insert_id` | integer | No | ID of an insert to include with the card (e.g., business card, flyer). |
| `address_id` | integer | No | Single address ID for sending to one recipient. |
| `address_ids` | array | No | List of existing address IDs from Handwrytten address book. Required if addresses is not provided. |
| `coupon_code` | string | No | Coupon code to apply to this order for discounts. |
| `signature_id` | integer | No | Signature ID for the wishes block of the message. |
| `signature2_id` | integer | No | Signature ID for the main message block. |
| `auto_font_size` | boolean | No | Whether to automatically adjust font size to fit the message on the card. |
| `check_quantity` | boolean | No | Whether to check if cards and inserts are in stock. Returns error if insufficient quantity available. |
| `denomination_id` | integer | No | Denomination ID for gift cards, if applicable. |
| `return_address_id` | integer | No | ID of the return address to use. If not provided, the default return address will be used. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Register User

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fname` | string | Yes | First name of the user. |
| `lname` | string | Yes | Last name of the user. |
| `login` | string | Yes | Email address for the new user account. This will be used as the login credential. |
| `silent` | boolean | No | If true, the registration notification email will not be sent to the user. |
| `fullname` | string | No | Full name of the user if provided. |
| `password` | string | Yes | Password for the new user account. Must meet minimum security requirements. |
| `silent_add` | boolean | No | If true, the registration notification email will not be sent to the user. |
| `discount_code` | string | No | Discount code managed in admin area. Used to add credits/bonus credits to the user and attach user to an existing group. |
| `password_confirmation` | string | Yes | Password confirmation - must be exactly equal to the password field. Required for validation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Request Password Reset

**Slug:** `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 password reset link if the provided email exists in the system, but will return success regardless to prevent email enumeration attacks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `login` | string | Yes | Email address of the user requesting password reset. An email with password reset instructions will be sent if this email exists in the system. |
| `g_recaptcha_response` | string | Yes | Google reCAPTCHA token for security validation. This is required to prevent automated abuse of the password reset endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set Default Address

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | The unique ID of the address to set as default. This must be an existing address ID from the user's address list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set Test Mode

**Slug:** `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 credit card.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `test_mode` | integer ("0" | "1") | Yes | Test mode setting: enabled (1) to activate test mode where cards are not sent and charges are refunded, or disabled (0) to deactivate test mode and process real orders. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Basket Item

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Existing basket item ID to update (required) |
| `font` | string | No | Font style to use for the handwritten message |
| `wishes` | string | No | Wishes text to include as part of the signature in the card |
| `card_id` | integer | No | ID of the card design to use |
| `message` | string | No | The handwritten message content to include in the card |
| `for_free` | boolean | No | Mark this basket item as free (no charge) |
| `quantity` | integer | No | Number of cards to send |
| `addresses` | array | No | List of address objects for bulk updates with custom messages |
| `date_send` | string | No | Date and time to send the card (format: YYYY-MM-DD HH:MM:SS) |
| `font_size` | integer | No | Font size for the message (in points) |
| `insert_id` | integer | No | ID of an insert to include with the card |
| `address_id` | integer | No | ID of the address to use for this basket item |
| `couponCode` | string | No | Coupon code to apply to this basket item |
| `address_ids` | array | No | List of address IDs for bulk updates |
| `signature_id` | integer | No | Signature ID for the wishes block of the message |
| `signature2_id` | integer | No | Signature ID for the main block of the message |
| `auto_font_size` | boolean | No | Automatically adjust font size to fit the message |
| `check_quantity` | boolean | No | Check card quantity in stock, return 'insufficient quantity' error if low stock |
| `denomination_id` | integer | No | Gift card denomination ID (if applicable) |
| `return_address_id` | integer | No | Return address ID. If not provided, the default return address will be used |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Billing Information

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `zip` | string | Yes | ZIP or postal code for billing address (required for tax calculations) |
| `address` | string | Yes | Street address for billing (required for tax calculations) |
| `country_id` | integer | Yes | Country ID for billing address. Use 1 for United States. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Recipient

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `zip` | string | Yes | ZIP or postal code. Required for recipient update. |
| `city` | string | Yes | City name. Required for recipient update. |
| `name` | string | No | Full name or company name if different from first_name/last_name. |
| `state` | string | No | State or province code (e.g., 'FL', 'CA'). |
| `address1` | string | Yes | Primary street address line. Required for recipient update. |
| `address2` | string | No | Secondary street address line (apartment, suite, etc.). |
| `birthday` | string | No | Recipient's birthday in MM/DD/YYYY format. |
| `last_name` | string | No | Recipient's last name. Required if first_name is not present. |
| `address_id` | integer | Yes | Unique identifier of the recipient address to update. Required. |
| `country_id` | string | Yes | Country identifier. Use '1' for USA. Required for recipient update. |
| `first_name` | string | No | Recipient's first name. Required if last_name is not present. |
| `business_name` | string | No | Business name if this is a business address. |
| `validate_address` | boolean | No | If true, validate the address before updating. Default: false. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Template

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Updated name for the template (required) |
| `message` | string | Yes | Updated message content for the template (required) |
| `template_id` | integer | Yes | ID of the template to update (required) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload Custom Logo

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | The image file to upload. Supported formats: PNG, JPG, JPEG. |
| `type` | string ("cover" | "logo") | No | Type of custom image being uploaded |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |