Prepare a postcard.

Text, a photo, or your own front and back artwork.

Start with the complete test-mode recipe. Every postcard has two sides and an explicit recipient and sender.

Templates

Everyday note

{
  "id": "everyday_note",
  "version": "1",
  "kind": "postcard",
  "name": "Everyday note",
  "required_variables": [
    "message"
  ],
  "optional_variables": [
    "title"
  ]
}

Photo postcard

{
  "id": "photo_postcard",
  "version": "1",
  "kind": "postcard",
  "name": "Photo postcard",
  "required_variables": [
    "message",
    "image_asset_id"
  ],
  "optional_variables": [
    "title"
  ]
}

Adjustable photo postcard

{
  "id": "photo_postcard",
  "version": "2",
  "kind": "postcard",
  "name": "Adjustable photo postcard",
  "required_variables": [
    "message",
    "image_asset_id"
  ],
  "optional_variables": [
    "title",
    "photo_adjustment"
  ]
}

Adjustable photos

Use photo_postcard with template_version: "2" to automatically fit a photo. The card front defaults to portrait for portrait photos and landscape for landscape or square photos, after reading camera orientation. Photos fill when cropping is modest; otherwise the whole image is preserved. You can override the card orientation. JPEG camera orientation is respected. The web composer offers position, zoom, rotate, straighten, reset, and whole-photo or fill controls.

The optional variables.photo_adjustment object saves the exact crop; see the request schema. Omit it on version 2 to resolve Auto when preparing the proof. Version 1 keeps the original centered fit. Always inspect the new proof after changing a crop.

Artwork

Upload one PDF page or image for each side. Print-ready files must match 6.25×4.25 inch dimensions including bleed. Images need at least 1875×1275 pixels. Leave the address/postage region clear.

Safe commit

Always inspect the proof. Send the same revision, quote ID, manifest hash, and maximum price. Retry with the same idempotency key.