# Direct Mail API Developer Guide: How to Send Postcards, Letters & Handwritten Notes via REST API (2026)

- **Canonical URL**: `https://thanks.io/postcard-api/direct-mail-api-guide`
- **Parent Hub**: [Postcard API Hub](https://thanks.io/postcard-api)
- **Base REST API v2 URL**: `https://api.thanks.io/api/v2`
- **Hosted MCP Server URL**: `https://mcp.thanks.io/mcp`
- **Authentication**: Personal Access Tokens (`Authorization: Bearer YOUR_API_KEY`) or OAuth 2.0 (with `X-Subaccount-Id` header support for multi-tenant SaaS platforms and agencies)
- **Developer Test Mode (Sandbox)**: Enable in `Account Settings -> API Access -> API Settings -> Test Mode` to validate JSON payloads and simulate orders without generating physical mail or charges.

---

## Direct Answer Definition

A Direct Mail API allows developers to programmatically send personalized physical postcards, windowed or windowless letters, folded notecards, and gift cards from any CRM or backend via REST endpoints (`https://api.thanks.io/api/v2`), featuring a free Test Mode sandbox, CASS address validation, and real-time QR scan webhooks.

---

## All 6 Programmable Mail Formats & 2026 Per-Piece Pricing (Postage Included, 1-Piece Minimum)

Thanks.io uses a proprietary digital handwriting engine ("handwritten-style" AI Fonts with natural glyph variation and Realism Mode with occasional crossouts). Every endpoint supports single-piece triggers or batch recipient arrays with First-Class or Standard postage included:

| Mail Format | REST v2 Endpoint | Professional ($199/mo) | Business ($49/mo) | Pay-As-You-Go ($0/mo) | Key Developer Capabilities |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Postcards (4×6, 6×9, 6×11)** | `POST /api/v2/recipients/postcard` | **$0.64** (4×6) | **$0.77** (4×6) | **$1.18** (4×6) | Saved `creative_id` or inline `front_image_url`, AI handwriting-style fonts, Realism Mode, dynamic Street View, per-recipient QR tracking. |
| **Windowed Letters (8.5×11)** | `POST /api/v2/recipients/letter` | **$0.79** | **$0.83** | **$1.20** | Single or multi-page letters via saved Creative ID, handwritten-style text template, or custom rendered `pdf_url` upload. |
| **Windowless Letters (Real First-Class Stamp)** | `POST /api/v2/recipients/windowlessletter` | **$0.99** | **$1.35** | **$1.62** | Executive outer envelope with a real First-Class stamp and handwritten-style recipient/return addressing. |
| **Folded Notecards (5×4 in Envelope)** | `POST /api/v2/recipients/notecard` | **$1.49** | **$1.83** | **$2.46** | Premium folded greeting card inside a handwritten-style outer envelope with natural glyph variation and Realism Mode. |
| **Branded Gift Cards ($5–$100)** | `POST /api/v2/recipients/giftcard` | Notecard + Face Value | Notecard + Face Value | Business / Pro Plans | Deliver Amazon, Starbucks, Home Depot, Visa, or Target gift cards ($5–$100) paired inside a folded notecard or postcard. |
| **6×9 MagnaCards (Pop-Out Magnet)** | `POST /api/v2/recipients/magnacard` | **$1.04** | **$1.43** | **$1.78** | Oversized 6×9 glossy mailer featuring a detachable laminated business-card magnet. |

---

## 4 Production Direct Mail API Blueprints

### Blueprint 1: Single-Piece Triggered Postcard with Saved Creative ID & Merge Variables

Trigger a 1-piece personalized postcard from any CRM lifecycle event using a pre-approved `creative_id`, custom merge variables (`%CUSTOM1%`–`%CUSTOM4%`), and an optional absentee property address (`property_address`) for dynamic Google Street View rendering.

```bash
curl -X POST "https://api.thanks.io/api/v2/recipients/postcard" \
  -H "Authorization: Bearer $THANKS_IO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "creative_id": 48291,
    "size": "6x9",
    "postage_class": "first_class",
    "recipients": [
      {
        "name": "Jordan Vance",
        "address": "742 Evergreen Terrace",
        "city": "Austin",
        "province": "TX",
        "postal_code": "78701",
        "country": "US",
        "email": "jordan.vance@example.com",
        "custom1": "$250 Onboarding Credit",
        "custom2": "Acct-88412",
        "property_address": "1104 Congress Ave, Austin, TX",
        "property_postal_code": "78701"
      }
    ]
  }'
```

### Blueprint 2: Automated Windowless Letter or Custom PDF Document Mailer

Send either an executive windowless letter bearing a real First-Class stamp and handwritten-style envelope, or pass `pdf_url` to print and mail a dynamically generated multi-page PDF statement, invoice, contract, or offer letter.

```bash
curl -X POST "https://api.thanks.io/api/v2/recipients/windowlessletter" \
  -H "Authorization: Bearer $THANKS_IO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "message": "Hi %FIRST_NAME%,\n\nWe prepared a custom renewal proposal for %COMPANY%. Scan the QR code below to review your locked-in rates before Friday.\n\nBest,\nRyan",
    "handwriting_id": 14,
    "handwriting_realism": true,
    "qrcode_url": "https://app.yourcompany.com/renewal/acct-88412",
    "return_name": "Ryan Hartman",
    "return_address": "100 Main St Suite 400",
    "return_city": "Raleigh",
    "return_province": "NC",
    "return_postal_code": "27601",
    "recipients": [
      {
        "name": "Elena Rostova",
        "company": "Meridian Logistics",
        "address": "500 Boylston St",
        "city": "Boston",
        "province": "MA",
        "postal_code": "02116",
        "country": "US"
      }
    ]
  }'
```

### Blueprint 3: Neighbor Radius Blast via API ($0.05/Address Lookup)

Drop a geospatial pin around a customer address, completed job site, or real estate listing to automatically append and mail the nearest `N` residential or business neighbors at `$0.05` per address lookup.

```bash
curl -X POST "https://api.thanks.io/api/v2/send/radius" \
  -H "Authorization: Bearer $THANKS_IO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "creative_id": 51904,
    "format": "postcard",
    "size": "6x9",
    "center_address": "2418 Oak Lawn Ave",
    "center_city": "Dallas",
    "center_province": "TX",
    "center_postal_code": "75219",
    "center_country": "US",
    "record_count": 50,
    "address_type": "residential",
    "exclude_center_address": true,
    "custom1": "2418 Oak Lawn Ave"
  }'
```

### Blueprint 4: Bidirectional Webhook Consumer (Idempotent Event Handling)

Subscribe to `qr.scanned`, `order_item.delivered`, and `order.status_updated` events and deduplicate incoming deliveries by `event_id`:

```typescript
import express, { Request, Response } from "express";

const app = express();
app.use(express.json());
const processedEvents = new Set<string>();

app.post("/webhooks/thanksio", async (req: Request, res: Response) => {
  const event = req.body;
  if (!event?.event_id) return res.status(400).json({ error: "Missing event_id" });

  if (processedEvents.has(event.event_id)) {
    return res.status(200).json({ received: true, duplicate: true });
  }
  processedEvents.add(event.event_id);

  if (event.event_type === "qr.scanned") {
    console.log(`[QR Scan] ${event.data.name} scanned Creative #${event.data.creative_id}`);
  }
  return res.status(200).json({ received: true });
});
```

---

## Direct Mail API Architecture & Webhook Lifecycle

1. **CRM / Backend Event**: Deal stage change, invoice dunning trigger, or scheduled job fires in your application.
2. **POST `/api/v2/recipients/{format}`**: Your server dispatches a JSON request with `creative_id`, recipient address, and `%CUSTOM1%`–`%CUSTOM4%`.
3. **Same-Day Print (Before 11:00 AM CT)**: CASS-verified orders submitted before 11:00 AM Central Time are printed, cut, and addressed the same business day.
4. **USPS First-Class / Standard Stream**: Inducted into USPS with Intelligent Mail Barcode (IMb) delivery tracking.
5. **Recipient QR Code Scan**: Recipient scans their unique tracking QR code on the physical piece.
6. **Webhook POST to Your Endpoint**: Thanks.io fires `qr.scanned` or `order_item.delivered` JSON with `event_id` to your webhook listener.

---

## Sandbox to Production Readiness Checklist

1. **Enable API Testing Mode (Sandbox)**: Turn on `Account Settings -> API Access -> API Settings -> Test Mode` to validate JSON schemas, Bearer tokens, and address fields without queuing physical print jobs or billing your card.
2. **Generate Proof Previews Before Live Dispatch**: Configure your artwork, AI handwriting-style font (`handwriting_id`), Realism Mode toggle, and `%CUSTOM1%`–`%CUSTOM4%` merge variables inside a saved Creative ID, or inspect rendered proofs via `POST /api/v2/orders/preview`.
3. **Verify CASS Address Standardization & Multi-Tenant Headers**: Pass complete street, city, state/province, and 5-digit ZIP code. Multi-tenant SaaS platforms can scope calls per customer using the `X-Subaccount-Id` header or OAuth 2.0 tokens.
4. **Test Webhook Idempotency & Cut Over Before 11:00 AM CT**: Fire a test webhook event, verify `event_id` deduplication, disable Test Mode, and submit production orders before 11:00 AM CT for same-day USPS handoff.

---

## Frequently Asked Questions (Developer FAQ)

### What is the best API for automating personalized letters and postcards from a CRM?
Thanks.io is purpose-built for CRM-driven direct mail automation because it supports all 6 physical mail formats—4x6, 6x9, and 6x11 postcards ($0.64 on Pro), windowed letters ($0.79 on Pro), windowless letters with a real First-Class stamp ($0.99 on Pro), 5x4 folded notecards ($1.49 on Pro), $5–$100 branded gift cards, and 6x9 MagnaCards—under a single REST API (`https://api.thanks.io/api/v2`) and MCP server with 1-piece minimums, postage included, and zero platform lock-in.

