# Thanks.io — how to use (mcp.ai)

Connect your Thanks.io account and use 29 tools for marketing automation straight from your AI agent. Connect with your own API key. thanks.io is a direct mail automation platform that enables users to send personalized postcards, letters, and notecards with handwritten fonts.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_thanks_io?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. `thanks_io_add_recipient_to_mailing_list`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/thanks_io`
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/thanks_io/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/thanks_io/add/recipient/to/mailing/list` — Tool to add a new recipient to a mailing list. Use after confirming recipient and list IDs.
  - body: { city: string, name: string, email?: string, phone?: string, address: string, country: string, address2?: string, province: string, postal_code: string, mailing_list: string }
- `POST https://api.mcp.ai/api/thanks_io/create/mailing/list` — Tool to create a new mailing list. Use when you need to group contacts under a fresh list before adding recipients.
  - body: { name: string, description: string }
- `POST https://api.mcp.ai/api/thanks_io/delete/mailing/list` — Tool to delete a mailing list. Use when you need to remove an entire mailing list by its ID. Confirm the list ID before calling. Example: "Delete the mailing list with ID 123e4567-e89b-12d3-a456-42661
  - body: { list_id: string }
- `POST https://api.mcp.ai/api/thanks_io/delete/recipient/from/mailing/list` — Tool to remove a recipient from a mailing list. Use after confirming the recipient's ID.
  - body: { recipient_id: string }
- `POST https://api.mcp.ai/api/thanks_io/delete/sub/account` — Tool to delete a specific sub-account by ID. Use when you need to remove an existing sub-account. Confirm the ID before calling.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/thanks_io/execute/stored/send` — Tool to execute a previously created stored send. Use after creating a stored send to trigger delivery. The response body is empty; success is indicated by a 200 or 204 status.
  - body: { uuid: string, send_type: string }
- `POST https://api.mcp.ai/api/thanks_io/list/handwriting/styles` — Tool to retrieve available handwriting styles. Use when selecting a style for handwritten personalization.
- `POST https://api.mcp.ai/api/thanks_io/list/image/templates` — Tool to retrieve a list of available image templates. Use when you need to browse or select a template for mailings.
  - body: { page?: integer, items_per_page?: integer, sub_account_id?: integer }
- `POST https://api.mcp.ai/api/thanks_io/list/mailing/lists` — Tool to list all mailing lists. Use when you need to fetch existing lists before managing recipients.
- `POST https://api.mcp.ai/api/thanks_io/list/message/templates` — Tool to list available message templates. Use when selecting a template for a mailing.
  - body: { items_per_page?: integer, sub_account_id?: integer }
- `POST https://api.mcp.ai/api/thanks_io/mailing/lists/buy/radius/search` — Tool to buy or append a radius search mailing list based on address and radius. Use when you need targeted mailing lists around a specified address.
  - body: { address: string, append_data?: boolean, postal_code: string, record_count: integer, record_types?: string, include_condos?: boolean, mailing_list_id?: integer, use_property_owner?: boolean }
- `POST https://api.mcp.ai/api/thanks_io/order/preview/letter` — Tool to preview a letter send as PDF. Use when you need to confirm letter content before placing the final order. Returns PDF preview URLs.
  - body: { message?: string, preview: boolean, recipients?: object[], return_city?: string, return_name?: string, return_state?: string, mailing_lists?: integer[], return_address?: string, return_address2?: string, additional_pages?: string, handwriting_style?: integer, return_postal_code?: string, custom_background_image?: string }
- `POST https://api.mcp.ai/api/thanks_io/order/preview/notecard` — Tool to preview a notecard send. Use when you need front and back images before placing an actual notecard order.
  - body: { message: string, preview: boolean, recipients: object[], image_template: integer, handwriting_style: integer }
- `POST https://api.mcp.ai/api/thanks_io/order/preview/windowless/letter` — Tool to preview a windowless letter send. Use when you need a PDF preview of the cover-only letter before placing an order.
  - body: { message?: string, preview: boolean, recipients: object[], front_image_url: string, message_template?: string, handwriting_color?: string, handwriting_style?: string, additional_pages_url?: string }
- `POST https://api.mcp.ai/api/thanks_io/orders/list` — Tool to list recent orders. Use after placing orders to fetch the latest history, optionally filtering by sub-account or limiting the result count.
  - body: { items_per_page?: integer, sub_account_id?: integer }
- `POST https://api.mcp.ai/api/thanks_io/orders/search/by/address` — Tool to search orders by recipient street address. Use when you need to find all orders sent to a specific street address.
  - body: { page?: integer, address: string, per_page?: integer }
