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

# Create a postcard

> Every field of POST /api/postcards, the validation rules, and how to retry without sending twice.

`POST /api/postcards` places an order. To prepare a card without ordering it, send `"draft": true`; see [Drafts](https://docs.paperjoy.co/en/postcards/drafts.md). With a `pj_live_` key it uses one credit and the card is written and mailed. With a `pj_test_` key it is free and never leaves the sandbox.

```bash theme={null}
curl https://paperjoy.co/api/postcards \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: 4f1c2a9e-6b0d-4d7e-9a51-3c8e2f7b1d20" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient": {
      "prefix": "Pani",
      "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! We hope the flowers brought you a lot of joy.",
    "signature": "Marta from the Linden Florist",
    "font_id": "font-1",
    "mistake": false
  }'
```

## Fields

**recipient** `object` *required*

Who receives the card. Send `first_name`, `company_name`, or both. Optional `prefix` (up to 30 characters) and `last_name`. See [Addresses and envelopes](https://docs.paperjoy.co/en/postcards/supported-countries.md#recipient).

**address** `object` *required*

A Polish address: `line_1`, optional `line_2`, `postal_code` (`00-001`), `city`, and `country` (`PL`). See [Delivery address](https://docs.paperjoy.co/en/postcards/supported-countries.md#delivery-address).

**content** `string` *required*

The message, up to 300 characters. Line breaks are kept. It must fit on the card. See [Write the card](https://docs.paperjoy.co/en/postcards/write.md#message).

**font\_id** `string` *required*

`font-1` (Standard) or `font-2` (Fast). See [Handwriting](https://docs.paperjoy.co/en/postcards/write.md#handwriting).

**signature** `string`

A typed sign-off, up to 50 characters, written on one line. Don't combine with `signature_id`.

**signature\_id** `string`

An active [custom signature](https://docs.paperjoy.co/en/postcards/custom-signatures.md) ID, such as `sig_ZeXOkSQjTp`. Don't combine with `signature`.

**mistake** `boolean` (default: false)

Cross out one word and write it again for a more natural look.

**draft** `boolean` (default: false)

Save the postcard as a free [draft](https://docs.paperjoy.co/en/postcards/drafts.md) instead of ordering it. Every other field becomes optional, and the card and envelope fit checks run when you submit.

Never send `test_mode`. The API key decides the mode.

## Response

`201 Created` with the new postcard. It starts with `"status": "new"` and `submitted_at` set, or with `"status": "draft"` and `"submitted_at": null` for a draft.

```json theme={null}
{
  "data": {
    "id": "pc_MXP7a4Ni0c",
    "test_mode": false,
    "address": {
      "line_1": "ul. Marszałkowska 10",
      "line_2": "m. 4",
      "postal_code": "00-001",
      "country": "PL",
      "city": "Warszawa"
    },
    "recipient": {
      "prefix": "Pani",
      "first_name": "Anna",
      "last_name": "Kowalska",
      "company_name": null
    },
    "content": "Dear Anna,\nthank you for your first order! We hope the flowers brought you a lot of joy.",
    "signature": "Marta from the Linden Florist",
    "signature_id": null,
    "font_id": "font-1",
    "mistake": false,
    "status": "new",
    "submitted_at": "2026-10-17T14:31:48+00:00",
    "sent_at": null,
    "created_at": "2026-10-17T14:31:48+00:00",
    "updated_at": "2026-10-17T14:31:48+00:00"
  }
}
```

Store the `id`. You need it to [track the postcard](https://docs.paperjoy.co/en/postcards/list-and-retrieve.md).

## Retry safely

Networks fail. The `Idempotency-Key` header makes sure a retry never mails the same card twice.

* Generate a new key, such as a UUID, for **each card you intend to send**. Save it with your own record before you call the API.
* If you get **no response** (a timeout or a dropped connection), retry with the **same key and the same body**. If the first request went through, Paperjoy returns the original `201` response with an `Idempotency-Relayed` header. No second card is created and no second credit is used.
* If you change the body of a postcard that was already created, use a **new key**. Reusing a key that succeeded with a different body returns `409 Conflict`.

Paperjoy remembers only **successful** responses, for 7 days per key. Errors such as `402`, `422`, or `429` are not stored, so once you fix the cause you can retry with the same key, even with a corrected body.

Keys are scoped to your account and mode. The header is required and can be up to 255 characters long.

> [!TIP]
>
> Derive the key from your own data, for example `order-1042-thank-you-1`. A retry after a crash or a fixed error then reuses the same key automatically.

## What gets checked

Paperjoy rejects the request with `422` and leaves your credits untouched when:

| Check | Error key |
| - | - |
| A required field is missing or too long | The field name, e.g. `content` |
| The postal code isn't `00-001` format, or the country isn't `PL` | `address.postal_code`, `address.country` |
| Neither `first_name` nor `company_name` is set | `recipient.first_name`, `recipient.company_name` |
| `signature` and `signature_id` are both set | `signature`, `signature_id` |
| The message doesn't fit on the card | `content` |
| The signature doesn't fit on one line | `signature` |
| The address doesn't fit on the envelope | `address` |
| The custom signature isn't active or isn't in your plan | `signature_id` |

Other failures: `402` when you have no credits (live only), `400` without an `Idempotency-Key`, and `429` after 100 postcards in a day. See [Errors and rate limits](https://docs.paperjoy.co/en/reference/errors-and-rate-limits.md).

## After you create it

Paperjoy runs an automated content check right away. The postcard moves to `queued`, or to `rejected` with a refund if the message is flagged. Follow it with [Track postcards](https://docs.paperjoy.co/en/postcards/list-and-retrieve.md).


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