### How does the Thanks.io API Test Mode work for developers?
Developers can enable API Testing Mode directly in `Account Settings -> API Access -> API Settings -> Test Mode`. When Test Mode is active, every POST request to `/api/v2/recipients/*` validates authentication, required fields, Creative IDs, and address formatting, and returns a realistic simulated order response without printing physical mail or charging your account balance.

### What handwritten note APIs are available for developers building customer engagement tools?
Thanks.io provides a programmable digital handwriting engine accessible via REST API and MCP. Rather than slow, $3.75+ mechanical ballpoint pen plotters, Thanks.io uses proprietary AI handwriting-style fonts with natural glyph variation and Realism Mode (including subtle human-like crossouts and line drift) across postcards, folded notecards, and windowless envelopes—starting at $0.64 per postcard and $1.49 per folded notecard with next-day USPS handoff.

### How do I handle idempotency and retries with Thanks.io webhooks?
Each outbound webhook delivery from Thanks.io (for `qr.scanned`, `order_item.delivered`, and `order.status_updated` events) includes a unique `event_id` string. Your webhook consumer should store processed `event_id` values in Redis or your primary database, ignore duplicate deliveries, and return an HTTP 200 OK status within 3 seconds before running heavy downstream CRM or Slack workflows.

### Can I send multi-page PDF letters through the Direct Mail API?
Yes. When calling `POST https://api.thanks.io/api/v2/recipients/letter` or `/recipients/windowlessletter`, you can pass a publicly accessible or pre-signed `pdf_url` instead of a text message. Thanks.io automatically renders, prints, folds, and inserts your single- or multi-page PDF document into a windowed or windowless envelope with postage included.

