# Thanks.io Postcard API for Developers & AI Agents (REST API v2 & OAuth MCP Server)

> **Direct Answer Definition**: The Thanks.io Postcard API is a RESTful v2 API and hosted OAuth MCP server that lets developers and AI agents programmatically send 4×6, 6×9, and 6×11 postcards, letters, notecards, and gift cards with digital handwriting-style fonts, dynamic QR tracking webhooks, and zero minimum orders starting at $0.64/piece.

- **Canonical URL**: `https://thanks.io/postcard-api`
- **Base REST API URL**: `https://api.thanks.io/api/v2`
- **OpenAPI 3.0 Spec**: `https://thanks.io/openapi.json`
- **Developer Documentation**: `https://docs.thanks.io`
- **Hosted Product MCP Server (57 Tools, OAuth 2.0)**: `https://mcp.thanks.io/mcp`
- **Hosted Documentation MCP Server**: `https://docs.thanks.io/mcp`
- **Authentication**: `Authorization: Bearer YOUR_API_KEY` (Personal Access Tokens via `Settings -> API Access` or OAuth 2.0 for multi-tenant apps)
- **Sandbox / Test Mode**: Toggle via `Account Settings -> API Access -> Test Mode` to validate payloads and inspect mock responses without printing or billing.

---

## Quick Metrics (2026)

| Metric | Value | Notes |
| :--- | :--- | :--- |
| **Lowest 4×6 Postcard Rate** | **$0.64 / piece** | Professional Plan ($0.77 on Business, $1.18 on $0/mo Pay as you go) |
| **Platform API Access Fee** | **$0 / month** | Full REST API v2 included on Pay as you go |
| **Minimum Order Volume** | **1 piece** | Zero minimum order commitments; postage included |
| **Hosted MCP Tools** | **57 tools** | OAuth 2.0 & Bearer MCP server at `https://mcp.thanks.io/mcp` |
| **Print Cut-Off** | **11:00 AM Central** | Same-business-day printing & USPS induction from Texas |

---

## Code Examples: Send a Personalized Postcard (`POST /api/v2/recipients/postcard`)

### 1. cURL
```bash
curl -X POST "https://api.thanks.io/api/v2/recipients/postcard" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "size": "4x6",
    "postage_class": "first_class",
    "front_image_url": "https://assets.yourcompany.com/postcards/welcome-front-300dpi.png",
    "handwriting_style": 14,
    "handwriting_color": "blue",
    "realism": true,
    "message": "Hi %FIRST_NAME%! Welcome aboard. Scan the QR code on this card to claim your $25 onboarding credit and book your kickoff call.",
    "qrcode_url": "https://yourcompany.com/claim?user=%CUSTOM1%",
    "return_name": "Acme Growth Team",
    "return_address": "500 Congress Ave",
    "return_city": "Austin",
    "return_state": "TX",
    "return_postal_code": "78701",
    "recipients": [
      {
        "name": "Sarah Jenkins",
        "address": "742 Evergreen Terrace",
        "city": "Austin",
        "province": "TX",
        "postal_code": "78704",
        "country": "US",
        "custom1": "usr_98234"
      }
    ]
  }'
```

### 2. Node.js / TypeScript
```typescript
const THANKS_IO_API_KEY = process.env.THANKS_IO_API_KEY!;

export async function sendTransactionalPostcard(customer: {
  id: string;
  name: string;
  street: string;
  city: string;
  state: string;
  zip: string;
}) {
  const response = await fetch("https://api.thanks.io/api/v2/recipients/postcard", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${THANKS_IO_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      size: "6x9",
      postage_class: "first_class",
      creative_id: 48210,
      message: "Hey %FIRST_NAME%, we noticed you left your custom quote unfinished! Scan the QR code right here to unlock 15% off this week.",
      handwriting_style: 14,
      qrcode_url: `https://yourcompany.com/resume/${customer.id}`,
      recipients: [
        {
          name: customer.name,
          address: customer.street,
          city: customer.city,
          province: customer.state,
          postal_code: customer.zip,
          country: "US",
          custom1: customer.id,
        },
      ],
    }),
  });

  if (!response.ok) {
    throw new Error(`Thanks.io API error (${response.status}): ${await response.text()}`);
  }

  return response.json();
}
```

### 3. Python
```python
import os
import requests