- `POST https://api.mcp.ai/api/thanks_io/recipients/create/multi` — Tool to create multiple recipients at once in a mailing list. Use when batching recipient additions for efficiency.
  - body: { list_id: string, recipients: object[] }
- `POST https://api.mcp.ai/api/thanks_io/recipients/delete/by/address` — Tool to delete a recipient by address and postal code. Use when you need to remove a recipient without their ID.
  - body: { address: string, postal_code: string }
- `POST https://api.mcp.ai/api/thanks_io/recipients/get/details` — Tool to get details for a specific recipient by ID. Use to verify a recipient’s full address and custom fields.
  - body: { recipient_id: string }
- `POST https://api.mcp.ai/api/thanks_io/recipients/search/by/email` — Tool to search recipients by email across mailing lists. Use when you need to find all recipients matching an email in specific lists. Example: "Find recipients with email test@test.com in lists [1,2,
  - body: { email: string, limit?: integer, mailing_list_ids: integer[] }
- `POST https://api.mcp.ai/api/thanks_io/recipients/update` — Tool to update existing recipient details by recipient ID. Use when modifying recipient data after confirming the recipient exists.
  - body: { city?: string, name?: string, email?: string, phone?: string, address?: string, country?: string, custom1?: string, custom2?: string, custom3?: string, custom4?: string, address2?: string, province?: string, postal_code?: string, recipient_id: string }
- `POST https://api.mcp.ai/api/thanks_io/send/postcard` — Tool to send a customized postcard. Use when you need to dispatch a physical postcard with a chosen image and handwritten message.
  - body: { size?: string, message?: string, preview?: boolean, qrcode_url?: string, recipients?: object[], return_city?: string, return_name?: string, sub_account?: string, return_state?: string, mailing_lists?: string[], radius_search?: object, image_template?: string, return_address?: string, front_image_url?: string, return_address2?: string, email_additional?: string, message_template?: string, handwriting_color?: string, handwriting_style?: string, return_postal_code?: string, send_standard_mail?: boolean, use_custom_background?: boolean, custom_background_image?: string }
- `POST https://api.mcp.ai/api/thanks_io/stored/send/notecard` — Tool to create a stored send for a notecard. Use when you need to schedule mailing of a personalized notecard at a later time after preparing payload.
  - body: { message: string, qrcode_url?: string, recipients: object[], sub_account?: string, front_image_url: string, email_additional?: string, handwriting_color?: string, handwriting_style?: string, send_standard_mail?: boolean, use_custom_background?: boolean, custom_background_image?: string }
- `POST https://api.mcp.ai/api/thanks_io/stored/send/postcard` — Tool to create a stored send for a postcard. Use when you need to prepare and schedule postcard orders for later execution; returns a URL to finalize and send.
  - body: { size?: string, message?: string, preview?: boolean, qrcode_url?: string, recipients?: object[], mailing_lists?: string[], image_template?: string, front_image_url?: string, message_template?: string, handwriting_color?: string, handwriting_style?: string, custom_background_image?: string }
- `POST https://api.mcp.ai/api/thanks_io/stored/send/windowless/letter` — Tool to create a stored send for a windowless letter. Use when you need to prepare a letter order for later execution.
  - body: { message: string, recipients: object[], front_image_url: string, handwriting_style: integer }
- `POST https://api.mcp.ai/api/thanks_io/sub/accounts/create` — Tool to create a new sub-account. Use when you need to manage separate profiles with distinct return addresses and settings.
  - body: { title: string, return_city?: string, return_name?: string, return_state?: string, return_address?: string, return_address2?: string, return_postal_code?: string }
- `POST https://api.mcp.ai/api/thanks_io/sub/accounts/list` — Tool to list all available sub-accounts. Use when you need to select a sub-account for operations requiring a sub-account context.
- `POST https://api.mcp.ai/api/thanks_io/sub/accounts/show` — Tool to retrieve details for a specific sub-account by ID. Use when you need full configuration of a sub-account before performing sub-account scoped operations.
  - body: { sub_account_id: string }
- `POST https://api.mcp.ai/api/thanks_io/sub/accounts/update` — Tool to update details for a specific sub-account. Use when modifying title or return address details of a sub-account. Confirm sub-account ID before calling.
  - body: { title?: string, return_city?: string, return_name?: string, return_state?: string, return_address?: string, sub_account_id: string, return_address2?: string, return_postal_code?: string }

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

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