Preview a postcard

POST /api/postcards/preview returns an image of the card exactly as the robot will write it. Use it to show customers a proof, or to check that dynamic text fits before you place an order.

curl https://paperjoy.co/api/postcards/preview \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: image/png" \
  --header "Content-Type: application/json" \
  --data '{
    "content": "Dear Anna,\nthank you for your first order! We hope the flowers brought you a lot of joy. See you in the spring!",
    "signature": "Marta from the Linden Florist",
    "font_id": "font-1"
  }' \
  --output preview.png

The response is 200 OK with Content-Type: image/png:

The PNG returned by the preview endpoint: a handwritten card with the message and signature.

Request body

The preview takes the card fields from Create a postcard. It doesn’t need a recipient or address.

Field	Type	Rule
`content`	string	Required. Up to 300 characters.
`font_id`	string	Required. `font-1` or `font-2`.
`signature`	string	Optional. Up to 50 characters.
`signature_id`	string	Optional. An active custom signature. Don’t combine with `signature`.
`mistake`	boolean	Optional. Defaults to `false`.

Good to know

Free. Previews never create a postcard or use a credit, in either mode.
Card only. The preview shows the handwritten side. The envelope preview is available in the editor.
Text that doesn’t fit is rejected, as on create. The preview returns the same 422 card_fit error as Create a postcard, so a 200 preview means the order will fit.
Mistakes are repeatable. With mistake: true, the same message always crosses out the same word, so the preview matches the final card.
Cached for 10 minutes. Identical requests return the same image quickly.
Rate limited. 30 previews per minute. See Rate limits.

Send exactly the same content, signature or signature_id, font_id, and mistake when you create the postcard, so the card matches what you approved.

Get started

Ways to send

Postcards

Account

API reference

Preview a postcard

Request body

Good to know

​Request body

​Good to know

Request body

Good to know