Skip to main content

Installing EmailEngine on Windows

Two ways to run EmailEngine on Windows: the native executable with a Redis-compatible server, or a Linux install inside WSL2.

Overview​

EmailEngine can be installed on Windows using two methods:

  1. Windows Executable - Native Windows binary with Memurai or Redis alternatives
  2. WSL2 - Linux installation inside Windows Subsystem for Linux
Production Recommendation

For production deployments on Windows Server, consider using WSL2 or running EmailEngine on a dedicated Linux VM for better performance and reliability.

Privileges​

EmailEngine does not require administrator privileges to run. You can run it as a regular user on any unprivileged port (e.g., 3000).

Administrator access is only needed during initial setup to:

  • Install Memurai/Redis as a Windows service
  • Create a Windows service for EmailEngine (optional)
  • Bind the SMTP or IMAP proxy to privileged ports (below 1024, such as 465 or 993)

Once installed, EmailEngine can run as an unprivileged user. For privileged ports, consider using a reverse proxy to forward traffic from privileged ports to EmailEngine.

Method 1: Windows Executable​

Native Windows installation using the standalone executable.

Step 1: Install Redis Alternative​

EmailEngine requires Redis, which doesn't officially support Windows. Use one of these alternatives:

Memurai is a Redis-compatible server for Windows.

  1. Download Memurai from https://www.memurai.com/get-memurai
  2. Run the installer (requires admin rights)
  3. Memurai starts automatically as a Windows service

Verify installation:

# Using Memurai CLI
memurai-cli ping
# Should return: PONG

Option B: Redis on WSL2​

If you have WSL2 installed:

# Start WSL2
wsl

# Install Redis in WSL2
sudo apt update
sudo apt install redis-server
sudo service redis-server start

# Exit WSL2
exit

Connect to WSL2 Redis from Windows using redis://localhost:6379

Option C: Redis Docker Container​

# Pull Redis image
docker pull redis:latest

# Run Redis
docker run -d --name redis -p 6379:6379 redis:latest

# Verify
docker exec redis redis-cli ping

Step 2: Download EmailEngine​

Open PowerShell and download the Windows executable:

# Download latest version
Invoke-WebRequest -Uri "https://go.emailengine.app/emailengine.exe" -OutFile "emailengine.exe"

# Or for specific version (e.g., 2.79.4)
Invoke-WebRequest -Uri "https://go.emailengine.app/download/v2.79.4/emailengine.exe" -OutFile "emailengine.exe"

Alternative: Browser download

  1. Visit https://github.com/postalsys/emailengine/releases/latest
  2. Download emailengine.exe
  3. Save to a permanent location (e.g., C:\Program Files\EmailEngine\)

Step 3: Configure EmailEngine​

Generate secrets and create .env file in the same directory as emailengine.exe:

# Generate a random secret (32 random bytes as 64 hex characters)
$secret = -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

# Create .env file with configuration
@"
EENGINE_REDIS=redis://127.0.0.1:6379/8
EENGINE_SECRET=$secret
EENGINE_WORKERS=4
EENGINE_PORT=3000
EENGINE_LOG_LEVEL=info
"@ | Out-File -FilePath ".env" -Encoding UTF8

Write-Host "Configuration saved to .env file"
Write-Host "EENGINE_SECRET=$secret"

Important: EmailEngine reads a .env file from the directory it is started in (the working directory, not the directory the executable sits in), and variables already set in the environment take precedence over the file. Keep this file secure and back it up.

Step 4: Test Run​

# Run EmailEngine (it will automatically load .env file)
.\emailengine.exe

In another PowerShell window:

Invoke-WebRequest -Uri "http://localhost:3000/health" | Select-Object -Expand Content
# Should return: {"success":true}

Step 5: Run as Windows Service​

To run EmailEngine as a Windows service, use NSSM (Non-Sucking Service Manager).

Install NSSM:

# Using Chocolatey
choco install nssm

# Or download from https://nssm.cc/download

Create service:

First, ensure your .env file is in C:\Program Files\EmailEngine\ directory.

# Install service via command line
nssm install EmailEngine "C:\Program Files\EmailEngine\emailengine.exe"
nssm set EmailEngine AppDirectory "C:\Program Files\EmailEngine"
nssm set EmailEngine DisplayName "EmailEngine"
nssm set EmailEngine Description "EmailEngine IMAP/SMTP API service"
nssm set EmailEngine Start SERVICE_AUTO_START

