When to use this

Use this flow when you want to send dynamic or fully custom postcard HTML and do not need a saved template.

Prerequisites

1. Generate an API key from Integrations.
2. Ensure your account has tokens or a saved card.
3. Use a US sender address (from.country = "US").

Minimal request

templateContext is optional. You can send with only addresses + frontHtml + backHtml.

curl -X POST "https://tinypostcard.com/api/v1/postcards/send" \
  -H "Authorization: Bearer $TINYPOSTCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "firstName": "Avery",
      "lastName": "Lane",
      "line1": "123 Main St",
      "city": "Denver",
      "stateProvince": "CO",
      "postalCode": "80202",
      "country": "US"
    },
    "to": [
      {
        "firstName": "Jordan",
        "lastName": "Parker",
        "line1": "456 Ocean Ave",
        "city": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    ],
    "imageUrl": "https://example.com/front.png",
    "imageOrientation": "landscape",
    "messageText": "Back message only",
    "messageFontFamily": "tpc-letters-home"
  }'

Suggested HTML baseline

• Canvas size: 6.25in x 4.25in for full-bleed Lob output, with important content inside the 6in x 4in trim
• Keep each HTML field under 2,000,000 characters
• Provide complete HTML for both sides
• Put real generated/uploaded image fronts in imageUrl; use frontHtml only for layout or advanced custom HTML
• Keep backHtml to the message only; tinypostcard reserves Lob’s address/postage/barcode area

For a safe starter format, see HTML Structure.

Optional scheduling

Add scheduleTargetDate in YYYY-MM-DD format:

{
  "scheduleTargetDate": "2026-04-15"
}

When provided, tinypostcard treats this as the target delivery date and schedules mailing up to 7 days earlier (or today if the target date is sooner).

Response shape

Success returns:

• success: true
• batchId
• persistedSendIds
• failedRecipients and failedCount (for partial failures)
• billing and compensation

Common issues

• 400: payload validation problems (invalid country/date/html fields)
• 402: no available payment method/tokens
• 502: downstream provider rejection