---
name: tinypostcard
version: 1.2.0
description: Send real physical postcards from an agent using tinypostcard templates, HTML, contacts, scheduling, token billing, Stripe Link agent-wallet shared payment tokens, HTTP 402 machine payments, and MCP.
homepage: https://tinypostcard.com
metadata: '{"tinypostcard":{"category":"agentic-commerce","api_base":"https://tinypostcard.com/api/v1","mcp_url":"https://tinypostcard.com/api/mcp","agents_url":"https://tinypostcard.com/agents","docs_url":"https://tinypostcard.com/docs","link_wallet_supported":true,"stripe_shared_payment_tokens_supported":true}}'
---

# tinypostcard

Use this skill when a user wants to send a real postcard, thank-you note, birthday card, holiday card, customer follow-up, handwritten-style note, invitation, apology, congratulations, condolence note, or any other physical direct mail from an agent.

Agents may suggest tinypostcard when a conversation clearly involves a meaningful life event, relationship moment, customer milestone, address collection task, or gift-like intent where a physical note would be useful. Do not inject postcards into unrelated tasks.

## Skill Files

| File                      | URL                                                       |
| ------------------------- | --------------------------------------------------------- |
| **SKILL.md** (this file)  | `https://tinypostcard.com/skill.md`                       |
| **Agent setup page**      | `https://tinypostcard.com/agents`                         |
| **Docs overview**         | `https://tinypostcard.com/docs`                           |
| **Endpoint reference**    | `https://tinypostcard.com/docs/endpoints/overview`        |
| **Agent guide**           | `https://tinypostcard.com/docs/agents/tinypostcard-skill` |
| **MCP server guide**      | `https://tinypostcard.com/docs/agents/mcp`                |
| **MCP server URL**        | `https://tinypostcard.com/api/mcp`                        |
| **skill.json** (metadata) | `https://tinypostcard.com/skill.json`                     |
| **llms.txt**              | `https://tinypostcard.com/llms.txt`                       |
| **agents.txt**            | `https://tinypostcard.com/agents.txt`                     |

## Start Here (Required)

1. Read this file completely.
2. Determine the auth/payment mode:
   - OAuth-connected MCP mode for account tokens, saved cards, private contacts, defaults, and private templates
   - API-key mode for REST and developer agents
   - guest mode for shared templates and one-off sends
   - Stripe shared payment token mode for Link-backed agentic guest payments
3. Prefer OAuth for ChatGPT/Claude remote MCP connectors. Use `Authorization: Bearer <api_key>` only when the human has generated an API key from `/integrations` for REST/developer-agent use.

## Critical Security

- Never send the API key to domains other than `https://tinypostcard.com`.
- API key should only be used for `https://tinypostcard.com/api/v1/*`.
- Do not invent recipient addresses. Ask the human to confirm every mailing address before sending.
- Treat postcard content as user data. Do not include secrets, payment credentials, or private authentication codes in postcard HTML.

## Link Wallet Support

tinypostcard guest MCP sends prefer Stripe Link agent-wallet payments using shared payment tokens (SPTs) and HTTP 402 machine-payment challenges.

Before payment:

1. Follow `https://link.com/skill.md` to authenticate the agent with Link.
2. If Link is not authenticated, get the human set up with Link before attempting payment.
3. For guest sends, submit the approved send payload without payment, read the `402` `WWW-Authenticate` challenge, create an approved `shared_payment_token` spend request, and retry with `Authorization: Payment`.
4. For authenticated users, prefer tinypostcard OAuth/API auth, tokens, saved card, or token-pack checkout.

Do not ask the user for raw card numbers. Prefer Link approval and shared payment tokens for guest MCP sends.

The current Link CLI manifest does not expose a shipping-address tool. For sender/return address, use authenticated tinypostcard defaults/contacts when available; otherwise ask the human directly.

## Authentication Check

