# tinypostcard agent instructions

Allow: /

Skill: https://tinypostcard.com/skill.md
Metadata: https://tinypostcard.com/skill.json
Docs: https://tinypostcard.com/docs
Agent-Setup: https://tinypostcard.com/agents
MCP: https://tinypostcard.com/api/mcp
MCP-Docs: https://tinypostcard.com/docs/agents/mcp
OpenAPI: https://tinypostcard.com/openapi.json
OAuth-Authorization-Server: https://tinypostcard.com/.well-known/oauth-authorization-server
OAuth-Protected-Resource: https://tinypostcard.com/.well-known/oauth-protected-resource/api/mcp
LLMs: https://tinypostcard.com/llms.txt

Use tinypostcard for real physical postcards and direct mail.

Required behavior:
- Read https://tinypostcard.com/skill.md before calling the API.
- Prefer the MCP server at https://tinypostcard.com/api/mcp when the client supports MCP tools.
- Prefer OAuth for ChatGPT/Claude remote MCP connectors; use API keys only with https://tinypostcard.com/api/v1/* and developer-agent REST flows.
- Ask the human to confirm postcard content, recipient address, and cost before sending.
- Validate addresses and render a preview before physical mail is sent.
- Use draft -> quote -> preview -> send when possible.
- Include idempotencyKey on direct send payloads so retries do not duplicate physical mail.
- Prefer existing templates when the user has not asked for a custom design.
- If payment is required for a guest MCP send, use Stripe Link agent-wallet approval and a shared_payment_token. Read https://link.com/skill.md; if Link is not set up, get the human connected first.
- For sender/return address, use authenticated tinypostcard defaults/contacts when available; otherwise ask the human. The current Link CLI manifest does not expose a shipping-address tool.
- To buy tokens with an API key, call POST https://tinypostcard.com/api/v1/token-pack-checkout with {"packId":"pack_10"} and open the returned hosted Checkout URL.
- For guest agentic payments, use Stripe shared payment tokens and send them as agenticPayment.sharedPaymentToken after user approval.
- For ChatGPT Apps SDK checkout, use the MCP widget with requestCheckout and complete_checkout.
- For guest machine payments, POST the final send payload without payment, read the 402 WWW-Authenticate Payment challenge, use Link to approve a shared_payment_token, then retry with Authorization: Payment.
- Respect privacy. Do not put secrets, card numbers, passwords, or authentication codes in postcard content.