Thanks io

Learn how to use Thanks io with Composio

Overview

SLUG: THANKS_IO

Description

thanks.io is a direct mail automation platform that enables users to send personalized postcards, letters, and notecards with handwritten fonts.

Authentication Details

generic_api_key
stringRequired

Connecting to Thanks io

Create an auth config

Use the dashboard to create an auth config for the Thanks io toolkit. This allows you to connect multiple Thanks io accounts to Composio for agents to use.

1

Select App

Navigate to [Thanks io](https://platform.composio.dev/marketplace/Thanks io).

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Thanks io Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4thanks_io_auth_config_id = "ac_YOUR_THANKS_IO_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": user_api_key}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Thanks io for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, thanks_io_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the [Thanks io toolkit’s playground](https://app.composio.dev/app/Thanks io)

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["THANKS_IO"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Add Recipient to Mailing List

Description

Tool to add a new recipient to a mailing list. use after confirming recipient and list ids.

Action Parameters

address
stringRequired
address2
string
city
stringRequired
country
stringRequired
email
mailing_list
stringRequired
name
stringRequired
phone
string
postal_code
stringRequired
province
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Mailing List

Description

Tool to create a new mailing list. use when you need to group contacts under a fresh list before adding recipients.

Action Parameters

description
string
name
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Mailing List

Description

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-426614174000".

Action Parameters

list_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Recipient from Mailing List

Description

Tool to remove a recipient from a mailing list. use after confirming the recipient's id.

Action Parameters

recipient_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Sub-Account

Description

Tool to delete a specific sub-account by id. use when you need to remove an existing sub-account. confirm the id before calling.

Action Parameters

id
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Execute Stored Send

Description

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.

Action Parameters

send_type
stringRequired
uuid
Required

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Handwriting Styles

Description

Tool to retrieve available handwriting styles. use when selecting a style for handwritten personalization.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Image Templates

Description

Tool to retrieve a list of available image templates. use when you need to browse or select a template for mailings.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Mailing Lists

Description

Tool to list all mailing lists. use when you need to fetch existing lists before managing recipients.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Message Templates

Description

Tool to list available message templates. use when selecting a template for a mailing.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Orders

Description

Tool to list recent orders. use after placing orders to fetch the latest history, optionally filtering by sub-account or limiting the result count.

Action Parameters

limit
integer
sub_account_id
integer

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Search Orders by Recipient Street Address

Description

Tool to search orders by recipient street address. use when you need to find all orders sent to a specific street address.

Action Parameters

address
stringRequired
page
integerDefaults to 1
per_page
integerDefaults to 50

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Search Orders by Recipient Full Name

Description

Tool to search orders by recipient full name. use when you need to find all orders sent to a specific recipient.

Action Parameters

full_name
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Order Summary Statistics

Description

Tool to retrieve order summary statistics for a date range. use when analyzing order volume and value filtered by type, status, or date range.

Action Parameters

end_date
string
start_date
string
status
string
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Preview letter send

Description

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.

Action Parameters

additional_pages_url
string
front_image_url
stringRequired
handwriting_style
integer
mailing_lists
array
message
string
preview
booleanRequired
return_address
string
return_address2
string
return_city
string
return_name
string
return_postal_code
string
return_state
string

Action Response

code
integerRequired
data
objectRequired
error
string
message
stringRequired
success
booleanRequired
successful
booleanRequired

Tool Name: Preview Notecard

Description

Tool to preview a notecard send. use when you need front and back images before placing an actual notecard order.

Action Parameters

handwriting_style
integerRequired
image_template
integerRequired
message
stringRequired
preview
booleanRequired
recipients
arrayRequired

Action Response

code
integerRequired
data
objectRequired
error
string
message
stringRequired
success
booleanRequired
successful
booleanRequired

Tool Name: Preview Postcard

Description

Tool to preview a postcard send. use when you need front and back images before placing an order.

Action Parameters

front_image_url
handwriting_color
string
handwriting_style
string
image_template
string
mailing_lists
array
message
string
message_template
string
preview
booleanRequired
qrcode_url
recipients
array
size
stringDefaults to 4x6

Action Response

code
integerRequired
data
objectRequired
error
string
message
stringRequired
success
booleanRequired
successful
booleanRequired

Tool Name: Preview Windowless Letter

Description

Tool to preview a windowless letter send. use when you need a pdf preview of the cover-only letter before placing an order.

Action Parameters

additional_pages_url
front_image_url
Required
handwriting_color
string
handwriting_style
string
message
string
message_template
string
preview
booleanRequired
recipients
arrayRequired

Action Response

code
integerRequired
data
objectRequired
error
string
message
stringRequired
success
booleanRequired
successful
booleanRequired

Tool Name: Proof Postcard

Description

Tool to generate a pdf proof of a postcard's front and back. use when you need a preview pdf before sending the final postcard.

Action Parameters

back_image_html_content
string
back_image_html_url
back_image_url
custom_background_image
front_image_html_content
string
front_image_html_url
front_image_url
handwriting_color
string
handwriting_style
integer
message
string
nostamp
boolean
qrcode_url
return_address
string
return_address2
string
return_city
string
return_name
string
return_postal_code
string
return_state
string
size
stringDefaults to 4x6
to_address
stringRequired
to_address2
string
to_city
stringRequired
to_country
stringRequired
to_name
stringRequired
to_postal_code
stringRequired
to_state
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Multiple Recipients

Description

Tool to create multiple recipients at once in a mailing list. use when batching recipient additions for efficiency.

Action Parameters

list_id
stringRequired
recipients
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Recipient by Address

Description

Tool to delete a recipient by address and postal code. use when you need to remove a recipient without their id.

Action Parameters

address
stringRequired
postal_code
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Recipient Details

Description

Tool to get details for a specific recipient by id. use to verify a recipient’s full address and custom fields.

Action Parameters

recipient_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Search Recipients by Email

Description

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,3]."

Action Parameters

email
stringRequired
limit
integer
mailing_list_ids
arrayRequired

Action Response

current_page
integerRequired
data
arrayRequired
error
string
first_page_url
stringRequired
from
integerRequired
last_page
integerRequired
last_page_url
stringRequired
next_page_url
string
path
stringRequired
per_page
integerRequired
prev_page_url
string
successful
booleanRequired
to
integerRequired
total
integerRequired

Tool Name: Update Recipient

Description

Tool to update existing recipient details by recipient id. use when modifying recipient data after confirming the recipient exists.

Action Parameters

address
string
address2
string
city
string
country
string
custom1
string
custom2
string
custom3
string
custom4
string
email
name
string
phone
string
postal_code
string
province
string
recipient_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send Postcard

Description

Tool to send a customized postcard. use when you need to dispatch a physical postcard with a chosen image and handwritten message.

Action Parameters

custom_background_image
email_additional
front_image_url
handwriting_color
string
handwriting_style
string
image_template
string
mailing_lists
array
message
string
message_template
string
qrcode_url
radius_search
object
recipients
array
return_address
object
send_standard_mail
boolean
size
stringDefaults to 4x6
sub_account
string
use_custom_background
boolean

Action Response

data
object
error
string
message
string
status
string
successful
booleanRequired

Tool Name: Stored Send Notecard

Description

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.

Action Parameters

custom_background_image
email_additional
front_image_url
Required
handwriting_color
handwriting_style
string
message
stringRequired
qrcode_url
recipients
arrayRequired
send_standard_mail
boolean
sub_account
string
use_custom_background
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Stored Send Postcard

Description

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.

Action Parameters

custom_background_image
string
front_image_url
string
handwriting_color
string
handwriting_style
string
image_template
string
mailing_lists
array
message
string
message_template
string
preview
boolean
qrcode_url
string
recipients
array
size
stringDefaults to 4x6

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Stored Send Windowless Letter

Description

Tool to create a stored send for a windowless letter. use when you need to prepare a letter order for later execution.

Action Parameters

front_image_url
Required
handwriting_style
integerRequired
message
stringRequired
recipients
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Sub-Account

Description

Tool to create a new sub-account. use when you need to manage separate profiles with distinct return addresses and settings.

Action Parameters

return_address
stringRequired
return_address2
string
return_city
stringRequired
return_name
stringRequired
return_postal_code
stringRequired
return_state
stringRequired
title
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Sub Accounts

Description

Tool to list all available sub-accounts. use when you need to select a sub-account for operations requiring a sub-account context.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Sub Account Details

Description

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.

Action Parameters

sub_account_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Sub-Account

Description

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.

Action Parameters

return_address
string
return_address2
string
return_city
string
return_name
string
return_postal_code
string
return_state
string
sub_account_id
stringRequired
title
string

Action Response

data
objectRequired
error
string
successful
booleanRequired