Direct Mail API Developer Guide & Architecture Blueprints

// Node.js 20+ / TypeScript — Triggered Postcard with Creative ID & Merge Variables
const THANKS_IO_API_KEY = process.env.THANKS_IO_API_KEY!;

interface SendPostcardPayload {
  creative_id: number;
  size: "4x6" | "6x9" | "6x11";
  postage_class?: "first_class" | "standard";
  recipients: Array<{
    name: string;
    address: string;
    city: string;
    province: string;
    postal_code: string;
    country: string;
    email?: string;
    custom1?: string;
    custom2?: string;
    property_address?: string;
    property_postal_code?: string;
  }>;
}

export async function triggerCrmPostcard() {
  const payload: SendPostcardPayload = {
    creative_id: 48291, // Saved Creative in Thanks.io Dashboard
    size: "6x9",
    postage_class: "first_class",
    recipients: [
      {
        name: "Jordan Vance",
        address: "742 Evergreen Terrace",
        city: "Austin",
        province: "TX",
        postal_code: "78701",
        country: "US",
        email: "[email protected]",
        custom1: "$250 Onboarding Credit",
        custom2: "Acct-88412",
        // Optional: Display Street View of subject property while mailing owner's address
        property_address: "1104 Congress Ave, Austin, TX",
        property_postal_code: "78701",
      },
    ],
  };

  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",
      // Optional for multi-tenant SaaS / agencies:
      // "X-Subaccount-Id": "sub_99201"
    },
    body: JSON.stringify(payload),
  });

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

  return await response.json();
}