Quickstart: your first postcard via the API

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 and a terminal with curl.

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.

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

Create a test API key

Open Ustawienia → Klucze API (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_.

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

export PAPERJOY_API_KEY="pj_test_..."

Create a test postcard

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:

{
  "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.

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.

Check the status

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.

Go live

When your integration works:

Turn off test mode in the account menu.
Buy credits if your balance is empty.
Create a new API key. It starts with pj_live_.
Replace the test key in your integration.

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

Next steps

Write the card

Fonts, line breaks, signatures, and how much text fits.

Preview before you order

Render the card as a PNG for free.

Create a postcard

Every field, validation rule, and safe retries.

Handle errors

Status codes, rate limits, and what to retry.

Get started

Ways to send

Postcards

Account

API reference

Quickstart: your first postcard via the API

Next steps

Write the card

Preview before you order

Create a postcard

Handle errors

​Next steps

Write the card

Preview before you order

Create a postcard

Handle errors

Next steps