The Programmable Postcard API for Developers & AI Agents
Dispatch personalized 4×6, 6×9, and 6×11 postcards, windowless letters, folded notecards, and gift cards with one HTTP POST or MCP tool call. Built-in digital handwriting-style fonts, Google Street View property photos, neighbor radius search, and 2-way QR scan webhooks—with zero minimum orders.
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.
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"
}
]
}'Core Postcard API Endpoints & Capabilities
Authenticate with a Bearer token (Authorization: Bearer YOUR_API_KEY) or OAuth 2.0 to orchestrate every stage of physical mail delivery.
/api/v2/recipients/postcardSend Postcards (Single, Batch & Radius Search)
Dispatches 4×6, 6×9, or 6×11 postcards to an explicit recipient array, a saved mailing list, or every residential/business neighbor within a geographic radius of a target address ($0.05/address lookup).
- •recipients[] (or radius_address + radius_count + address_type)
- •size ('4x6' | '6x9' | '6x11') & postage_class ('standard' | 'first_class')
- •creative_id OR (front_image_url, message, handwriting_style, realism)
- •qrcode_url, custom1–custom4, and optional absentee property_address
- ✓4×6, 6×9 & 6×11 Full-Bleed Glossy Postcards
- ✓Saved Creative ID or Dynamic Image URL + Message
- ✓Radius Neighbor Search (center address + record count)
- ✓Google Street View Dynamic Property Photo Layer
/api/v2/recipientsAdd Recipients to Automated Campaign Lists
Inserts one or more contacts into a Thanks.io Mailing List to automatically trigger multi-step drip sequences (Days After Added, Birthday, Anniversary, or evenFLOW budget-paced campaigns).
- •mailing_list_id (Target list with attached drip rules)
- •name, address, city, province, postal_code, country
- •email, phone, birth_date, anniversary_date
- •custom1, custom2, custom3, custom4 merge variables
- ✓Automatic CASS Address Standardization & Validation
- ✓Multi-Step Drip, Birthday & Anniversary Campaign Triggers
- ✓Radius &Targeted Lead Feed Appending
- ✓DELETE /api/v2/recipients/{id} for Instant Suppression
/api/v2/creativesList & Manage Saved Creative IDs
Retrieves your saved Creatives library—each Creative bundles an approved front image template, handwriting-style interior/back message, font color, and dynamic QR configuration under a single integer ID.
- •GET /api/v2/creatives (List all saved Creative IDs)
- •GET /api/v2/image-templates & GET /api/v2/message-templates
- •POST /api/v2/creatives (Programmatically assemble a new Creative)
- •Pass creative_id in any send call to avoid hardcoding copy
- ✓Decouple Marketing Design from Engineering Code
- ✓Supports AI Studio, Canva & Custom 300 DPI Uploads
- ✓Create & Update Image/Message Templates via REST
- ✓Compatible with Postcards, Letters, Notecards & MagnaCards
/api/v2/handwriting-stylesQuery Digital Handwriting Styles & Realism Engine
Returns all available proprietary digital handwriting-style fonts, AI Fonts with natural glyph variation, ink colors, and Realism Mode settings (authentic spacing variation and occasional human crossouts).
- •handwriting_style (Integer style ID returned by endpoint)
- •handwriting_color ('blue' | 'black' | 'red' | 'green' | 'purple' | hex)
- •realism (boolean — enables authentic human-like imperfections)
- •salutation & signoff overrides
- ✓Proprietary Digital Handwriting Engine (Fast, Scalable & Affordable)
- ✓AI Fonts with Dynamic Per-Character Glyph Variation
- ✓Realism Mode (Natural Baseline Variation & Occasional Crossouts)
- ✓Sub-Account & Brand Font Filtering
/api/v2/send/letter • /notecard • /giftcard • /magnacardMulti-Format Dispatch: Letters, Notecards, Gift Cards & MagnaCards
Extend your integration beyond postcards using the exact same authentication and recipient schema to send windowed/windowless letters, 5×4 folded notecards, digital gift card mailers, and 6×9 magnetic postcards.
- •POST /api/v2/send/letter & POST /api/v2/send/windowlessletter
- •POST /api/v2/send/notecard & POST /api/v2/send/magnacard
- •POST /api/v2/send/giftcard (brand_id + amount_cents)
- •pdf_url (for custom multi-page document mailings)
- ✓Windowless Letters with Real First-Class Stamp & Handwriting Envelope
- ✓Multi-Page 8.5×11 PDF Letters (Invoices, Statements, Legal Notices)
- ✓5×4 Folded Notecards in Handwritten-Style Envelopes
- ✓$5–$100 Gift Cards (Amazon, Starbucks, Target, Home Depot) & MagnaCards
POST https://your-api.com/webhooks/thanksioReal-Time Webhooks: QR Scans & USPS IMb Delivery
Subscribe via POST /api/v2/webhooks to receive real-time JSON callbacks the second a recipient scans their personalized QR code or when USPS Intelligent Mail barcode (IMb) scans confirm mailbox delivery.
- •event ('qr.scanned' | 'order_item.delivered' | 'order.status_updated')
- •recipient (id, name, address, email, phone, custom1–custom4)
- •order_id, creative_id, scanned_at, user_agent, ip_address
- •Lead Board auto-population + Slack / CRM routing
- ✓qr.scanned — Instant Per-Recipient Scan Attribution
- ✓order_item.delivered — USPS Informed Visibility / IMb Scan Events
- ✓order.status_updated — Pre-Press, Printed & Inducted Transitions
- ✓Test Webhook Trigger Endpoint (/api/v2/webhooks/{id}/test)
Digital Handwriting & Realism Mode
Proprietary handwritten-style fonts and AI Fonts with natural glyph variation and optional crossouts—rendered at 300 DPI without $3.75 pen-plotter fees.
Street View & Radius Blasts ($0.05/Lead)
Automatically inject a Google Street View photo of the recipient's house or mail the closest 50–500 neighbors around any US address via API.
2-Way QR Scan & IMb Webhooks
Receive instant JSON webhooks when a recipient scans their unique QR code or when USPS Intelligent Mail barcode scans confirm delivery.
Test Mode Sandbox & AI Phone
Validate payloads for free in Test Mode. Business & Pro plans also include 1 free 24/7 AI Receptionist phone number (%YOUR_AI_PHONE%).
Postcard Dimensions, Bleed Specs & All-In Pricing
Every API rate includes full-color printing and USPS postage with zero minimum order quantities. Orders placed before 11:00 AM Central print the same business day from Texas.
| Mail Format | 300 DPI Pixel Specs & Bleed | Pay As You Go ($0/mo) | Business ($49/mo) | Professional ($199/mo) | First Class Upgrade |
|---|---|---|---|---|---|
4×6 Standard Postcard 4.0" × 6.0" (6.0" × 4.0" landscape) | 1875 × 1275 px @ 300 DPI (incl. bleed) 0.125" bleed per side; keep text 0.25" inside trim | $1.18 | $0.77 | $0.64 | +$0.05 (5–10 bus. days + USPS tracking) |
6×9 Panorama Postcard 6.0" × 9.0" (9.0" × 6.0" landscape) | 2775 × 1875 px @ 300 DPI (incl. bleed) 0.125" bleed per side; 3.5" × 2.5" USPS indicia/address zone | $1.32 | $0.91 | $0.71 | +$0.05 (5–10 bus. days + USPS tracking) |
6×11 Jumbo Postcard 6.0" × 11.0" (11.0" × 6.0" landscape) | 3375 × 1875 px @ 300 DPI (incl. bleed) 0.125" bleed per side; maximum USPS flat-rate letter-class size | $1.64 | $1.01 | $0.76 | +$0.21 (First Class oversize postage) |
6×9 MagnaCard (Pop-Out Magnet) 6.0" × 9.0" with integrated fridge magnet | 2775 × 1875 px @ 300 DPI 0.125" bleed; center magnet die-cut safe zone | $1.78 | $1.43 | $1.04 | +$0.21 |
Windowed Business Letter 8.5" × 11.0" in #10 Double-Window Envelope | 2550 × 3300 px (or multi-page PDF URL) Standard #10 window address placement handled automatically | $1.20 | $0.83 | $0.79 | +$0.21 |
Windowless Executive Letter 8.5" × 11.0" in Handwritten-Style Stamped Envelope | 2550 × 3300 px @ 300 DPI Includes real First-Class stamp & digital handwriting envelope | $1.62 | $1.35 | $0.99 | First Class Stamp Included |
5×4 Folded Notecard (+ Optional Gift Card) 5.0" × 4.0" folded card in matching envelope | 1575 × 1275 px outside cover @ 300 DPI Full handwriting-style interior message + Realism Mode | $2.46 | $1.83 | $1.49 | +$0.21 (Gift cards add $5–$100 face value) |
Thanks.io vs. Lob, PostGrid & Handwrytten
See why engineering teams migrate from $260–$550/mo legacy print APIs to Thanks.io's REST API v2 and hosted MCP server.
| API Provider | Monthly Platform Fee | 4×6 Postcard Rate | Handwriting Engine | MCP & AI Tooling | Radius & Street View |
|---|---|---|---|---|---|
| Thanks.io | $0/mo (Pay as you go) • $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 + Docs MCP | Built-in Radius Search ($0.05/lead) + Google Street View API |
| $260 to $550+/mo for low per-piece tiers ($0 developer tier charges $0.905+) | $0.905 (Free) / Requires $260–$550+/mo for lower tiers | None (Standard print/HTML templates only) | REST API only; no hosted OAuth MCP server or AI Receptionist | No built-in neighbor radius lookup or dynamic Street View | |
PostGrid Compare vs PostGrid | $0 starter (high per-piece) or $300+/mo for automation & webhooks | $0.95 to $1.35+ on entry tiers | None (Standard commercial print) | REST API only; no hosted MCP server for AI agents | Address verification API, but no radius neighbor blasts |
Handwrytten Compare vs Handwrytten | $0 to $99+/mo | $3.25+ per card | Mechanical pen plotters (Slow multi-day queue & $3.25+ cost) | Basic REST API; no 57-tool OAuth MCP server | No Street View personalization or radius neighbor search |
Click2Mail / Stannp | $0/mo | $0.89 to $1.35+ | None (Legacy print shop fonts) | Legacy XML / basic REST; no MCP server or AI Studio | Manual list uploads; no dynamic Street View API |
How to Send Your First API Postcard
Go from API key generation to live USPS dispatch and webhook attribution in four steps.
Generate Your Bearer API Key & Enable Test Mode
Create a free Thanks.io account ($0/mo Pay as you go) and navigate to Settings -> API Access to generate a Personal Access Token. Toggle Test Mode on to validate payloads and inspect mock order responses without printing or charging your balance.
Pick a Saved Creative ID or Pass 300 DPI Artwork URLs
Either design your mailer in ThanksAI Studio / Canva and reference its integer creative_id (GET /api/v2/creatives), or pass a 300 DPI front_image_url, message string with %FIRST_NAME% merge tags, and handwriting_style ID directly in your POST request.
POST to /api/v2/recipients/postcard
Send a single recipient, an array of up to hundreds of recipients, or a radius search query. Choose '4x6', '6x9', or '6x11' and select 'standard' or 'first_class' postage. Orders submitted before 11am Central print the same business day from Texas.
Subscribe to QR Scan & USPS Delivery Webhooks
Register your webhook endpoint via POST /api/v2/webhooks to receive real-time JSON callbacks on qr.scanned, order_item.delivered, and order.status_updated—closing the attribution loop in your database or CRM.
Deep-Dive Architecture Guides & Integration Blueprints
Explore the complete Postcard API documentation series—starting with our flagship Node.js & Python implementation guide.
Direct Mail API Developer Guide: Automate Postcards, Letters, Notecards & QR Webhooks in Node.js & Python
Complete architectural implementation guide covering Bearer authentication, Test Mode sandbox validation, multi-format payloads (postcards, windowless letters, notecards, gift cards), Saved Creative IDs, idempotency patterns, and Express/FastAPI QR webhook receivers.
Postcard API Webhooks & Attribution: Real-Time QR Code Scan Events & USPS Intelligent Mail Barcode (IMb) Tracking
Deep dive into configuring POST /api/v2/webhooks for qr.scanned, order_item.delivered, and order.status_updated events—plus piping scan telemetry into HubSpot, Salesforce, Segment, and Slack.
Handwritten-Style Postcard & Windowless Letter API: AI Fonts, Realism Mode & Dynamic Merge Variables
How Thanks.io's proprietary digital handwriting engine renders natural glyph variation and Realism Mode crossouts at 300 DPI—delivering handwritten open rates at $0.64–$0.99 per piece instead of $3.75 pen-plotter prices.
Real Estate & Home Services Postcard API: Automated Google Street View Property Photos & Radius Neighbor Blasts
Programmatically mail a homeowner a postcard showing a Google Street View photo of their exact house, or trigger a 50-neighbor radius blast around a completed roofing, solar, or real estate listing for $0.05/address.
Migrating from Lob or PostGrid to the Thanks.io Postcard API: Endpoint Mapping & Cost Reduction Playbook
Side-by-side payload translation from Lob (/v1/postcards) and PostGrid (/print-mail/v1/postcards) to Thanks.io (/api/v2/recipients/postcard), eliminating $260–$550/mo platform fees.
Connected MCP, Agent & CRM Automation Guides
Prefer a hosted MCP server or turnkey CRM integration over raw HTTP calls? Explore our native connectors:
Full Node.js, Python & cURL implementation guide for postcards, letters, notecards, and QR webhooks.
Connect Claude, Cursor, Windsurf, and custom AI agents to https://mcp.thanks.io/mcp.
How autonomous AI agents discover leads, design creatives in AI Studio, and dispatch physical mail.
Trigger postcards, windowless letters, and gift cards from 8,000+ apps without writing boilerplate.
Native HubSpot workflow actions and 2-way contact sync for automated lifecycle mailers.
Webhook and sub-account direct mail automation for GoHighLevel agencies and SaaSpreneurs.
Recover high-AOV abandoned Shopify carts with automated First-Class postcards and unique QR discounts.
Trigger automated Street View postcards, sphere nurture drips, and neighbor blasts from Follow Up Boss.
Quick technical overview of REST API v2 endpoints, rate limits, authentication, and OpenAPI spec.
Postcard API Frequently Asked Questions
Get Your Free Postcard API Key + $10 Credit
Test payloads for free in Sandbox Mode or dispatch live 4×6, 6×9, and 6×11 postcards starting at $0.64/piece with postage included and zero minimums.