List postcards

curl --request GET \
  --url https://paperjoy.co/api/postcards \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://paperjoy.co/api/postcards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://paperjoy.co/api/postcards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://paperjoy.co/api/postcards"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://paperjoy.co/api/postcards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "pc_7H2nlRUb1r",
      "test_mode": false,
      "address": {
        "line_1": "ul. Piotrkowska 100",
        "line_2": null,
        "postal_code": "90-001",
        "country": "PL",
        "city": "Łódź"
      },
      "recipient": {
        "prefix": null,
        "first_name": "Tomasz",
        "last_name": "Lewandowski",
        "company_name": null
      },
      "content": "Thank you for being with us for a whole year!",
      "signature": "Marta from the Linden Florist",
      "signature_id": null,
      "font_id": "font-1",
      "mistake": false,
      "status": "sent",
      "submitted_at": "2026-10-11T14:31:00+00:00",
      "sent_at": "2026-10-15T14:31:00+00:00",
      "created_at": "2026-10-11T14:31:00+00:00",
      "updated_at": "2026-10-15T14:31:00+00:00"
    }
  ],
  "links": {
    "first": "https://paperjoy.co/api/postcards?page=1",
    "last": "https://paperjoy.co/api/postcards?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://paperjoy.co/api/postcards?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "path": "https://paperjoy.co/api/postcards",
    "per_page": 50,
    "to": 1,
    "total": 1
  }
}

GET

api

postcards

List postcards

curl --request GET \
  --url https://paperjoy.co/api/postcards \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://paperjoy.co/api/postcards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://paperjoy.co/api/postcards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://paperjoy.co/api/postcards"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://paperjoy.co/api/postcards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "pc_7H2nlRUb1r",
      "test_mode": false,
      "address": {
        "line_1": "ul. Piotrkowska 100",
        "line_2": null,
        "postal_code": "90-001",
        "country": "PL",
        "city": "Łódź"
      },
      "recipient": {
        "prefix": null,
        "first_name": "Tomasz",
        "last_name": "Lewandowski",
        "company_name": null
      },
      "content": "Thank you for being with us for a whole year!",
      "signature": "Marta from the Linden Florist",
      "signature_id": null,
      "font_id": "font-1",
      "mistake": false,
      "status": "sent",
      "submitted_at": "2026-10-11T14:31:00+00:00",
      "sent_at": "2026-10-15T14:31:00+00:00",
      "created_at": "2026-10-11T14:31:00+00:00",
      "updated_at": "2026-10-15T14:31:00+00:00"
    }
  ],
  "links": {
    "first": "https://paperjoy.co/api/postcards?page=1",
    "last": "https://paperjoy.co/api/postcards?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://paperjoy.co/api/postcards?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "path": "https://paperjoy.co/api/postcards",
    "per_page": 50,
    "to": 1,
    "total": 1
  }
}

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.

Query Parameters

page

integer

default:1

The page to return, starting at 1. A page past the end returns an empty data array.

Required range: x >= 1

per_page

integer

default:50

How many postcards to return per page.

Required range: 1 <= x <= 100

status

enum<string>

Return only postcards with this status, for example draft. Where the postcard is in production. Treat unknown values as "in progress".

Available options:

draft,

new,

queued,

rejected,

pair_claimed,

in_progress,

pair_completed,

sent

Response

One page of postcards in the API key's mode.

One page of postcards with Laravel's pagination links and metadata.

data

object[]

required

Show child attributes

links

object

required

URLs of neighbouring pages. prev and next are null at the ends of the list.

Show child attributes

Get started

Ways to send

Postcards

Account

API reference

List postcards

Authorizations

Query Parameters

Response