> ## 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. # List postcards > Returns your postcards in the API key's mode, newest first, one page at a time. Use `page` and `per_page` to move through the list, and follow `links.next` until it is `null`. Requires the `postcards:read` ability. ## OpenAPI ````yaml /en/openapi.yaml get /api/postcards openapi: 3.1.0 info: title: Paperjoy API version: '2026-10-19' description: >- Create, preview, and track real handwritten postcards. The API key decides whether a request runs in test or live mode. termsOfService: https://paperjoy.co/regulamin license: name: Proprietary url: https://paperjoy.co/regulamin servers: - url: https://paperjoy.co security: - bearerAuth: [] tags: - name: Account description: The authenticated account and its credit balance. - name: Postcards description: Create, preview, list, and retrieve postcards. - name: Signatures description: Custom handwritten signatures available to your organization. paths: /api/postcards: get: tags: - Postcards summary: List postcards description: >- Returns your postcards in the API key's mode, newest first, one page at a time. Use `page` and `per_page` to move through the list, and follow `links.next` until it is `null`. Requires the `postcards:read` ability. operationId: listPostcards parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/StatusFilter' responses: '200': description: One page of postcards in the API key's mode. content: application/json: schema: $ref: '#/components/schemas/PostcardList' example: 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: '« Previous' page: null active: false - url: https://paperjoy.co/api/postcards?page=1 label: '1' page: 1 active: true - url: null label: Next » page: null active: false path: https://paperjoy.co/api/postcards per_page: 50 to: 1 total: 1 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' components: parameters: Page: name: page in: query required: false description: >- The page to return, starting at 1. A page past the end returns an empty `data` array. schema: type: integer minimum: 1 default: 1 PerPage: name: per_page in: query required: false description: How many postcards to return per page. schema: type: integer minimum: 1 maximum: 100 default: 50 StatusFilter: name: status in: query required: false description: Return only postcards with this status, for example `draft`. schema: $ref: '#/components/schemas/PostcardStatus' schemas: PostcardList: type: object description: One page of postcards with Laravel's pagination links and metadata. required: - data - links - meta properties: data: type: array items: $ref: '#/components/schemas/Postcard' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' PostcardStatus: type: string description: >- Where the postcard is in production. Treat unknown values as "in progress". enum: - draft - new - queued - rejected - pair_claimed - in_progress - pair_completed - sent Postcard: type: object required: - id - test_mode - recipient - signature - signature_id - mistake - status - submitted_at - sent_at - created_at - updated_at properties: id: type: string examples: - pc_MXP7a4Ni0c test_mode: type: boolean description: >- `true` for a test postcard. Test postcards are free and are never written or mailed. address: description: The delivery address. Can be `null` only in a draft. oneOf: - $ref: '#/components/schemas/Address' - type: 'null' recipient: oneOf: - $ref: '#/components/schemas/Recipient' - type: 'null' content: type: - string - 'null' maxLength: 300 description: The message. Can be `null` only in a draft. signature: type: - string - 'null' maxLength: 50 description: >- The typed signature, or `null` when the postcard uses a custom signature. signature_id: type: - string - 'null' description: The custom signature used on the postcard, or `null`. examples: - sig_ZeXOkSQjTp font_id: description: The handwriting. Can be `null` only in a draft. oneOf: - $ref: '#/components/schemas/FontId' - type: 'null' mistake: type: boolean description: >- Whether one word is crossed out and rewritten to look naturally handwritten. status: $ref: '#/components/schemas/PostcardStatus' submitted_at: type: - string - 'null' format: date-time description: When the postcard was ordered. `null` while it's a draft. sent_at: type: - string - 'null' format: date-time description: When the postcard was mailed. `null` until the status is `sent`. created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time PaginationLinks: type: object description: >- URLs of neighbouring pages. `prev` and `next` are `null` at the ends of the list. required: - first - last - prev - next properties: first: type: string format: uri last: type: string format: uri prev: type: - string - 'null' format: uri next: type: - string - 'null' format: uri PaginationMeta: type: object description: Where this page sits in the full list. required: - current_page - from - last_page - links - path - per_page - to - total properties: current_page: type: integer minimum: 1 from: type: - integer - 'null' description: >- Position of the first postcard on this page, or `null` when the page is empty. last_page: type: integer minimum: 1 links: type: array description: >- Page links for building a pager: previous, each page number, then next. items: type: object required: - url - label - page - active properties: url: type: - string - 'null' format: uri label: type: string page: type: - integer - 'null' active: type: boolean path: type: string format: uri description: The list URL without query parameters. per_page: type: integer minimum: 1 maximum: 100 to: type: - integer - 'null' description: >- Position of the last postcard on this page, or `null` when the page is empty. total: type: integer minimum: 0 description: Number of postcards in the API key's mode. Error: type: object required: - message properties: message: type: string ValidationError: type: object required: - message - errors properties: message: type: string errors: type: object additionalProperties: type: array items: type: string Address: type: object required: - line_1 - postal_code - country - city properties: line_1: type: string maxLength: 255 description: Street and building number. examples: - ul. Marszałkowska 10 line_2: type: - string - 'null' maxLength: 255 description: Apartment, floor, or other detail. examples: - m. 4 postal_code: type: string pattern: ^\d{2}-\d{3}$ examples: - 00-001 country: type: string enum: - PL city: type: string maxLength: 255 examples: - Warszawa Recipient: type: object description: Send `first_name`, `company_name`, or both. properties: prefix: type: - string - 'null' maxLength: 30 examples: - Pani first_name: type: - string - 'null' maxLength: 255 last_name: type: - string - 'null' maxLength: 255 company_name: type: - string - 'null' maxLength: 255 FontId: type: string enum: - font-1 - font-2 description: >- `font-1` is clear, rounded handwriting. `font-2` is a faster, joined-up cursive. responses: Unauthorized: description: The API key is missing, invalid, revoked, or expired. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Unauthenticated. Forbidden: description: >- The API key lacks the required ability, or the resource belongs to someone else. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: This action is unauthorized. ValidationError: description: >- A field is invalid, the text does not fit on the card or envelope, or the `Idempotency-Key` is longer than 255 characters. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/Error' examples: field: summary: Invalid field value: message: The selected font id is invalid. errors: font_id: - The selected font id is invalid. card_fit: summary: Message does not fit on the card value: message: >- The content does not fit on the postcard. Shorten it or remove blank lines. errors: content: - >- The content does not fit on the postcard. Shorten it or remove blank lines. envelope_fit: summary: Address does not fit on the envelope value: message: The sender or recipient address does not fit on the envelope. errors: address: - >- The sender or recipient address does not fit on the envelope. draft_limit: summary: Too many open drafts value: message: >- You already have 100 open drafts. Submit or delete some of them before saving another draft. errors: draft: - >- You already have 100 open drafts. Submit or delete some of them before saving another draft. signature_unavailable: summary: Custom signature unavailable value: message: >- The selected signature is unavailable or is not active for your plan. errors: signature_id: - >- The selected signature is unavailable or is not active for your plan. securitySchemes: bearerAuth: type: http scheme: bearer description: >- A Paperjoy API key. Keys starting with `pj_test_` use test mode; keys starting with `pj_live_` use live mode. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.