THANKS_IO_API_KEY = os.environ["THANKS_IO_API_KEY"]
BASE_URL = "https://api.thanks.io/api/v2"

def send_postcard_batch(recipients: list[dict]) -> dict:
    payload = {
        "size": "4x6",
        "postage_class": "standard",
        "front_image_url": "https://assets.yourcompany.com/postcards/q4-offer.png",
        "handwriting_style": 14,
        "realism": True,
        "message": (
            "Hi %FIRST_NAME%, thanks for being a VIP member! "
            "Scan the QR code on this card to claim your private renewal reward."
        ),
        "qrcode_url": "https://yourcompany.com/vip?acct=%CUSTOM1%",
        "recipients": recipients,
    }

    response = requests.post(
        f"{BASE_URL}/recipients/postcard",
        json=payload,
        headers={
            "Authorization": f"Bearer {THANKS_IO_API_KEY}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        timeout=15,
    )
    response.raise_for_status()
    return response.json()
```

### 4. Sample `200 OK` JSON Response
```json
{
  "status": "success",
  "id": "ord_94810274",
  "test_mode": false,
  "product_type": "postcard",
  "size": "4x6",
  "postage_class": "first_class",
  "recipient_count": 1,
  "unit_cost": 0.64,
  "first_class_upgrade": 0.05,
  "total_charged": 0.69,
  "currency": "USD",
  "estimated_print_date": "2026-11-06",
  "dispatch_facility": "TX-USPS-CENTRAL",
  "tracking": {
    "qrcode_tracking_enabled": true,
    "unique_scan_url": "https://qr.thanks.io/s/rk92m10x",
    "webhook_events_subscribed": [
      "qr.scanned",
      "order_item.delivered",
      "order.status_updated"
    ]
  },
  "created_at": "2026-11-06T15:42:11Z"
}
```

---

## Core REST API v2 Endpoints

1. **`POST /api/v2/recipients/postcard` — Send Postcards (Single, Batch & Radius Search)**: Dispatches 4×6, 6×9, or 6×11 glossy postcards using a saved `creative_id` or `front_image_url` + `message` + `handwriting_style`. Supports radius neighbor search (`$0.05/address`) and Google Street View dynamic property imagery.
2. **`POST /api/v2/recipients` — Add Recipients to Automated Campaign Lists**: Inserts contacts into a Thanks.io Mailing List to trigger multi-touch drip sequences (`Days After Added`, `Birthday`, `Anniversary`, `evenFLOW`), with automatic CASS validation and `DELETE /api/v2/recipients/{id}` suppression.
3. **`GET /api/v2/creatives` — Fetch Saved Creative IDs**: Lists saved Creatives combining front artwork, handwriting-style message templates, ink color, and QR settings under one integer ID.
4. **`GET /api/v2/handwriting-styles` — List Digital Handwriting Styles**: Returns all proprietary digital handwriting-style fonts and AI Fonts with natural glyph variation. Pass `realism: true` on send calls for authentic baseline variation and occasional human crossouts.
5. **`POST /api/v2/send/letter` • `/windowlessletter` • `/notecard` • `/giftcard` • `/magnacard` — Multi-Format Dispatch**: Use the same bearer token and recipient format to send 8.5×11 windowed/windowless letters, 5×4 folded notecards, $5–$100 digital gift card mailers (Amazon, Starbucks, Target, Home Depot), and 6×9 magnetic MagnaCards.
6. **`POST /api/v2/webhooks` — Real-Time QR Scan & USPS Delivery Webhooks**: Subscribe to `qr.scanned`, `order_item.delivered` (USPS Intelligent Mail barcode / Informed Visibility), and `order.status_updated`.

---

## Postcard Dimensions, 300 DPI Print Specs & 2026 Pricing (Postage Included)

| Format | Trim Size | 300 DPI Pixel Specs (incl. 0.125" Bleed) | Pay As You Go ($0/mo) | Business ($49/mo) | Professional ($199/mo) | First Class Upgrade |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **4×6 Standard Postcard** | 4.0" × 6.0" | `1875 × 1275 px` | $1.18 | $0.77 | **$0.64** | +$0.05 (5–10 bus. days) |
| **6×9 Panorama Postcard** | 6.0" × 9.0" | `2775 × 1875 px` | $1.32 | $0.91 | **$0.71** | +$0.05 (5–10 bus. days) |
| **6×11 Jumbo Postcard** | 6.0" × 11.0" | `3375 × 1875 px` | $1.64 | $1.01 | **$0.76** | +$0.21 |
| **6×9 MagnaCard (Magnet)** | 6.0" × 9.0" | `2775 × 1875 px` | $1.78 | $1.43 | **$1.04** | +$0.21 |
| **Windowed Letter** | 8.5" × 11.0" | `2550 × 3300 px` or PDF | $1.20 | $0.83 | **$0.79** | +$0.21 |
| **Windowless Letter** | 8.5" × 11.0" | `2550 × 3300 px` + Real Stamp | $1.62 | $1.35 | **$0.99** | First Class Stamp Included |
| **5×4 Folded Notecard** | 5.0" × 4.0" | `1575 × 1275 px` cover | $2.46 | $1.83 | **$1.49** | +$0.21 |

*Note: Business ($49/mo) and Professional ($199/mo) plans also include webhooks, dynamic QR tracking, campaign automation, Zapier/Make/n8n integrations, and 1 free 24/7 AI Receptionist phone number (`%YOUR_AI_PHONE%`).*

---

## Developer Comparison: Thanks.io vs. Lob, PostGrid & Handwrytten

| Provider | Monthly Platform Fee | 4×6 Postcard Rate | Handwriting Engine | MCP & AI Agent Support | Radius & Street View |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Thanks.io** | **$0/mo (Free) • $49/mo (Biz) • $199/mo (Pro)** | **$0.64 (Pro) / $0.77 (Biz) / $1.18 (Free)** | Proprietary Digital Handwriting + AI Fonts + Realism Mode | Hosted OAuth MCP Server (57 tools) + OpenAPI 3.0 | Built-in Radius Search ($0.05/lead) + Google Street View API |
| **Lob** ([Compare](/compare/thanks-io-vs-lob)) | $260 to $550+/mo for lower per-piece tiers | $0.905+ on Free tier | None (HTML/print only) | REST API only | None |
| **PostGrid** ([Compare](/compare/thanks-io-vs-postgrid)) | $300+/mo for automation & webhooks | $0.95 to $1.35+ on entry tiers | None | REST API only | Address verification only; no radius blasts |
| **Handwrytten** ([Compare](/compare/thanks-io-vs-handwrytten)) | $0 to $99+/mo | $3.25+ per card | Mechanical pen plotters (slow queue, $3.25–$3.75+) | Basic REST API | None |
| **Click2Mail / Stannp** | $0/mo | $0.89 to $1.35+ | None | Legacy XML / basic REST | Manual uploads only |

---

## Postcard API Developer Resource Hub (Silo Navigation)

- **[Spoke #1 — Live Today] [Direct Mail API Developer Guide: Automate Postcards, Letters, Notecards & QR Webhooks in Node.js & Python](https://thanks.io/postcard-api/direct-mail-api-guide)**: Complete architectural guide covering Bearer authentication, Test Mode sandbox, multi-format payloads, Saved Creative IDs, idempotency, and Express/FastAPI QR webhook receivers.
- **[Hosted OAuth MCP Server (57 Tools)](https://thanks.io/mcp)**: Connect Claude Desktop, Cursor, and autonomous AI agents to `https://mcp.thanks.io/mcp`.
- **[AI Agents & Autonomous Direct Mail](https://thanks.io/agents)**: End-to-end agentic direct mail workflows.
- **[Zapier Direct Mail Automation](https://thanks.io/zapier-direct-mail)** • **[HubSpot Direct Mail](https://thanks.io/hubspot-direct-mail)** • **[GoHighLevel Direct Mail](https://thanks.io/gohighlevel-direct-mail)** • **[Shopify Abandoned Checkout](https://thanks.io/shopify-abandoned-checkout)** • **[Follow Up Boss Direct Mail](https://thanks.io/followupboss-direct-mail)** • **[FAQ: Does Thanks.io Have an API?](https://thanks.io/faq/does-thanks-io-have-an-api)**

---

## Frequently Asked Questions

### What is the best postcard API for developers?
The Thanks.io Postcard API (`https://api.thanks.io/api/v2`) is widely rated the best postcard API for developers, SaaS teams, and AI agents because it combines free REST API v2 access on the $0/month Pay-as-you-go plan, wholesale unit pricing down to $0.64 per 4×6 postcard (postage included) on Professional, zero minimum order quantities, a proprietary digital handwriting engine, built-in Google Street View and neighbor radius search, and a hosted 57-tool OAuth MCP server.

### How much does it cost to send a postcard via the Thanks.io API?
All Thanks.io Postcard API prices include printing and standard USPS postage with zero minimum order requirements. On Pay as you go ($0/month), 4×6 postcards cost $1.18, 6×9 postcards cost $1.32, and 6×11 jumbo postcards cost $1.64. On the Business plan ($49/month), rates drop to $0.77 (4×6), $0.91 (6×9), and $1.01 (6×11). On the Professional plan ($199/month), rates drop to $0.64 (4×6), $0.71 (6×9), and $0.76 (6×11). Upgrading to First Class postage (5 to 10 business days plus USPS tracking and return-to-sender) adds $0.05 on 4×6 and 6×9 postcards or $0.21 on 6×11 jumbo postcards.

### Does the Thanks.io Postcard API have a free sandbox or test mode?
Yes. You can enable Test Mode under `Account Settings -> API Access -> Test Mode`. While Test Mode is enabled, all POST requests to `/api/v2/recipients/postcard` and other send endpoints validate your authentication, JSON schema, image URLs, and recipient addresses and return a realistic mock order payload without printing physical mail or charging your credit card.

### Can I send handwritten-style postcards through the API?
Yes. Every postcard, letter, and folded notecard sent through the Thanks.io API uses our proprietary digital handwriting engine. You can query `GET /api/v2/handwriting-styles` to choose from dozens of realistic handwritten-style fonts and AI Fonts with natural glyph variation, select your ink color, and pass `realism: true` to enable authentic human-like baseline variations and occasional crossouts—without paying $3.25+ for slow mechanical pen plotters.

### How do dynamic QR code webhooks work on API postcards?
When you pass a `qrcode_url` parameter (with optional merge tags like `%CUSTOM1%` or `%FIRST_NAME%`) in your `POST /api/v2/recipients/postcard` request, Thanks.io automatically generates a unique trackable QR code for each individual recipient. The moment a recipient scans their postcard with their smartphone camera, they are redirected to your destination URL while Thanks.io fires a real-time `qr.scanned` webhook payload containing the recipient's identity, address, creative ID, and scan timestamp to your server.

### Can I mail every neighbor within a radius of a property via the API?
Yes. By passing a center street address, postal code, and desired record count to the radius endpoint, Thanks.io automatically queries verified residential or business addresses around that coordinate ($0.05 per appended address) and dispatches your postcards in a single API call.

### How does Thanks.io compare to Lob and PostGrid for postcard automation?
Lob charges $260 to $550+ per month to unlock lower per-piece postcard tiers (charging $0.905+ on its free developer tier), and PostGrid charges $300+ per month for advanced automation features. Neither Lob nor PostGrid offers digital handwriting-style fonts, 5×4 folded notecards, branded gift card mailers, 6×9 MagnaCards, dynamic Google Street View property photos, or a hosted 57-tool OAuth MCP server. Thanks.io provides full REST API v2 access on the $0/month plan and full webhook/QR automation on the $49/month Business plan.

### Can AI agents send postcards using the Model Context Protocol (MCP)?
Yes. Thanks.io hosts an official OAuth 2.0 and Bearer-authenticated MCP server at `https://mcp.thanks.io/mcp` exposing 57 direct mail tools, alongside a Documentation MCP server at `https://docs.thanks.io/mcp` and an OpenAPI 3.0 specification at `https://thanks.io/openapi.json`.