Getnada API for Temporary Email Workflows

Step 0 — Health check (optional)

Confirms the app can reach the database (and optionally Redis). No API key or inbox token. Response shape: { "status": "ready", "database": "ok", "redis": "ok" } — or HTTP 503 with status: "not_ready" when MariaDB is down. Use GET /api/health for a lightweight liveness probe ({ "ok": true }, no dependency checks).

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

Step 1 — List available domains

GET /api/public/domains returns { domains, items, planMax }. Each item includes domain, partnerExternal (partner mail vs local MX), and for authenticated callers also accessTier / scope (system or personal). Guests see guest-tier hostnames only.

Verified members: append ?api_key=YOUR_API_KEY (or send the key in headers) to include member/premium system domains and active personal domains in the same response.

Guest (default)

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. The JSON response includes visibility (public or private) and recipient.

Public vs private: New addresses opened through this route create a public inbox row unless the address already exists as a private inbox. If the row is private, the server returns HTTP 403 unless the request is authenticated as the owner: either your browser session (signed-in, verified user — same cookies as the site) or an account API key that belongs to that same user. Guests, pending accounts, and other users’ keys cannot open someone else’s private inbox. Public inbox behavior for anonymous open is unchanged when the row is public.

JSON body uses error: "PRIVATE_INBOX_ACCESS_DENIED" for that 403 — useful for scripts; the web UI shows a friendly message instead of the raw code.

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, activeUntil, sessionSeq, recipient, and mailSource (local or partner). 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). Response: { messages: [...], cursor }. Partner domains use string message id values — poll only (no SSE).

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; partner inboxes return 403 PARTNER_POLL_ONLY — use polling instead.

Heartbeat example

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

Step 5 — Read one message

GET /api/inbox/message?id= returns full sanitized HTML body for a single message. Response: { message: { id, subject, from_addr, html_sanitized, text_plain, … } }. Local MX inboxes use numeric id from the messages list; partner inboxes use string uids.

curl -sS -H "Authorization: Bearer YOUR_INBOX_TOKEN" \
  "https://your-domain.example/api/inbox/message?id=MESSAGE_ID"

Step 6 — Mark read (optional)

PATCH /api/inbox/message with JSON { "id": "MESSAGE_ID", "read": true | false } and the inbox JWT. Returns { ok: true }. Partner inboxes accept the call but do not persist read state server-side.

curl -sS -X PATCH "https://your-domain.example/api/inbox/message" \
  -H "Authorization: Bearer YOUR_INBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"MESSAGE_ID","read":true}'

Step 7 — Close inbox (optional)

POST /api/inbox/close ends the inbox session when your automation finishes with the temporary email address.

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

SSE stream example

When Redis is configured, subscribe to new-mail events instead of polling Step 3. Not available for partner (partnerExternal: true) domains.

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

Authentication cheat sheet

Endpoint reference

Complete Getnada temporary email API surface for temp mail automation, inbox monitoring, and member account management.

Common error codes

Reference docs

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.