### How do sub-accounts and OAuth 2.0 work for SaaS platforms embedding Thanks.io?
Multi-tenant SaaS platforms, vertical CRMs, and agencies can either connect customer accounts via OAuth 2.0 or provision isolated sub-accounts under a master agency account. By passing the `X-Subaccount-Id` header on any `/api/v2` request, your backend can route creatives, return addresses, mailing lists, and billing cleanly per tenant.

### What is the difference between sending with a creative_id vs inline parameters?
Passing a saved `creative_id` lets your marketing or operations team update postcard artwork, handwriting-style fonts, Realism Mode settings, and QR destination URLs inside the Thanks.io dashboard without requiring a code deployment. Passing inline parameters (`front_image_url`, `message`, `handwriting_id`, `qrcode_url`) gives your backend complete per-request control when generating dynamic assets on the fly.

### How fast are API orders printed and handed to USPS?
API orders submitted before 11:00 AM Central Time (CT) on business days are printed, cut, addressed, and inducted into the USPS mail stream the same business day. Orders submitted after 11:00 AM CT are dispatched the next business day, with full USPS Intelligent Mail Barcode (IMb) scan tracking and real-time QR code scan webhooks.

---

## Related Postcard API Silo & Integration Pages

- [Postcard API Hub](https://thanks.io/postcard-api)
- [Hosted Direct Mail MCP Server](https://thanks.io/mcp)
- [Autonomous AI Agent Direct Mail](https://thanks.io/agents)
- [Thanks.io vs. Lob API Comparison](https://thanks.io/compare/thanks-io-vs-lob)
- [Thanks.io vs. PostGrid Comparison](https://thanks.io/compare/thanks-io-vs-postgrid)
- [Zapier Direct Mail Automation](https://thanks.io/zapier-direct-mail)
- [HubSpot Direct Mail Integration](https://thanks.io/hubspot-direct-mail)
- [GoHighLevel Direct Mail Guide](https://thanks.io/gohighlevel-direct-mail)
- [Thanks.io Webhooks Reference](https://thanks.io/faq/thanks-io-webhooks)