--- name: tinypostcard version: 1.0.0 description: External API skill for sending physical postcards with HTML, templates, and token billing. homepage: https://tinypostcard.com metadata: {"tinypostcard":{"category":"productivity","api_base":"https://tinypostcard.com/api/v1"}} --- # tinypostcard Use this skill to search templates, render postcard HTML, and send postcards through `https://tinypostcard.com/api/v1`. ## Skill Files | File | URL | |------|-----| | **SKILL.md** (this file) | `https://tinypostcard.com/skill.md` | | **Docs overview** | `https://tinypostcard.com/docs` | | **Endpoint reference** | `https://tinypostcard.com/docs/endpoints/overview` | | **Agent guide** | `https://tinypostcard.com/docs/agents/tinypostcard-skill` | | **skill.json** (metadata) | `https://tinypostcard.com/skill.json` | ## Start Here (Required) 1. Read this file completely. 2. Confirm your human has done all prerequisites: - signed up to tinypostcard - purchased tokens - generated an API key from `/integrations` 3. Use `Authorization: Bearer ` on all API calls. ## 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/*`. ## Authentication Check ```bash curl https://tinypostcard.com/api/v1/me \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Core API Flow 1. `GET /api/v1/me` 2. `GET /api/v1/balance` 3. `GET /api/v1/templates?scope=shared&limit=10` 4. `GET /api/v1/templates/{templateId}/html` 5. `POST /api/v1/postcards/send` ## HTML Rules - Use both `frontHtml` and `backHtml`. - Keep postcard layout sized for `6in x 4in` output. - If unsure, use template HTML from `/api/v1/templates/{templateId}/html`. ## 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" } ], "frontHtml": "

Front

", "backHtml": "

Back

" }' ``` ## Errors - `401`: invalid or missing API key - `402`: insufficient tokens/payment setup - `400`: invalid payload - `502`: downstream print provider issue ## Admin Endpoints (admin keys only) - `GET /api/v1/admin/token-packs` - `GET /api/v1/admin/users` - `GET /api/v1/admin/users/{userId}/token-balance`