Skip to main content

API & Webhooks - FAQs

Does thanks.io have an API?​

Yes. thanks.io provides a REST API (v2) for sending mailers, managing mailing lists and recipients, handling orders, configuring webhooks, and more. The full OpenAPI spec is at docs.thanks.io.

How do I authenticate API requests?​

Personal access token (single-account scripts) or OAuth 2.0 (multi-tenant applications). Both use a Bearer token in the Authorization header.

Is there a sandbox?​

Yes. API Testing Mode lets you submit orders without generating real mail or per-piece charges - orders sent via the API or Zapier are cancelled automatically. Turn on Test Mode in the API Settings card under Settings → API Access, then click Save Changes. Turn it off before going live.

Buying leads is not an order, so a Radius Search is still charged for while test mode is on. To keep a test run cheap, a Radius Search bought via the API or Zapier is limited to 5 records per purchase while test mode is enabled; a larger record_count is refused with HTTP 422 before anything is bought or charged. See API Test Mode.

warning

Make sure API Testing Mode is off before you want to send real mail, or to buy a full Radius Search list through the API.

Can I check what an order will cost before sending it?​

Yes. Every send endpoint has a matching estimate endpoint: post the same request body to /api/v2/estimate/{mailer-type} instead of /api/v2/send/{mailer-type}. The request is validated exactly as a send would be, and the response gives the total in cents, a US / international / extra-page / gift card breakdown, your current balance, and whether it covers the order. Nothing is charged, printed, or mailed, and no order is created. See Estimating an Order's Cost.

Can I send a creative through the API?​

Yes. Pass creative_id to any /send/* or /estimate/* endpoint and the piece is sent exactly as the creative is saved: its front, message, handwriting, and background. Don't combine it with template, front image, message, handwriting, background, or PDF parameters; a request that does is rejected with 422. Only qrcode_url and, for letters, additional_pages_url can be added. The creative must belong to your account, be ready to send, and match the endpoint's mail type and postcard size.

Copy a creative's ID from its menu in Creatives (Copy creative ID). GET /creatives and GET /creatives/{id} list and read your creatives; creatives are designed in the dashboard. See Finding template IDs.

How do I check whether a gift card was redeemed?​

List the order's items with GET /api/v2/orders/{order}/items. Each gift card item includes redeemed_at and invalidated_at next to its brand and amount; a null date means that hasn't happened. The redemption code is never returned.

Can I invalidate a gift card through the API?​

Yes, as long as it hasn't been redeemed. Send PUT or PATCH to /api/v2/order-items/{orderItem}/invalidate-giftcard. The card can no longer be redeemed, and the response is the updated order item. A card that's already redeemed or invalidated, or an item that isn't a gift card, returns 422. See Invalidating an unredeemed gift card.

What webhook events are available?​

Order Status Change, Order Item Status Change, Order Item Delivered, and QR Code Scans.

Are webhooks guaranteed?​

Webhooks are delivered at-least-once. Make your webhook consumer idempotent (safe to process the same event more than once) and deduplicate on event ID.

How do I test my webhooks?​

Go to Settings → Webhooks and choose Send Test on the webhook, or use a tool like webhook.site to inspect payloads.

What is the thanks.io MCP server?​

There are two:

  • The thanks.io MCP server at https://mcp.thanks.io/mcp connects an AI assistant (Claude, ChatGPT, Cursor, VS Code, and others) to your account, so you can check results, build lists, design and list creatives, and send mail by chatting. thanks.io tells the assistant to show you a preview and wait for your approval before every send. To connect, click Integrations & API in the sidebar, then Connect Your AI on the AI Assistants card. See Integrations Overview.
  • The documentation MCP server at https://docs.thanks.io/mcp provides LLM-friendly access to the API documentation for AI assistants and developer tools that support the Model Context Protocol.