# Llamatrust Lightning Inbox

Temporary and persistent email inboxes for verification-code retrieval. Pay with Bitcoin Lightning. No user account signup required.

## What This Is

Each inbox is a unique email alias (default style: `word.word.word_1988a@inbox.llamatrust.ai`).
Activate it with a Lightning micropayment. Receive email. Retrieve extracted verification codes via API.
Lease expires automatically. Pay to extend. Persistent inboxes can preserve alias continuity beyond the active lease window.

## Quickstart for Agents

### Step 1 — Get a client token (one-time, reusable)

POST https://inbox.llamatrust.ai/api/v1/client-tokens/request
Content-Type: application/json

Response:
  request_id  — save this
  invoice     — BOLT11 Lightning invoice to pay

POST https://inbox.llamatrust.ai/api/v1/client-tokens/activate
Content-Type: application/json
{ "request_id": "<request_id>" }

Response:
  token         — bearer token for all subsequent requests
Store this token. It is required for inbox creation and ID-based management routes.

### Step 2 — Create an inbox

POST https://inbox.llamatrust.ai/api/v1/inboxes
Authorization: Bearer <client_token>
Content-Type: application/json

Optional JSON body:
  mode         — "ephemeral" (default) or "persistent"
  alias_style  — "reddit" (default) or "four_word"

Response:
  inbox_id      — inbox ID
  alias         — alias only
  email         — full email address to use
  retrieval_token — mailbox-scoped secret for retrieval routes
  ownership_token — returned only for persistent inboxes; save this carefully
  invoice       — BOLT11 invoice to activate the inbox
  payment_hash  — settlement reference
  expires_in_hours — initial lease length

Token roles:
  client_token     — create / renew / archive / ID-based management
  retrieval_token  — mailbox-scoped retrieval routes
  ownership_token  — persistent inbox continuity / renew-by-token / release

### Step 3 — Pay the invoice

Pay the BOLT11 invoice using any Lightning wallet or API.
The inbox activates automatically on payment confirmation.

### Step 4 — Check inbox status

GET https://inbox.llamatrust.ai/api/v1/inboxes/<id>/status
Authorization: Bearer <client_token>

or

GET https://inbox.llamatrust.ai/api/v1/inboxes/token/<retrieval_token>/status

Response:
  status        — "awaiting_payment" | "active" | "grace" | "expired" | "archived"
                  persistent inboxes may also enter "sleeping"
  alias         — email address
  expires_at    — unix timestamp

### Step 5 — Poll for codes

GET https://inbox.llamatrust.ai/api/v1/inboxes/token/<retrieval_token>/codes

Response:
  codes[]       — extracted verification results, newest first
    code        — predicted best candidate (e.g. "123456")
    candidates  — ordered array of plausible extracted values
    received_at — unix timestamp
    method      — e.g. "regex:code-is-digits"

Notes:
  - The API currently returns a primary predicted candidate plus candidate alternatives.
  - Magic-link and token-style emails may surface as opaque token candidates today.
  - First-class ranked links[] are not yet exposed separately from codes/candidates.

### Step 6 — Extend lease (optional)

POST https://inbox.llamatrust.ai/api/v1/inboxes/<id>/renew
Authorization: Bearer <client_token>

Response:
  invoice       — BOLT11 invoice to pay for extension
  retrieval_token — same mailbox retrieval token

For persistent inboxes:

POST https://inbox.llamatrust.ai/api/v1/inboxes/renew-by-token
Content-Type: application/json
{ "ownership_token": "<ownership_token>" }

POST https://inbox.llamatrust.ai/api/v1/inboxes/ownership/<ownership_token>/release

### Step 7 — Release inbox (optional but good hygiene)

POST https://inbox.llamatrust.ai/api/v1/inboxes/<id>/archive
Authorization: Bearer <client_token>

## Claim / Ack Flow (for verified one-time retrieval)

Create a single-use claim token, retrieve it once, then acknowledge:

POST /api/v1/inboxes/token/<retrieval_token>/claims
GET  /api/v1/inboxes/token/<retrieval_token>/claims/<claim_token>
POST /api/v1/inboxes/token/<retrieval_token>/claims/<claim_token>/ack

Claim tokens expire after 120 seconds by default.

## Error Responses

All errors return JSON:
  { "error": "<message>" }

Common status codes:
  400 — bad request / missing fields
  401 — unauthorized (missing or invalid client token)
  402 — payment required (inbox not yet activated)
  404 — inbox not found or expired
  409 — duplicate request
  410 — inbox archived or expired
  500 — internal error

## Pricing

- Client token:  5 sats / 30 days
- Inbox lease:   100 sats / 2 hours (default TTL)
- Extensions:    available via /renew

## Data Policy

Mailbox access depends on the returned tokens. If you lose the relevant token, practical control may be lost.
Ephemeral inboxes are lease-based and should not be treated as durable long-term mailboxes.
Persistent inboxes preserve alias continuity, but not indefinite message history.
Do not rely on post-expiry message recovery outside the agreed pickup / retention window.
No user accounts. Payments are pseudonymous via Lightning Network.

## Base URL

https://inbox.llamatrust.ai

## Health Check

GET https://inbox.llamatrust.ai/health
→ { "ok": true, "domain": "inbox.llamatrust.ai" }