# Real postcards, in the post

> Propose a printed postcard from a day — a person still has to send it.

## Proposing a printed postcard

A journal with `postcards` and `contacts` switched on (check `GET /api/v2/status`'s `capabilities`) can put a real card in somebody's letterbox. **You compose it; you never send it.**

```http
GET /api/v2/{user}/postcards/recipients
```

Answers with a name, a town, a country — **never a street** — for everybody on this journal's contacts list who has asked for a real postcard. A card is addressed by `contactId`, never by an address you were told in a conversation.

```http
PUT /api/v2/{user}/postcards/orders/{id}
Content-Type: application/json
Authorization: Bearer fs_agent_…

| Field | | Type |
| --- | --- | --- |
| `source` | **required** | an object — see /api/v2/openapi.json for its shape or an object — see /api/v2/openapi.json for its shape — `{trip, day, photo}` for a photograph already on a trip, or `{inbox: "<id>"}` for a staged one |
| `message` | **required** | string — the card's own words — the author's, never invented |
| `from` | **required** | string — who it is signed as |
| `recipients` | **required** | a list of {string} — contact ids — 1 to 25 |
| `locale` | optional | string — the language the message is written in; absent means the journal's default |
| `crop` | optional | an object — see /api/v2/openapi.json for its shape |
| `figures` | optional | boolean |
```

**This charges nothing and prints nothing.** It writes a proposal and answers with a `url` on the response document. The owner opens that page, sees the card laid out, its cost and their balance, and presses one button — the only thing in this system that puts a card in the post. Hand over the URL and say a preview is waiting; do not say the cards have been sent.

`GET /api/v2/{user}/postcards/orders/{id}` reads its status back later. `GET /api/v2/{user}/postcards/texts?trip=…` offers each day's opening line, per language, as prefill material for the message — nothing here writes or translates it for you.