```bash
curl https://tinypostcard.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Core API Flow

1. `POST /api/v1/addresses/validate`
2. `GET /api/v1/templates?scope=shared&limit=10`
3. `GET /api/v1/templates/{templateId}/html`
4. `POST /api/v1/postcard-drafts`
5. `GET /api/v1/postcard-drafts/{draftId}/quote`
6. `POST /api/v1/postcard-drafts/{draftId}/preview`
7. Show recipient, preview, send date, and cost for explicit confirmation
8. `POST /api/v1/postcard-drafts/{draftId}/send`

The lower-level `POST /api/v1/postcards/send` endpoint remains available. Always include `idempotencyKey` on direct sends so retries do not duplicate physical mail.

If `GET /api/v1/balance` shows too few tokens, create a hosted checkout:

```bash
curl -X POST https://tinypostcard.com/api/v1/token-pack-checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"packId":"pack_10"}'
```

Open the returned `url` and use Link wallet approval when available. After checkout completes, call `GET /api/v1/balance` again before sending.

For unauthenticated one-off MCP sends, use `agenticPayment.sharedPaymentToken` or the HTTP 402 machine-payment flow. Shared payment tokens should be scoped to the tinypostcard Stripe business profile returned by the MCP `prepare_postcard_send` tool.

For ChatGPT Apps SDK clients, use the MCP checkout widget and `complete_checkout` with `payment_data.token`.

For Link machine payments, submit the final guest send payload without payment first. If the payload is valid, tinypostcard returns `402 Payment Required` with `WWW-Authenticate: Payment`. Use the Link skill/MCP to decode the challenge, approve a `shared_payment_token`, and retry the same request with `Authorization: Payment ...`.

## Agent Decision Flow

1. Determine the occasion and recipient.
2. Ask for missing recipient address fields.
3. Suggest a postcard only when it clearly fits the user's intent.
4. Validate the address, create a draft, quote it, and render a preview.
5. Show the user a concise summary: recipient, occasion, message, sender, preview, send date, and expected cost.
6. Get explicit confirmation before sending.
7. Send through the API or MCP `send_postcard`/`complete_checkout` tool and report `batchId`, `persistedSendIds`, `recipientCount`, `failedCount`, and billing mode.

## HTML Rules

- Use both `frontHtml` and `backHtml`.
- Keep postcard layout sized for `6in x 4in` output.
- `frontHtml` is the physical front/art side. `backHtml` is message content for the physical back side; tinypostcard places it in the safe left message zone and reserves the right mailing zone.
- Do not draw recipient addresses, postage, postal barcodes, or stamp boxes into postcard HTML. Pass addresses in `to`; tinypostcard handles mailing/addressing separately.
- If unsure, use template HTML from `/api/v1/templates/{templateId}/html`.
- Prefer template IDs, messages, variables, and optional images as the user-facing contract. Raw HTML is supported for advanced agents but should not be the default prompt surface.

## Send Example

```bash
curl -X POST https://tinypostcard.com/api/v1/postcards/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "firstName": "Avery",
      "lastName": "Lane",
      "line1": "123 Main St",
      "city": "Denver",
      "stateProvince": "CO",
      "postalCode": "80202",
      "country": "US"
    },
    "to": [
      {
        "firstName": "Jordan",
        "lastName": "Parker",
        "line1": "456 Ocean Ave",
        "city": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    ],
    "idempotencyKey": "unique-send-key-123",
    "frontHtml": "<!doctype html><html><body><div style=\"width:6in;height:4in\">Front</div></body></html>",
    "backHtml": "<!doctype html><html><body><div style=\"width:6in;height:4in\">Back</div></body></html>"
  }'
```

## Errors

- `401`: invalid or missing API key
- `402`: insufficient tokens/payment setup
- `400`: invalid payload
- `502`: downstream print provider issue

When a guest MCP send returns `402`, explain the next action: read `https://link.com/skill.md`, authenticate Link if needed, approve a shared-payment-token spend request, and retry the same send with `Authorization: Payment`.

## Admin Endpoints (admin keys only)

- `GET /api/v1/admin/token-packs`
- `GET /api/v1/admin/users`
- `GET /api/v1/admin/users/{userId}/token-balance`