# Start service
nssm start EmailEngine

# Check status
nssm status EmailEngine

Note: EmailEngine will automatically load configuration from the .env file in its working directory (C:\Program Files\EmailEngine\). No need to set environment variables in NSSM.

Service management:

# Start service
nssm start EmailEngine

# Stop service
nssm stop EmailEngine

# Restart service
nssm restart EmailEngine

# Remove service
nssm remove EmailEngine confirm

Upgrading Windows Installation​

# Stop service
nssm stop EmailEngine

# Download latest version
Invoke-WebRequest -Uri "https://go.emailengine.app/emailengine.exe" -OutFile "emailengine.exe"

# Replace existing binary
Move-Item -Path "emailengine.exe" -Destination "C:\Program Files\EmailEngine\emailengine.exe" -Force

# Start service
nssm start EmailEngine

# Verify version
& "C:\Program Files\EmailEngine\emailengine.exe" --version

Windows Subsystem for Linux 2 provides better performance and compatibility.

Step 1: Enable WSL2​

# Run as Administrator
wsl --install

# Restart your computer

# Set WSL2 as default
wsl --set-default-version 2

# Install Ubuntu
wsl --install -d Ubuntu-22.04

Step 2: Install EmailEngine in WSL2​

# Start WSL2
wsl

Inside WSL2, follow the binary method of the Linux installation guide:

sudo apt update
sudo apt install redis-server
wget https://go.emailengine.app/emailengine.tar.gz
tar xzf emailengine.tar.gz
sudo mv emailengine /usr/local/bin/

The automated installer is not the right tool here: it provisions a TLS certificate through Caddy for a public hostname, which a WSL2 instance behind the Windows host cannot answer for.

To run EmailEngine as a SystemD service inside WSL2, systemd has to be enabled in the distribution first. Add the following to /etc/wsl.conf inside the distribution and run wsl --shutdown from PowerShell:

[boot]
systemd=true

Step 3: Access from Windows​

EmailEngine running in WSL2 is accessible from Windows at:

  • http://localhost:3000 (if configured on port 3000)

Step 4: Auto-start with Windows​

Create a Windows startup script to launch EmailEngine in WSL2.

Create start-emailengine.bat in C:\Program Files\EmailEngine\:

@echo off
wsl sudo service redis-server start
wsl sudo systemctl start emailengine

The second line assumes EmailEngine is installed as a SystemD service inside WSL2 with systemd enabled as described above. Create the SystemD unit first, or start the binary directly instead.

Add to Windows startup:

  1. Press Win + R
  2. Type shell:startup and press Enter
  3. Create a shortcut to start-emailengine.bat

Why WSL2​

  • Runs the Linux build, which is the one that gets the most testing
  • Redis runs natively rather than through a compatible reimplementation
  • The Linux installation guide, the SystemD unit, and the upgrade script all apply unchanged

Configuration Options​

Create .env file in the same directory as emailengine.exe:

# Required
EENGINE_REDIS=redis://127.0.0.1:6379/8
EENGINE_SECRET=your-secret-key-at-least-32-chars

# Optional
EENGINE_WORKERS=4
EENGINE_PORT=3000
EENGINE_LOG_LEVEL=info
EENGINE_LOG_RAW=false

EmailEngine automatically loads this file on startup. This is the recommended approach for Windows installations.

Alternative: TOML Configuration File​

You can also use config.toml in the same directory as emailengine.exe:

[service]
secret = "your-secret-key-at-least-32-chars"

[dbs]
redis = "redis://127.0.0.1:6379/8"

[api]
port = 3000
host = "0.0.0.0"

[workers]
imap = 4

[log]
level = "info"
raw = false

The section and key names are those of the config/default.toml shipped with EmailEngine, so EENGINE_WORKERS corresponds to workers.imap, not to a key under [api].

Run with config file:

.\emailengine.exe --config="C:\Program Files\EmailEngine\config.toml"

Note: The same file can be named by the NODE_CONFIG_PATH environment variable instead of --config; both fill the same slot. A TOML file can carry every setting, service.secret included, so nothing else has to be passed on the command line.

See Also​