Getting Started

Getting Started

Requirements

• Node.js 23.6 or newer to develop (it runs the TypeScript server directly); the production bundle runs on Node 20+.
• An IMAP server (port 993 TLS, or 143 STARTTLS) and an SMTP server (465 TLS, or 587 STARTTLS) for each mail domain.
• A TLS reverse proxy in front of it (the login cookie is Secure in production). See Deployment.
• Optional: openssl ≥ 1.1.1 with cms for S-MIME; a ManageSieve service for Mail Rules.

Quick start

git clone https://github.com/antongpopov/goodmail.git
cd goodmail
npm install
npm run setup      # a short wizard: asks for your domains and servers, checks them, writes goodmail.conf

Or by hand:

npm install
cp goodmail.conf.example goodmail.conf   # edit the domains
npm run dev        # API on :3000 + Vite on :5173

Production

npm run build      # dist/ (web) + dist-server/index.mjs (single-file server bundle)
NODE_ENV=production PORT=3000 node dist-server/index.mjs

deploy/goodmail.service in the repository is an example systemd unit. Put the process behind a TLS reverse proxy; the page and the API are both served by the Node process, so the proxy only has to forward everything to it. See Deployment.

First sign-in

Open the site and sign in with a full mailbox address and its password. If a domain is not listed in goodmail.conf, the sign-in says "This server doesn't handle mail for …" (add the domain, or set autodiscover=true, see Configuration).

Tests

npm test           # unit tests plus a live-server smoke test
npm run typecheck