Skip to content
BurnerByte

concepts

Demo Mode

A public "try it" inbox on the landing page, off by default.

Demo mode lets logged-out visitors create a real, short-lived disposable inbox on the landing page (and the /try route) and watch real mail arrive, without signing up. It is off by default and adds no public surface until you provision and enable it.

How it works

  • A visitor calls POST /api/v1/try/inbox, which creates an inbox under a dedicated demo user/domain with a short TTL, and polls GET /api/v1/try/inbox/{id}/emails for incoming mail.
  • Creation is rate-limited per IP, sharing the login bucket (rate_limit.login, default 10/min) — so demo traffic and sign-in attempts contend for the same allowance. Polling has its own bucket, fixed at 60 requests per minute per IP. GET /api/v1/try/status is unlimited.
  • It is receive-only and IDOR-safe: the read endpoint is scoped to the demo user, so only demo inboxes are ever readable. Inboxes expire on the TTL and are removed by the cleanup worker.

Prerequisites

  1. A domain whose MX record points at your server (see DNS), added and assigned to a team.
  2. A dedicated demo user that is a member of that team. Use a throwaway account, e.g. [email protected].

Anything created through demo mode is owned by this user on this domain, so keep it isolated from real tenants.

Configure

Demo mode needs two IDs: the domain assignment (the domain-to-team link the inbox is created under) and the demo user. The quickest way to find both:

sql
SELECT da.id AS assignment_id, u.id AS user_idFROM domain_assignments daJOIN team_memberships tm ON tm.team_id = da.team_idJOIN users u ON u.id = tm.user_idWHERE u.email = '[email protected]';

Set them via environment variables (or the demo: block in config.yaml):

bash
DEMO_ENABLED=trueDEMO_ASSIGNMENT_ID=<assignment_id>DEMO_USER_ID=<user_id>DEMO_TTL=10m            # optional, defaults to 10m

The IDs are read at startup; DEMO_TTL controls how long each demo inbox lives.

Turn it on and off

Once the IDs are configured, an admin can flip demo mode on or off without a restart from Settings → System → Platform Settings → Demo Mode. If the toggle is on but the IDs aren't configured, the settings page warns you and the demo stays off. GET /api/v1/try/status still answers 200 with {"enabled": false} so the frontend can probe it cheaply; the two inbox endpoints return 404.

Security notes

  • Off unless explicitly enabled and configured with valid IDs.
  • Public endpoints are unauthenticated but rate-limited and receive-only.
  • The read path is scoped to the demo user, so a real user's inbox can never be read through it.
  • Demo inboxes are ephemeral (TTL) and auto-expire.