Skip to main content
POST /api/postcards places an order. To prepare a card without ordering it, send "draft": true; see Drafts. With a pj_live_ key it uses one credit and the card is written and mailed. With a pj_test_ key it is free and never leaves the sandbox.

​
Fields

​
object
required
Who receives the card. Send first_name, company_name, or both. Optional prefix (up to 30 characters) and last_name. See Addresses and envelopes.
​
object
required
A Polish address: line_1, optional line_2, postal_code (00-001), city, and country (PL). See Delivery address.
​
string
required
The message, up to 300 characters. Line breaks are kept. It must fit on the card. See Write the card.
​
string
required
font-1 (Standard) or font-2 (Fast). See Handwriting.
​
string
A typed sign-off, up to 50 characters, written on one line. Don’t combine with signature_id.
​
string
An active custom signature ID, such as sig_ZeXOkSQjTp. Don’t combine with signature.
​
boolean
default:"false"
Cross out one word and write it again for a more natural look.
​
boolean
default:"false"
Save the postcard as a free draft instead of ordering it. Every other field becomes optional, and the card and envelope fit checks run when you submit.
Never send test_mode. The API key decides the mode.

​
Response

201 Created with the new postcard. It starts with "status": "new" and submitted_at set, or with "status": "draft" and "submitted_at": null for a draft.
Store the id. You need it to track the postcard.

​
Retry safely

Networks fail. The Idempotency-Key header makes sure a retry never mails the same card twice.
  • Generate a new key, such as a UUID, for each card you intend to send. Save it with your own record before you call the API.
  • If you get no response (a timeout or a dropped connection), retry with the same key and the same body. If the first request went through, Paperjoy returns the original 201 response with an Idempotency-Relayed header. No second card is created and no second credit is used.
  • If you change the body of a postcard that was already created, use a new key. Reusing a key that succeeded with a different body returns 409 Conflict.
Paperjoy remembers only successful responses, for 7 days per key. Errors such as 402, 422, or 429 are not stored, so once you fix the cause you can retry with the same key, even with a corrected body. Keys are scoped to your account and mode. The header is required and can be up to 255 characters long.
Derive the key from your own data, for example order-1042-thank-you-1. A retry after a crash or a fixed error then reuses the same key automatically.

​
What gets checked

Paperjoy rejects the request with 422 and leaves your credits untouched when: Other failures: 402 when you have no credits (live only), 400 without an Idempotency-Key, and 429 after 100 postcards in a day. See Errors and rate limits.

​
After you create it

Paperjoy runs an automated content check right away. The postcard moves to queued, or to rejected with a refund if the message is flagged. Follow it with Track postcards.