API & developers

GetNada API — integrate temporary email & inboxes

The GetNada API lets you automate disposable email: list domains, open temporary inboxes, and fetch messages with the token from open. Build apps that create throwaway addresses, poll inboxes, or wire verification flows without hosting mail yourself. API keys unlock member-tier domains. 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.

RegisterLog 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. 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, 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 (or POST /api/account/inboxes / …/inboxes/<id>/open for private create/refresh). 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.

← HomeAboutContact