API & developers

Getting started with the API

Use plain HTTP against this deployment: list domains, open a temporary inbox, then read messages with the inbox token returned from open. Account API keys unlock member-tier domains when opening an inbox. There is no billing here; premium is manual via Contact.

Trouble signing in? From Log in, use Forgot password. If you registered but are still pending, open Account to enter your activation code.

Prerequisites

Guests can call public endpoints and open guest-tier inboxes. To use ?api_key= on open, register, verify your email, then create a key on this page after sign-in.

Lost your password? Use Forgot password from the login page.

Step 0 — Health check (optional)

Confirms the app can reach the database. No API key or inbox token.

curl -sS "https://your-domain.example/api/ready"

Step 1 — List available domains

GET /api/public/domains returns enabled hostnames. Pick one for the local part of your disposable address.

curl -sS "https://your-domain.example/api/public/domains"

Step 2 — Open (create) an inbox

POST /api/inbox/open with JSON body { "email": "local@domain" }. Append ?api_key=YOUR_API_KEY when you need member-tier domains (verified account). Omit the query param for guest-only domains.

curl -sS -X POST "https://your-domain.example/api/inbox/open?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Response includes token (inbox JWT), inboxId, and activeUntil. Use token in Step 3 — it is not the same as your account API key.

Step 3 — List messages

GET /api/inbox/messages requires the inbox token from Step 2. Either pass ?token=… or Authorization: Bearer … (same JWT).

Option A — query string

curl -sS "https://your-domain.example/api/inbox/messages?token=YOUR_INBOX_TOKEN"

Option B — Authorization header

curl -sS -H "Authorization: Bearer YOUR_INBOX_TOKEN" \
  "https://your-domain.example/api/inbox/messages"

Step 4 — Keep-alive, polling, realtime

Heartbeat — POST /api/inbox/heartbeat with JSON { "token": "…" } extends the session (browser UI does this on a timer).
Polling — repeat Step 3 on an interval if Redis/SSE is unavailable.
SSE — GET /api/inbox/stream with the same inbox token (Bearer or ?token=) when Redis is configured; otherwise use polling.

Heartbeat example

curl -sS -X POST "https://your-domain.example/api/inbox/heartbeat" \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_INBOX_TOKEN"}'

Authentication cheat sheet

Account API key (verified members only) — used so open can resolve member-tier domain access. Preferred for scripts: append ?api_key=… to the /api/inbox/open URL. Also supported: X-API-Key or Authorization: Bearer … on that same request.

Query parameters may be logged by proxies and browsers. For production integrations in hostile networks, prefer sending the account key in headers instead of the query string.

Inbox token — short-lived JWT returned by open. Use it for messages, heartbeat, stream. Pass ?token=… or Authorization: Bearer ….

Access tiers

Guest — no account API key; guest-tier domains only on open.
Member — verified email; API keys within plan limits; member + guest domains for open.
Premium — data-level higher access; upgrades only via Contact.

Reference

Key storage, issuance, and HTTP errors: docs/PART_2_API_KEYS.md. Auth and activation: docs/PART_2_AUTH_PLAN.md.

Not built here: Swagger portal, org sharing, admin key console, usage analytics dashboards, or automated key rotation wizards.

← Home About Contact