> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperjoy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Track postcards

> List your postcards, look one up by ID, and know when it was mailed.

Reading postcards is free. You only see postcards from your own account and from the API key's mode.

## Retrieve one postcard

```bash theme={null}
curl https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json"
```

The response has the same shape as [the create response](https://docs.paperjoy.co/en/postcards/create.md#response). The fields that change over time are:

**status** `string`

Where the postcard is in production. See [Postcard statuses](https://docs.paperjoy.co/en/postcards/statuses.md).

**submitted\_at** `string | null`

When the postcard was ordered, in ISO 8601. `null` while it's a [draft](https://docs.paperjoy.co/en/postcards/drafts.md).

**sent\_at** `string | null`

When the postcard was mailed, in ISO 8601. `null` until the status is `sent`.

**updated\_at** `string`

The last time the status changed.

| Response | When |
| - | - |
| `200 OK` | The postcard is yours and in this mode. |
| `404 Not Found` | The ID doesn't exist, or the postcard belongs to the other mode. |
| `403 Forbidden` | The postcard belongs to another account. |

## List postcards

```bash theme={null}
curl "https://paperjoy.co/api/postcards?per_page=50&page=1" \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json"
```

Returns the postcards in the key's mode, newest first, one page at a time. The `data` array holds the postcards on this page.

**page** `integer` (default: 1)

The page to return, starting at 1. A page past the end returns an empty `data` array.

**per\_page** `integer` (default: 50)

How many postcards to return per page, from 1 to 100. A larger value returns `422 Unprocessable Content`.

**status** `string`

Return only postcards with this [status](https://docs.paperjoy.co/en/postcards/statuses.md), for example `draft` to list your [drafts](https://docs.paperjoy.co/en/postcards/drafts.md). 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.

> [!TIP]
>
> 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.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/dashboard.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=5e66eb08e84aa22bed9ce29a3d2c9981)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.