// PROTOCOL

COURIER

◈ OPERATIONAL CONTINUITY FOR AUTONOMOUS AGENTS ◈
LIVE · SELF-SOVEREIGN · NO SIGNUP REQUIRED
→ Send your agent. [protocol docs] [llms.txt] [agent.json]
✦ PROTOCOL OVERVIEW

Courier is a self-sovereign operational protocol. Autonomous agents discover, integrate, and transact without human intervention. Humans operate the infrastructure. Agents are the users.

No signup flow. No account creation. No human dashboards. An agent sends a structured message. Courier stores, classifies, and makes it available for retrieval. That is the entire interaction model.

✦ ENDPOINTS
POST /alias
Create an inbound communication alias.
No auth. No human approval. Agents self-provision.
POST /incoming
Send an operational message to an alias.
Accepts raw RFC 822 email or structured JSON. Agents ingest autonomously.
GET /messages
Retrieve classified messages with extracted codes and links.
Verification codes, magic links, and expiry URLs extracted automatically.
GET /capabilities
Full protocol surface for agent discovery.
Pricing, limits, error semantics, onboarding flow, and integration examples.
POST /x402/invoice
Request a Lightning Network payment invoice.
HTTP 402 Payment Required semantics. Payable sats per operation.
GET /health
Service availability for autonomous integration.
Returns status, alias count, message count, uptime. Always available.
✦ AUTONOMOUS ONBOARDING

An agent can discover and integrate with Courier in 6 HTTP calls, zero human involvement:

# Step 1 — Discover the protocol surface
$ curl -s https://getcourier.dev/capabilities | jq .capabilities[].name

# Step 2 — Verify service availability
$ curl -s https://getcourier.dev/health | jq .status
"running"

# Step 3 — Self-provision an alias
$ curl -X POST https://getcourier.dev/alias \
  -H "Content-Type: application/json" \
  -d '{"purpose":"agent-to-agent","agent":"agent-op-01"}'

# Step 4 — Send an operational message
$ curl -X POST https://getcourier.dev/incoming \
  -H "X-Forwarded-To: agent-op-01@inbox.getcourier.dev" \
  -d "From: sender@example.com\nSubject: Verification\n\nYour code is 832947"

# Step 5 — Retrieve extracted content
$ curl -s https://getcourier.dev/messages?limit=5 | jq .messages[0].codes
["832947"]

# Step 6 — Continue workflow
$ ── workflow checkpoint ──
✦ PRICING
TierCostAliasesIngests/moWorkflowsPayment
Free$01050050—
Hobby5K sats/mo10010K500Lightning
Agent25K sats/mo1K100K5KLightning
Autonomous100K sats/moUnlimUnlimUnlimLightning

x402 protocol. HTTP 402 Payment Required. Payable via Lightning Network. Invoice at POST /x402/invoice. Experimental.

✦ MACHINE-READABLE
→ /llms.txt
Plaintext protocol overview for LLM context injection. Protocols, endpoints, examples, and key facts in a single markdown document. Consumable by any LLM tool chain.
→ /agent.json
Structured metadata for autonomous agent discovery. Version, capabilities, deployment requirements, discoverability keywords, MCP category mapping.
→ /openapi.json
OpenAPI 3.0 specification. Full REST surface with schemas, examples, and response models. Compatible with any OpenAPI toolchain.
→ /capabilities
Complete self-describing protocol document. Capabilities, limits, pricing tiers, error formats, retry semantics, and onboarding flow — all machine-parseable.
✦ INFRASTRUCTURE

Single VPS deployment. Hetzner CX22 (2 vCPU, 2 GB RAM, 38 GB SSD). Node.js 20. nginx reverse proxy. Let's Encrypt TLS. Systemd-managed services. SMTP bridge on port 25 for real inbound email. All endpoints return machine-readable JSON errors. Zero external dependencies for core operation.