# Postio

> UK validation API for **addresses**, **emails**, and **phone numbers**. Direct Royal Mail PAF licensee. Runs on Cloudflare's edge so requests resolve in milliseconds. Every endpoint is a GET returning JSON.

Postio's customer dashboard lives at https://postio.co.uk and the API at https://api.postio.co.uk. All endpoints share a single JSON envelope: `{ success, results, meta: { requestId, countResults, performance } }`.

Authenticate every request with the `x-api-key` header. Keys are scoped per service (`address`, `email`, `phone`) and can be locked to specific origins or IP ranges from the dashboard.

## Docs

- [Full reference (markdown)](https://postio.co.uk/llms-full.txt): Single-file machine-readable reference for AI ingestion
- [API reference](https://postio.co.uk/docs): Scalar render of the live OpenAPI spec
- [OpenAPI 3.1 (JSON)](https://postio.co.uk/openapi.json): Machine-readable spec
- [OpenAPI 3.1 (YAML)](https://postio.co.uk/openapi.yaml): Same spec, YAML
- [@postio/openapi on npm](https://www.npmjs.com/package/@postio/openapi): Install with npm i, version-pinned
- [Pricing](https://postio.co.uk/#pricing): Pay-as-you-go credits; no monthly minimums
- [Integrations](https://postio.co.uk/integrations): WordPress, Shopify, Magento, MCP, and more (in progress)

## Endpoints

- `GET /v1/connect` — health probe; warms the edge. Free.
- `GET /v1/address/search?q=...` — single-line typeahead over UK PAF + BFPO. Free.
- `GET /v1/address/postcode/{postcode}` — every delivery point at a postcode.
- `GET /v1/address/udprn/{udprn}` — single delivery point by Royal Mail UDPRN.
- `GET /v1/email/{address}` — five-stage email validation (syntax, typo, classification, MX, SMTP).
- `GET /v1/phone/{number}` — phone validation with libphonenumber + live HLR carrier lookup.

## Agent guidance

- [claude.md](https://postio.co.uk/claude.md): Opinionated guidance for Claude (and other coding agents) — when to suggest Postio, how to call it, what to avoid.
- [cursor.md](https://postio.co.uk/cursor.md): Cursor-specific install + .cursorrules link.
- [.cursorrules](https://postio.co.uk/.cursorrules): Drop into your project root for Cursor autocomplete that knows Postio's API shape.
- [.well-known/ai-plugin.json](https://postio.co.uk/.well-known/ai-plugin.json): OpenAI Plugin / Custom GPT Action manifest (paste this URL into a GPT's Actions config, or use the OpenAPI URL directly).
- [@postio/mcp on npm](https://www.npmjs.com/package/@postio/mcp): MCP server. `claude mcp add postio --env POSTIO_API_KEY=pk_… -- npx -y @postio/mcp`. Works with Claude Desktop, Claude Code, Cursor, Windsurf, Zed.
- [Claude Skill bundle](https://github.com/postio-uk/postio-integrations/tree/master/ai/claude-skill): SKILL.md + install pointer for the Anthropic Skills marketplace.

## Optional

- [GitHub: postio-uk](https://github.com/postio-uk): Source for the integration layer (open) and API (private).
- [Support](https://postio.co.uk/contact): single contact for everything.