Draft postcards: prepare, review, and send later

A draft is a postcard that hasn’t been ordered yet. It’s free, it’s never written or mailed, and you can change it as often as you like. When it’s ready, submit it: Paperjoy then checks it, uses one credit, and the postcard continues as a normal order.

Create a draft

Send "draft": true to POST /api/postcards. Every field is optional, so you can save a draft before you know the address or the final text.

curl https://paperjoy.co/api/postcards \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: draft-order-1042" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "draft": true,
    "recipient": { "first_name": "Anna", "last_name": "Kowalska" },
    "content": "Dear Anna,\nthank you for your first order!",
    "font_id": "font-1"
  }'

The response is 201 Created with "status": "draft" and "submitted_at": null. Creating a draft:

uses no credit and doesn’t need a credit balance;
doesn’t count toward the daily limit of 100 postcards;
checks each field you send (length, postal code format, font), but not whether the text fits on the card or the address fits on the envelope. Those checks run when you submit.

You can have up to 100 open drafts per account in each mode. Beyond that, creating a draft returns 422 with an error on draft. Submit or delete some drafts first. Without draft, or with "draft": false, POST /api/postcards orders the postcard right away, as before.

Edit a draft

PATCH /api/postcards/{id} changes only the fields you send. Send null to clear a field. address and recipient are replaced as a whole, so send all their parts.

curl --request PATCH https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "address": {
      "line_1": "ul. Marszałkowska 10",
      "postal_code": "00-001",
      "city": "Warszawa",
      "country": "PL"
    }
  }'

Response	When
`200 OK`	The draft was updated.
`409 Conflict`	The postcard was already submitted. Only drafts can be changed.
`422`	A field is invalid, or you sent a field a postcard doesn’t have, such as `status`.

You can’t set status yourself. A draft becomes an order only when you submit it. To check how the draft looks, use POST /api/postcards/preview with the same content, signature, and font_id.

Submit a draft

POST /api/postcards/{id}/submit orders the draft. It needs no body, but it does need an Idempotency-Key.

curl --request POST https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c/submit \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: submit-order-1042" \
  --header "Accept: application/json"

Paperjoy validates the draft exactly like a new postcard, including card and envelope fit. If it passes, it uses one credit (live only), sets "status": "new" and submitted_at, and starts the content check.

Response	When
`200 OK`	The postcard was ordered. A retry with the same key returns this response again, with an `Idempotency-Relayed` header, and charges nothing.
`402 Payment Required`	Live mode and less than one credit. The postcard stays a draft.
`409 Conflict`	The postcard was already submitted, or the key was used before for a different request.
`422`	The draft is incomplete or doesn’t fit. `errors` lists the fields to fix. The postcard stays a draft.
`429`	The daily limit of 100 postcards was reached.

A draft is never charged twice. After a 402 or 422, fix the cause and submit again with the same key.

Delete a draft

curl --request DELETE https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json"

204 No Content when the draft is gone. Deleting is permanent. Submitted postcards can’t be deleted and return 409.

Find your drafts

GET /api/postcards?status=draft lists only drafts. See Track postcards.

Unused drafts are deleted after 30 days

Paperjoy permanently deletes drafts that haven’t changed for 30 days. Editing a draft resets the clock. Submitted postcards are never deleted this way.

In the Paperjoy app

In the editor, Zapisz szkic (Save draft) saves the card as a draft without using a credit. The dashboard has a Szkice (Drafts) tab: open a draft to edit it, then click Wyślij (1 kredyt) (Send, 1 credit) or Usuń szkic (Delete draft). Drafts created by your AI assistant through the MCP server appear in the same tab, so you can review them before anything is sent.

Get started

Ways to send

Postcards

Account

API reference

Draft postcards: prepare, review, and send later

Create a draft

Edit a draft

Submit a draft

Delete a draft

Find your drafts

Unused drafts are deleted after 30 days

In the Paperjoy app

​Create a draft

​Edit a draft

​Submit a draft

​Delete a draft

​Find your drafts

​Unused drafts are deleted after 30 days

​In the Paperjoy app

Create a draft

Edit a draft

Submit a draft

Delete a draft

Find your drafts

Unused drafts are deleted after 30 days

In the Paperjoy app