> ## 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.

# Postcard statuses

> Every step from order to mailbox, what each status means, and what you can do at each one.

The `status` field shows where a postcard is. Statuses only move forward and you can't set them through the API. A [draft](https://docs.paperjoy.co/en/postcards/drafts.md) moves on only when you submit it.

```mermaid theme={null}
flowchart LR
  draft -.-> new
  new --> queued
  new --> rejected
  queued --> P["Production<br/><small>pair_claimed → in_progress → pair_completed</small>"]
  P --> sent
```

## All statuses

| Status | In the app | What's happening |
| - | - | - |
| `draft` | Szkic | A [draft](https://docs.paperjoy.co/en/postcards/drafts.md). Free, editable, and never written. Submit it to order it. |
| `new` | Nowe zamówienie | Order received. The automated content check is running. |
| `queued` | Przyjęto do realizacji | The check passed. Waiting for a free robot. |
| `rejected` | Odrzucono zamówienie | The check flagged the message. Nothing will be written. |
| `pair_claimed` | Rozpoczęto realizację | A robot picked up the card and its envelope. |
| `in_progress` | W trakcie pisania | The robot addresses the envelope and writes the card in one run. |
| `pair_completed` | W trakcie wysyłki | Card and envelope are ready and on their way to the post office. |
| `sent` | Wysłano | Mailed with Poczta Polska. `sent_at` is set. |

> [!NOTE]
>
> New statuses may be added. Treat any value you don't recognize as "in production" instead of failing.

## Drafts

A postcard created with `"draft": true` starts as `draft`. Drafts are free, are never picked up by a robot, and have `submitted_at` set to `null`. When you [submit a draft](https://docs.paperjoy.co/en/postcards/drafts.md#submit-a-draft), Paperjoy uses one credit, sets `submitted_at`, and the postcard moves to `new`. Drafts that don't change for 30 days are deleted.

Every postcard ordered directly, without a draft, has `submitted_at` equal to its creation time.

## Rejected

Every message passes an automated content check before production. If it's flagged as offensive or harmful, the postcard moves to `rejected`:

* Nothing is written or mailed.
* For live postcards, the credit is returned to your balance automatically.
* You can send a reworded message as a new postcard with a new `Idempotency-Key`.

## Test postcards

Test postcards go through the content check too, so they reach `queued` or `rejected`. They never move further and are never written or mailed.

## Sent

When a postcard reaches `sent`, `sent_at` holds the time it was handed to Poczta Polska. From there, delivery follows normal domestic letter mail.

```json theme={null}
{
  "data": {
    "id": "pc_7H2nlRUb1r",
    "status": "sent",
    "sent_at": "2026-10-15T14:31:00+00:00",
    ...
  }
}
```


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