BurnerByte Documentation
Install BurnerByte with Docker Compose, set up MX and TXT records, harden it for production, and call the REST API — 162 operations across 122 paths.
Which version this describes
Checked against v1.24.0 on 2026-09-18. If you are running something newer, the release notes are the authority on what changed since.
Welcome to BurnerByte
BurnerByte is a self-hosted temporary email platform built for teams that need disposable email addresses for testing, development, and QA workflows. It provides real-time email delivery, configurable attachment policies, webhooks, a full RBAC system, and SSO integration — all running on your own infrastructure.
Note
BurnerByte is open-source under the Apache 2.0 license. Source code is available on GitHub.
Get Started
InstallationPrerequisites, cloning, and initial setupQuick StartRun BurnerByte and receive your first email in minutesDocker SetupRun the full stack with Docker ComposeConfigurationAll config options, env vars, and runtime overridesFirst-Run InstallerBoot with no database configured and set it up from the browser
Core Concepts
RBAC & RolesDynamic permission-based access control with 5 roles across org and team levelsDomains & DNSDomain verification, MX/TXT records, and team assignmentInboxesTemporary inbox lifecycle, TTL management, and Redis routingEmailsMIME parsing, HTML rendering, and attachment handlingWebhooksHMAC-SHA256 signed events with retry and delivery logsAPI KeysScoped programmatic access with SHA-256 hashing and IP allowlistsSSOMulti-provider OIDC integration with auto-provisioning and domain mappingsSettings CascadePolicy inheritance across platform defaults, org, domain, assignment and team
Architecture
System OverviewTwo-binary design, request flow, and key componentsSMTP PipelineHow inbound emails are received, parsed, and storedReal-time & WebSocketLive email delivery and notification streamingDatabase Schema36 tables, 74 indexes, 8 triggersBackground Workers7 periodic jobs: cleanup, DNS, webhooks, reconciler, analytics, invite expiry, admin stats
Deploy & Operate
Production HardeningSecurity checklist, scaling, and backupsReverse ProxyNginx and Caddy configurations with WebSocket supportDNS SetupMX and TXT records for email receivingBackup and RestoreWhat to back up, in what order, and how to restore itUpgradingMoving between releases, version skew, and why migrate-down is not a rollbackMonitoringHealth checks, Prometheus metrics, and structured logging
API & Frontend
API ReferenceAuthentication, pagination, errors, and 162 endpoints across 122 pathsFrontend OverviewNext.js architecture, keyboard shortcuts, and UX patternsThemingCSS variables, color customization, and component libraryTroubleshootingCommon issues and solutions
A Look Around
Every screen of a running instance — inbox creation, live mail, the reader, dashboard, analytics, domains, teams, the audit log and settings — is in the screenshot gallery, full size, with detail on each.
Architecture at a Glance
┌─────────────────┐ Next.js UI ────────▶ │ Go API │ ───▶ PostgreSQL (:3000) │ (:8080) │ ───▶ Redis (pub/sub) │ Chi + Workers │ ───▶ MinIO (attachments) └─────────────────┘ ▲ │ subscribes: live email + notifications │ External MTAs ─────▶ ┌─────────────────┐ (inbound SMTP) │ Go SMTPD │ ──▶ parses + stores, │ (:2525) │ publishes to Redis └─────────────────┘ Two independent Go binaries: cmd/smtpd receives mail and publishes to Redispub/sub; cmd/api persists it, fans out over WebSocket, and serves the UI/API.Two separate Go binaries, which scale differently:
cmd/api— HTTP API server + background workers. Run exactly one: every replica starts all seven workers and there is no leader election, so a second one duplicates every job.cmd/smtpd— SMTP inbound server. Scales out freely.
See Architecture Overview for what that ceiling costs and Background Workers for the jobs involved.
Key Features
| Feature | Description |
|---|---|
| Setup Wizard | Guided first-run setup: admin account, org, SMTP, domain, team, branding, invites |
| Multi-team | Single org with teams scoped to specific domains |
| Full RBAC | 5 roles across org and team levels, DB-backed permissions |
| Real-time | WebSocket streaming for instant email and notification delivery |
| Attachments | Configurable policies inherited across org, domain and assignment |
| Webhooks | HMAC-SHA256 signed with exponential backoff retry |
| API Keys | Scoped programmatic access with SHA-256 hashing and IP allowlists |
| Audit Log | Full activity trail with filtering, search, and CSV export |
| Analytics | Time-series charts, peak hours, domain breakdown, top senders |
| SSO | Multi-provider OIDC with auto-provisioning, domain mappings, claim mappings |
| Private Inboxes | Only the creator can access their inboxes and emails |
| Bulk Operations | Bulk invite, bulk verify, bulk delete, bulk revoke |
Tech Stack
| Layer | Technology |
|---|---|
| Backend | Go 1.25+, Chi router, pgxpool, go-redis, gorilla/websocket, enmime |
| Frontend | Next.js 16, React 19, shadcn/ui, Tailwind CSS 4, Zustand, TanStack Query, Recharts |
| Docs | MDX, published at burnerbyte.com/docs |
| Database | PostgreSQL 16 (50 migrations, 74 indexes, 8 triggers) |
| Cache | Redis 7 (inbox routing, analytics cache, rate limiting) |
| Storage | MinIO or any S3-compatible store for attachments, with a local-filesystem fallback |
| Infrastructure | Docker, Docker Compose |
| CI | GitHub Actions (.github/workflows/ci.yml) — Go tests against live Postgres and Redis, frontend lint/typecheck/test/build, and a full docker compose build |
| Testing | pgregory.net/rapid for property-based testing |