Skip to main content

API & Developer Documentation

The thanks.io REST API and full developer documentation - including authentication, API keys, webhooks, rate limits, code examples, and endpoint references - is hosted at:

docs.thanks.io →

Your API keys are on Settings → API & MCP Access (click your name in the top right of the dashboard, then API & MCP Access). See Generate an API Key.

Sending a creative​

The simplest way to send mail through the API is by creative. A creative is a design you saved in the dashboard: its front, message, handwriting, QR code and background travel together. Pass its creative_id to any /send/* endpoint (or /estimate/* to price it first) along with your recipients, and it sends exactly as saved. The same creative ID works in Zapier, the n8n node, HubSpot workflow actions, and AI assistants connected to the thanks.io MCP server.

Find a creative's ID in Creatives: open its ⋮ menu and choose Copy creative ID. See Finding Creative & Template IDs, and Send a creative in the API reference.

Choosing a postage class​

Every /send/* and /estimate/* endpoint takes a postage_class field: first_class, or standard for Standard Mail (also known as Marketing Mail). Leave it out to mail at your account's default class, set by Standard Mail Mode in Settings → Mail Preferences. postage_class replaces the deprecated send_standard_mail field; a request that sends both is rejected with a 422. See Postage Options.

Previewing an order​

Add "preview": true to any /send/* request to get PNG previews of the piece instead of placing the order. On the Free and Business plans, these preview images carry a DRAFT watermark; the mail you send prints without it. Professional and Enterprise previews have no watermark. To check the price instead, use /estimate/*.

What you'll find at docs.thanks.io​

  • Authentication - generating API keys, authorization headers
  • Sending mail via API - orders API, sending postcards, letters, and handwritten cards programmatically, including sending a saved creative by creative_id
  • Creatives library - listing and reading your creatives with GET /creatives and GET /creatives/{id} (read-only; creatives are designed in the dashboard)
  • Estimating an order's cost - pricing an order with the same request body before you send it, with nothing charged or mailed (walkthrough: Estimating an Order's Cost)
  • Order items - per-piece status, delivery date, scans, and failure reason for every recipient in an order, plus redemption status (redeemed_at, invalidated_at) for gift cards
  • Gift card invalidation - invalidating an unredeemed gift card on a mailed piece so it can't be redeemed (see Gift Cards)
  • Campaigns API - creating and managing campaigns via API
  • Mailing lists API - managing contact lists, adding and removing contacts
  • Templates API - retrieving template IDs, handwriting style IDs, image template and message template IDs (find them in the dashboard with Finding Creative & Template IDs)
  • Webhooks - setting up webhook delivery, easy add-to-list webhooks, webhook error troubleshooting
  • Rate limits - API rate limiting and best practices
  • Error codes - full list of API error codes and how to resolve them
  • Code examples - sample code in multiple languages (Node.js, Python, PHP, Ruby, etc.)
  • MCP server - thanks.io MCP server setup and configuration for AI integrations. In the dashboard, the AI Assistants card on Integrations & API walks you through connecting Claude, ChatGPT and other clients
  • Test mode - using API test mode (orders auto-cancel, and a Radius Search bought via API or Zapier is capped at 5 records)
  • First API request - getting started walkthrough for developers

Head to docs.thanks.io to get started.

Last updated on