Self-hosting
Components, environment variables and the health endpoint.
Components
| Component | Role |
|---|---|
| Web app | REST API and dashboard (Next.js). Stateless, listens on port 3000. |
| Worker | Delivers emails through your providers, sends webhooks and keeps the database schema up to date. |
| PostgreSQL 16 | Source of truth: workspaces, keys, domains, providers and every email. |
| Redis 7 | Delivery queue and rate limiting. If it is down, accepted emails wait in the database and are sent once it is back. |
| Mail server | Your MTA (for example KumoMTA or Postfix) or an external provider. Mailpit in development. |
Local setup
npm install
npm run docker:up # PostgreSQL, Redis and Mailpit (UI on http://localhost:8025)
npm run dev:web # http://localhost:3000
npm run dev:worker # in a second terminalThe worker applies the database schema and pending migrations each time it starts. To run them by hand, use npm run db:migrate. Copy .env.example to .env to change the defaults.
Environment variables
| Variable | Used by | Purpose |
|---|---|---|
DATABASE_URL | Web, worker | PostgreSQL connection string. |
REDIS_URL | Web, worker | Redis connection string. Defaults to redis://localhost:6379. |
SESSION_HMAC_SECRET | Web | Signs dashboard sessions. Required in production, at least 16 characters. |
API_KEY_PEPPER | Web | Secret mixed into API key hashes. Required in production. Changing it invalidates every key. |
MAILFORGE_ENCRYPTION_KEY | Web, worker | Encrypts DKIM keys, provider passwords and webhook secrets in the database. Required in production and identical for web and worker. If you lose it, those secrets cannot be read again. |
INBOUND_WEBHOOK_SECRET | Web | Verifies inbound email requests. Inbound is rejected while it is unset. |
MTA_SMTP_HOST / MTA_SMTP_PORT / MTA_SMTP_SECURE | Web, worker | Mail server used for the first provider route of a new workspace. |
MAILFORGE_TRACKING_BASE_URL | Worker | Public address of the web app, used in tracking links. Required in production for open and click tracking. |
MAILFORGE_ALLOW_UNVERIFIED_SENDERS | Web | Mail from unverified domains is allowed in development and refused in production. Set true or false to force one. |
MAILFORGE_RATE_LIMIT_PER_SEC | Web | Sending requests per second and workspace before the API answers 429. Defaults to 100. |
WORKER_CONCURRENCY | Worker | Emails one worker sends in parallel. Defaults to 20. |
MAILFORGE_WEBHOOK_ALLOW_PRIVATE | Web, worker | Allows webhook endpoints on private addresses. On in development, off in production. |
MAILFORGE_AUTO_MIGRATE | Worker | Set false to stop the worker from updating the database schema when it starts. |
MAILFORGE_SPAM_CHECK_MODE | Web | Pre-send spam check: off, report (default) or enforce. |
MAILFORGE_SPF_HOST | Web | Host placed in the SPF record shown for your domains. |
MAILFORGE_INBOUND_MX_HOST | Web | Host placed in the inbound MX record shown for your domains. |
openssl rand -hex 32Health endpoint
GET
/api/healthNo authenticationReturns 200 when the web app can reach the database and 503 when it cannot. If only Redis is away, the answer stays 200 with degraded: true, because mail is still accepted. Use it for load balancer and uptime checks.
curl https://mail.example.com/api/health{
"ok": true,
"degraded": false,
"service": "mailforge-web",
"database": {
"ok": true,
"latencyMs": 2
},
"redis": {
"ok": true,
"latencyMs": 1
},
"timestamp": "2026-11-20T18:00:00.000Z"
}Production notes
- Serve the web app over HTTPS. In production the session cookie is only sent over secure connections.
- To send from your own server you need outbound port 25, a reverse DNS (PTR) record for the server IP that matches its hostname, and the DNS records of each sending domain.
- Until your own IP has a sending reputation, add AWS SES or Postmark as a second provider so mail has a fallback route.