Skip to main content
Reading postcards is free. You only see postcards from your own account and from the API key’s mode.

​
Retrieve one postcard

The response has the same shape as the create response. The fields that change over time are:
​
string
Where the postcard is in production. See Postcard statuses.
​
string | null
When the postcard was ordered, in ISO 8601. null while it’s a draft.
​
string | null
When the postcard was mailed, in ISO 8601. null until the status is sent.
​
string
The last time the status changed.

​
List postcards

Returns the postcards in the key’s mode, newest first, one page at a time. The data array holds the postcards on this page.
​
integer
default:"1"
The page to return, starting at 1. A page past the end returns an empty data array.
​
integer
default:"50"
How many postcards to return per page, from 1 to 100. A larger value returns 422 Unprocessable Content.
​
string
Return only postcards with this status, for example draft to list your drafts. An unknown value returns 422.
Next to data, the response has links with the first, last, prev, and next page URLs, and meta with current_page, last_page, per_page, and total. To read the whole list, follow links.next until it is null.

​
Know when a card is mailed

Paperjoy doesn’t send webhooks. To follow delivery, check each open postcard on a schedule:
  1. Store the id of every postcard you create.
  2. Every few hours, retrieve the postcards that aren’t sent or rejected yet.
  3. When status becomes sent, record sent_at and stop checking that postcard.
A postcard changes status only a handful of times, so checking a few times a day is enough.
Prefer retrieving single postcards by ID over listing everything. It stays fast as your history grows.

​
In the app

The Panel (Dashboard) shows the same postcards with their status, filterable by status. Click a row to see the card preview, the postcard ID, and the delivery address.
The Paperjoy dashboard with a chart of ordered and sent postcards and a table of postcards with their recipients and statuses.