Quickstart

Requires Bun 1.x.

bun install                # installs all workspaces (apps/api, apps/web, packages/sdk)
bun run web:build          # builds the dashboard to apps/web/dist
bun run api:start          # generates the embedded-asset manifest, runs migrations, starts the server

Admin Onboarding & Authentication

Mail Buddy boots with zero initial configuration required.

When you navigate to http://localhost:3000 for the first time, you are guided through the First-Run Setup wizard to create your primary administrator account. Public registration is permanently disabled. Once logged in, administrators can invite or create additional team members with generated passwords under Configuration > Team Users.

Compiling the single binary

cd apps/api
bun run compile   # -> ../../mail-buddy (regenerates the embedded dashboard manifest first)

The resulting binary is fully self-contained — it runs correctly from any working directory, with the dashboard and DB migrations both embedded. It lands around ~60–65MB (Bun's embedded runtime).

Or grab a prebuilt binary instead of compiling one yourself.

Deployment footprint

The API server and the dashboard are both inside the binary — only two things live outside it by default:

mail-buddy              # the binary itself (API + dashboard)
mail-buddy.sqlite       # the database (path configurable via DATABASE_PATH)
uploads/                # locally-stored assets (only when using local storage provider)

Testing

bun test   # runs all 116 unit + integration tests across the monorepo

Zero-Env & Dynamic Settings

Mail Buddy does not require an .env file. All operational settings (SMTP credentials, storage provider, and server URLs) are persisted dynamically in the SQLite database and configured directly in the web UI.

• SMTP Settings (/settings/smtp): Configure host, port, user, password, and test connectivity in real-time with the "Send Test Email" tool.
• Storage Engine (/settings/storage): Switch between Local filesystem storage and Amazon S3 / S3-compatible buckets.
• API Keys (/settings/api-keys): Issue scoped (admin or send_only) keys for backend services with optional IP and Origin whitelisting.

Storage Engine (Local & S3)

Mail Buddy supports two storage providers:

1. Local Filesystem (Default): Stores uploaded images under ./uploads.
2. Amazon S3 & S3-Compatible: Direct integration with AWS S3, LocalStack, MinIO, Cloudflare R2, and DigitalOcean Spaces. Includes a live "Test S3 Bucket Access" verification tool.

Optional Environment variables

Variable	Default	Notes
PORT	3000	HTTP port
DATABASE_PATH	./mail-buddy.sqlite	SQLite file location
UPLOADS_DIR	./uploads	Local asset storage directory
LOG_LEVEL	info	fatal | error | warn | info | debug | trace | silent

API & SDK

Prefer using mail-buddy-sdk for seamless TypeScript integration:

import { MailBuddyClient } from 'mail-buddy-sdk';

const client = new MailBuddyClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'mb_YOUR_API_KEY',
});

// Single send
await client.send({
  to: 'user@example.com',
  subject: 'Welcome',
  templateId: '123e4567-e89b-12d3-a456-426614174000',
  variables: { username: 'Jane' },
});

// Live template compilation preview
const preview = await client.templates.preview({
  htmlContent: '{{embed "header-id"}}
Order #{{order_id}}
',
  variables: { order_id: '1234' },
});

Monorepo layout

apps/api        Elysia server - REST API, delivery worker, embeds apps/web/dist at compile time
apps/web        React (Vite + Tailwind) admin dashboard
packages/sdk    mail-buddy-sdk - published Node.js client
docs-site       Documentation static website

Releases

The server/dashboard binary and the SDK are versioned and released independently.

• App binary: Pushing a v*.*.* tag builds and attaches cross-platform binaries to a GitHub Release.
• SDK: Pushing an sdk-v*.*.* tag publishes mail-buddy-sdk to npm.

Contributing

Contributions are welcome — see CONTRIBUTING.md for dev setup and CODE_OF_CONDUCT.md for community standards.