To connect an AI agent to a direct mail API, create a thanks.io account, generate an API key, turn on API Testing Mode, and give your agent either the thanks.io REST endpoint (https://api.thanks.io/api/v2/send/postcard) or the MCP connector (mcp.thanks.io/MCP) so it can call thanks.io as a tool. Run one test order, confirm it appears as canceled in your order history, then switch testing mode off to mail real postcards, letters, and notecards.
Most AI tools can write a great postcard but can’t mail one. I built thanks.io to close that gap: we print, address, and mail physical mail through an API that any AI agent can call.
What does it mean to connect an AI agent to a direct mail API?
It means giving your AI agent permission and instructions to place real mail orders on your behalf. Instead of copying AI-written text into a design tool, the agent sends the recipient, message, and creative straight to the thanks.io API, and thanks.io handles printing, postage, and delivery.
What do you need before you start?
- A free thanks.io account (includes $10 in credits)
- A thanks.io API key from API Settings
- An AI agent or platform that can make web requests or use MCP connectors: Claude, ChatGPT, or an agent platform such as Zo Computer
- A return address and a postcard image or template
How do you connect an AI agent to thanks.io, step by step?
- Create your thanks.io account. Sign up at thanks.io.
- Create an API key. In API Settings, generate a personal access token. Store it as a secret or environment variable, never in a prompt or public file.
- Enable API Testing Mode. While it is on, orders submitted through the API are automatically canceled instead of mailed, so your agent can practice at no risk.
- Give the agent the docs. The thanks.io documentation is available to AI clients through a documentation MCP server at
https://docs.thanks.io/mcp, and every page has a plain-markdown version indexed at docs.thanks.io/llms.txt. Your agent can read the endpoint reference itself instead of guessing. - Send a test order. Ask the agent to submit a postcard. Under the hood it makes a request like this:
curl -X POST "https://api.thanks.io/api/v2/send/postcard" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "recipients": [{ "name": "John Doe", "address": "123 Main Street, Any Town, NY 12345" }], "message": "Hi %FIRST_NAME% - Thank you for your business!", "front_image_url": "https://cdn.thanks.io/inspiration_templates/default10.png" }' - Check the order history. The test order should show up in your thanks.io Order History and then be canceled automatically.
- Go live. Turn testing mode off. Have the agent preview each order and show you the cost before it sends.
Should an AI agent use the REST API or an MCP server?
Use the REST API when you are building an app or workflow that places orders from code. Use MCP (Model Context Protocol) when you want a chat-based AI to work with thanks.io directly: checking account performance, building mailing lists, designing creatives, previewing orders, and sending mail. MCP is a standard way for an AI to use a tool instead of only describing it. Claude and ChatGPT both support adding custom MCP connectors in their settings. See the thanks.io MCP page for the current server details.
If you want the agent to run on its own, such as checking for new leads each morning and mailing a postcard, run it on an always-on platform like Zo Computer. A chat window stops when you close the tab; a platform keeps running.
Which thanks.io API workflow should your agent use?
| Goal | Best approach |
|---|---|
| Recurring or triggered mail (new lead, birthday, new customer) | Add a recipient to a campaign. thanks.io handles the sequence. |
| One-off or on-demand postcards | Postcard order via direct send |
| Fully designed letters | PDF letter order |
| Rewards and incentives | Gift card order |
What can an AI agent do with thanks.io once it’s connected?
- Mail a handwriting-style postcard when a new lead lands in your CRM
- Send birthday, anniversary, and thank-you cards on a schedule
- Run Just Listed and Just Sold postcards to nearby neighbors for real estate
- Add QR codes so you can track who responds
- Personalize each piece using merge fields such as
%FIRST_NAME%
How do you keep an AI agent safe when it can spend money?
- Keep API Testing Mode on until the output looks right.
- Require a preview and cost check before any real send.
- Store the API key as a secret, and rotate it if it leaks.
- Limit the agent to one task, such as “mail new leads,” rather than open-ended access.
- Check your order history regularly.
Frequently asked questions
Can ChatGPT or Claude send direct mail?
Not by themselves. They can write the copy. To send, they need a connection to a mail service such as thanks.io through an MCP connector or API calls made from a platform that can run them.
Do I need to know how to code?
No. With an MCP-capable AI or an agent platform, you describe what you want in plain English and the agent makes the API calls. The code above shows what happens behind the scenes.
Is there a way to test without mailing anything?
Yes. thanks.io’s API Testing Mode cancels API orders automatically instead of mailing them.
How much does it cost to try?
New thanks.io accounts can be created free with $10 in credits. Per-piece pricing depends on the mailer type and volume, so check thanks.io for current rates.
Where can I get help integrating?
Read the thanks.io Quickstart, or schedule an API consult.
Bottom line
Connecting an AI agent to a direct mail API takes about five minutes: account, API key, testing mode, test order, go live. I built thanks.io to give your agent the one thing it lacks: the ability to put a real piece of mail in a real mailbox. Create a free account and start with a test order today.
