curl --request POST \
  --url https://paperjoy.co/api/postcards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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",
  "font_id": "font-1",
  "mistake": false
}
'

{
  "data": {
    "id": "pc_MXP7a4Ni0c",
    "test_mode": true,
    "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"
  }
}

Create a postcard

Creates a postcard in the API key’s mode. A pj_live_ key places a real order and uses one credit. A pj_test_ key creates a free test postcard that is never written or mailed.

With "draft": true it saves a free draft instead: every field is optional, no credit is used, and the draft doesn’t count toward the daily limit. You can have up to 100 open drafts in each mode. Order the draft with POST /api/postcards/{id}/submit.

Send a unique Idempotency-Key header with every new postcard. Requires the postcards:write ability.

POST

api

postcards

curl --request POST \
  --url https://paperjoy.co/api/postcards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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",
  "font_id": "font-1",
  "mistake": false
}
'

{
  "data": {
    "id": "pc_MXP7a4Ni0c",
    "test_mode": true,
    "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"
  }
}

Authorizations

Authorization

string

header

required

A Paperjoy API key. Keys starting with pj_test_ use test mode; keys starting with pj_live_ use live mode.

Headers

Idempotency-Key

string

required

A unique key for this postcard, such as a UUID. Paperjoy remembers keys for 7 days. Retrying with the same key and the same body returns the original response without creating another postcard.

Maximum string length: 255

Body

application/json

address, recipient, content, and font_id are required unless you send draft set to true.

address

object

required

Show child attributes

recipient

object

required

Send first_name, company_name, or both.

Show child attributes

content

string

required

The handwritten message. Line breaks (\n) and blank lines are kept. The text must fit on the card; see the card_fit validation error.

Maximum string length: 300

font_id

enum<string>

required

font-1 is clear, rounded handwriting. font-2 is a faster, joined-up cursive.

Available options:

font-1,

font-2

signature

string | null

A sign-off written on one line at the bottom of the card. Do not send together with signature_id.

Maximum string length: 50

signature_id

string | null

An active custom signature ID from GET /api/signatures. Requires a plan with custom signatures. Do not send together with signature.

Example:

"sig_ZeXOkSQjTp"

mistake

boolean

default:false

Cross out one word and write it again, like a real person would. The same message always gets the same correction.

draft

boolean

default:false

true saves a free draft instead of ordering. The other fields are then optional.

Response

The postcard was created.

data

object

required

Show child attributes

Get started

Ways to send

Postcards

Account

API reference

Create a postcard

Authorizations

Headers

Body

Response