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

# Quickstart: your first postcard via the API

> Send your first postcard through the API in five minutes, safely in test mode.

You'll create a test postcard, check its status, and then switch to live. Test postcards are free and are never written or mailed, so you can run every step without risk.

**You need:** a [Paperjoy account](https://paperjoy.co/register) and a terminal with `curl`.

**1. Turn on test mode**

In the Paperjoy app, open the account menu in the top right corner and turn on **Tryb testowy** (Test mode).

![The account menu with the Tryb testowy switch.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/account-menu.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=7373cd87ba02e1fd4e2df93bc78819ac)

A **Tryb testowy** banner stays at the top of every page while test mode is on.

**2. Create a test API key**

Open [**Ustawienia → Klucze API**](https://paperjoy.co/settings/api-tokens) (Settings → API keys), enter a name such as `quickstart`, and click **Utwórz klucz** (Create key).

![The API keys page in test mode, showing a newly created key that starts with pj\_test\_.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/api-token-created.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=a997ac0e3d3f99ffd7eb6d407a6d48b2)

Copy the key now. Paperjoy shows it only once. Check that it starts with `pj_test_`, then save it in your shell:

```bash theme={null}
export PAPERJOY_API_KEY="pj_test_..."
```

**3. Create a test postcard**

```bash theme={null}
curl https://paperjoy.co/api/postcards \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient": {
      "first_name": "Anna",
      "last_name": "Kowalska"
    },
    "address": {
      "line_1": "ul. Marszałkowska 10",
      "line_2": "m. 4",
      "postal_code": "00-001",
      "city": "Warszawa",
      "country": "PL"
    },
    "content": "Dear Anna,\nthank you for your first order!",
    "signature": "Marta from the Linden Florist",
    "font_id": "font-1"
  }'
```

Paperjoy answers with `201 Created` and the new postcard:

```json theme={null}
{
  "data": {
    "id": "pc_MXP7a4Ni0c",
    "test_mode": true,
    "status": "new",
    "content": "Dear Anna,\nthank you for your first order!",
    "font_id": "font-1",
    "sent_at": null,
    ...
  }
}
```

`"test_mode": true` confirms that no credit was used. Save the `id` to look the postcard up later.

> [!NOTE]
>
> The `Idempotency-Key` header makes retries safe. If the network drops and you're unsure whether the request worked, resend the exact same request with the same key. Paperjoy returns the original postcard instead of creating a second one. See [Create a postcard](https://docs.paperjoy.co/en/postcards/create.md#retry-safely).

**4. Check the status**

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

Shortly after you create it, the status changes from `new` to `queued`. A test postcard stops there; it never enters production. The card also appears on the **Panel** (Dashboard) page while test mode is on.

**5. Go live**

When your integration works:

1. Turn off test mode in the account menu.
2. [Buy credits](https://paperjoy.co/billing) if your balance is empty.
3. Create a new API key. It starts with `pj_live_`.
4. Replace the test key in your integration.

The same request now places a real order and uses one credit.

## Next steps

> [card] [Write the card](https://docs.paperjoy.co/en/postcards/write.md)
>
> Fonts, line breaks, signatures, and how much text fits.

> [card] [Preview before you order](https://docs.paperjoy.co/en/postcards/preview.md)
>
> Render the card as a PNG for free.

> [card] [Create a postcard](https://docs.paperjoy.co/en/postcards/create.md)
>
> Every field, validation rule, and safe retries.

> [card] [Handle errors](https://docs.paperjoy.co/en/reference/errors-and-rate-limits.md)
>
> Status codes, rate limits, and what to retry.


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