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

# Paperjoy Zapier integration

> Send a handwritten postcard automatically when something happens in a form, CRM, or shop.

With Zapier, a new customer, a closed deal, or a birthday on your calendar can trigger a real postcard. No code needed.

> [!NOTE]
>
> The Paperjoy Zapier app is installed through an invitation link. It is not listed in the public Zapier directory yet.

## Install and connect

**1. Accept the invitation**

Open the [Paperjoy invitation](https://zapier.com/developer/public-invite/243427/bb628a44df0a0263531ba127cef5e6cd/) and add Paperjoy to your Zapier account. You can also find the link in the Paperjoy app under **Ustawienia → Integracje** (Settings → Integrations).

**2. Create a test API key**

In Paperjoy, turn on [test mode](https://docs.paperjoy.co/en/getting-started/test-mode.md) and create a key named, for example, `zapier-test` in [**Ustawienia → Klucze API**](https://paperjoy.co/settings/api-tokens). It starts with `pj_test_`.

**3. Connect Paperjoy in Zapier**

When Zapier asks you to connect Paperjoy, paste the key. Name the connection so you can tell it apart later, for example **Paperjoy (test)**.

## Build a Zap

**1. Choose a trigger**

Pick the app and event that should send a card, such as **New Order** in your shop or **Deal Won** in your CRM.

**2. Filter out incomplete records**

Add a **Filter** step so the Zap only continues when the street, postal code, city, and a name or company are present. This stops half-empty records from creating orders.

**3. Add the Paperjoy action**

Choose Paperjoy as the action app and map the fields. Use the table below.

**4. Test the action**

Zapier creates a free test postcard. Check it on the **Panel** (Dashboard) in the Paperjoy app while test mode is on.

**5. Switch to live and publish**

Create a `pj_live_` key, add it as a second connection named **Paperjoy (live)**, select it in the action, and turn the Zap on. Every run now places a real order and uses one credit.

## Field mapping

| Paperjoy field | What to map | Notes |
| - | - | - |
| Recipient | First name, last name, prefix, company | Needs a first name or a company. |
| Address | Street, apartment, postal code, city | Postal code in `00-001` format. Country is `PL`. |
| Message | Your text, with dynamic fields | Up to 300 characters, and it must fit on the card. See [Write the card](https://docs.paperjoy.co/en/postcards/write.md). |
| Signature | A sign-off | Up to 50 characters, written on one line. |
| Font | `font-1` or `font-2` | See [Handwriting](https://docs.paperjoy.co/en/postcards/write.md#handwriting). |
| Mistake | Yes or no | Crosses out one word and rewrites it for a more natural look. |

## Tips for reliable Zaps

* **Keep messages short.** Dynamic fields such as long company names can push a message over the limit. A card that doesn't fit fails instead of being shortened.
* **Use Formatter.** Trim spaces and fix capitalization of names before they reach Paperjoy.
* **Keep test and live connections apart.** Name them clearly so you never publish a Zap that points at the wrong mode.
* **Watch your balance.** A Zap run fails when you have no credits. Top up in [Billing](https://paperjoy.co/billing) and replay the run from Zap history.


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