Send a Postcard

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

Generate an API key from Integrations.
Ensure your account has tokens or a saved card.
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"
      }
    ],
    "frontHtml": "<!doctype html><html><body><div style=\"width:6in;height:4in\">Front</div></body></html>",
    "backHtml": "<!doctype html><html><body><div style=\"width:6in;height:4in\">Back</div></body></html>"
  }'

Suggested HTML baseline

Canvas size: 6in x 4in
Keep each HTML field under 2,000,000 characters
Provide complete HTML for both sides

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

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"
      }
    ],
    "frontHtml": "<!doctype html><html><body><div style=\"width:6in;height:4in\">Front</div></body></html>",
    "backHtml": "<!doctype html><html><body><div style=\"width:6in;height:4in\">Back</div></body></html>"
  }'