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

# Test mode

> Build and check your integration without spending credits or mailing real postcards.

Test mode is a separate sandbox inside your account. Test postcards go through the same validation and content check as live ones, but they are free and Paperjoy never writes or mails them.

![The Paperjoy dashboard in test mode, with the Tryb testowy banner at the top.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/test-mode.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=5669fa402a08656361a09a85d93e50ab)

While test mode is on, a banner shows at the top of every page.

## Turn test mode on or off

Open the account menu in the top right corner of the Paperjoy app and switch **Tryb testowy** (Test mode). To leave, use the same switch or click **Wyłącz tryb testowy** (Turn off test mode) in the banner.

The switch changes what you see in the app and which kind of API key you create next. It does not change existing keys.

## Test each method

> [tab] Editor
>
> Turn on test mode and open **Edytor** (Editor). The send button changes to **Utwórz testową pocztówkę** (Create test postcard).

> [tab] API
>
> Create an API key while test mode is on. It starts with `pj_test_`. Every request made with it runs in test mode, and responses include `"test_mode": true`.
>
> The URLs and request bodies are identical in both modes. Never send a `test_mode` field; the key decides.

> [tab] Zapier
>
> Create a `pj_test_` key and add it as a separate Paperjoy connection in Zapier. Use it while you build and test the Zap, then switch the action to a connection with a `pj_live_` key before you turn the Zap on.

> [tab] MCP
>
> The MCP server has no test mode. It always creates live postcards and uses credits, even when test mode is on in your browser.
>
> Try your message in the editor or with a `pj_test_` API key first, and ask your assistant to confirm each card before it sends.

## What a test postcard does

| | Test | Live |
| - | - | - |
| Costs a credit | No | Yes, one |
| Validation and fit checks | Yes | Yes |
| Content check | Yes | Yes |
| Furthest status | `queued` or `rejected` | `sent` |
| Written and mailed | Never | Yes |

Don't wait for a test postcard to reach `sent`. It stops at `queued`.

## What is kept separate

| Area | Behavior |
| - | - |
| Postcards | Lists, the dashboard, and lookups by ID only show the current mode. A postcard from the other mode returns `404 Not Found`. |
| API keys | The app lists and revokes keys for the current mode only. The 20-key limit counts both modes together. |
| Idempotency keys | The same key can be used once in each mode. |
| Rate limits | Each mode has its own counters with the same limits. |
| Credit balance | Shared. `available_credit_balance` always shows your real balance; test postcards never change it. |

## Go live checklist

**1. Turn off test mode**

Use the account menu or the banner.

**2. Add credits**

Check your balance in [Billing](https://paperjoy.co/billing). Live requests fail with `402` when you have no credits.

**3. Create a live API key**

It starts with `pj_live_`. Store it next to, not instead of, your test key.

**4. Swap the key and send one real card**

Send a single postcard to yourself and follow its status before you turn on bulk sending.

> [!WARNING]
>
> A `pj_live_` key places real orders and spends credits. Never use it in automated tests or CI.


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