Self-hosting

Components, environment variables and the health endpoint.

Components

ComponentRole
Web appREST API and dashboard (Next.js). Stateless, listens on port 3000.
WorkerDelivers emails through your providers, sends webhooks and keeps the database schema up to date.
PostgreSQL 16Source of truth: workspaces, keys, domains, providers and every email.
Redis 7Delivery queue and rate limiting. If it is down, accepted emails wait in the database and are sent once it is back.
Mail serverYour MTA (for example KumoMTA or Postfix) or an external provider. Mailpit in development.

Local setup

Terminal
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 terminal

The 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

VariableUsed byPurpose
DATABASE_URLWeb, workerPostgreSQL connection string.
REDIS_URLWeb, workerRedis connection string. Defaults to redis://localhost:6379.
SESSION_HMAC_SECRETWebSigns dashboard sessions. Required in production, at least 16 characters.
API_KEY_PEPPERWebSecret mixed into API key hashes. Required in production. Changing it invalidates every key.
MAILFORGE_ENCRYPTION_KEYWeb, workerEncrypts 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_SECRETWebVerifies inbound email requests. Inbound is rejected while it is unset.
MTA_SMTP_HOST / MTA_SMTP_PORT / MTA_SMTP_SECUREWeb, workerMail server used for the first provider route of a new workspace.
MAILFORGE_TRACKING_BASE_URLWorkerPublic address of the web app, used in tracking links. Required in production for open and click tracking.
MAILFORGE_ALLOW_UNVERIFIED_SENDERSWebMail from unverified domains is allowed in development and refused in production. Set true or false to force one.
MAILFORGE_RATE_LIMIT_PER_SECWebSending requests per second and workspace before the API answers 429. Defaults to 100.
WORKER_CONCURRENCYWorkerEmails one worker sends in parallel. Defaults to 20.
MAILFORGE_WEBHOOK_ALLOW_PRIVATEWeb, workerAllows webhook endpoints on private addresses. On in development, off in production.
MAILFORGE_AUTO_MIGRATEWorkerSet false to stop the worker from updating the database schema when it starts.
MAILFORGE_SPAM_CHECK_MODEWebPre-send spam check: off, report (default) or enforce.
MAILFORGE_SPF_HOSTWebHost placed in the SPF record shown for your domains.
MAILFORGE_INBOUND_MX_HOSTWebHost placed in the inbound MX record shown for your domains.
Generate secrets
openssl rand -hex 32

Health endpoint

GET/api/healthNo authentication

Returns 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
Response
{
  "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.