Everything you need to
self-host MailFlow

Quick Start

MailFlow runs entirely in Docker. You need Docker Engine 24+ and Docker Compose v2 installed on your server. No other dependencies are required.

1. 1

   Download the compose file and default config

   These two commands fetch the latest pre-built compose file and a template .env.

   bash Copy

   curl -o docker-compose.yml https://raw.githubusercontent.com/maathimself/mailflow/main/docker-compose.ghcr.yml
   curl -o .env               https://raw.githubusercontent.com/maathimself/mailflow/main/.env.example

2. 2

   Generate secrets and configure .env

   Open .env in your editor. Four fields are required:

   bash Copy

   # Generate secrets (run once for each)
   openssl rand -hex 32   # → SESSION_SECRET
   openssl rand -hex 16   # → DB_PASSWORD
   openssl rand -hex 32   # → ENCRYPTION_KEY
   
   # Then edit .env — minimum required fields:
   APP_URL=https://mail.example.com
   SESSION_SECRET=<output from above>
   DB_PASSWORD=<output from above>
   ENCRYPTION_KEY=<output from above>

3. 3

   Start the containers

   bash Copy

   docker compose up -d

4. 4

   Create your admin account

   Open https://your-domain.com in a browser. The first account you register becomes the admin. After registering, go to Settings → Users to close registration or invite others.

5. 5

   Add your email accounts

   Go to Settings → Accounts → Add Account. Choose a preset (Gmail, iCloud) or enter custom IMAP/SMTP details. See Email Providers below for per-provider instructions.

Option A — Pre-built Images

The recommended installation method. Docker pulls pre-built images directly from GitHub Container Registry — no cloning or building required. MailFlow exposes HTTPS on port 443 and HTTP on port 80 by default. Choose the deployment scenario that fits your setup:

Browser ─── HTTPS:443 ──► nginx (self-signed TLS) ─┬─► Node.js API
        └── HTTP:80  ──► nginx (plain HTTP)         └─► WebSocket
                                                          │
                                                   ┌──────┴──────┐
                                                   ▼             ▼
                                              PostgreSQL        Redis

APP_PORT=443       # HTTPS port (self-signed cert)
APP_HTTP_PORT=80   # HTTP port (no TLS)

Internet ──HTTPS──► Your Proxy ──────────────── HTTP:80 ──► nginx ──► backend
                     (Nginx / Caddy / Traefik)
                     X-Forwarded-Proto: https   ◄── required for Secure cookies

server {
    listen 443 ssl;
    server_name mail.example.com;
    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Real-IP         $remote_addr;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

mail.example.com {
    reverse_proxy localhost:80
    # Caddy automatically sets X-Forwarded-Proto and handles TLS
}

# Add to the frontend service in docker-compose.yml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.mailflow.rule=Host(`mail.example.com`)"
  - "traefik.http.routers.mailflow.entrypoints=websecure"
  - "traefik.http.routers.mailflow.tls.certresolver=letsencrypt"
  - "traefik.http.services.mailflow.loadbalancer.server.port=80"
  - "traefik.http.middlewares.mailflow-proto.headers.customrequestheaders.X-Forwarded-Proto=https"
  - "traefik.http.routers.mailflow.middlewares=mailflow-proto"

Internet ──HTTPS──► Caddy :443 ──► nginx :443 (internal, TLS) ──► backend
                   (auto Let's Encrypt TLS)

Option B — Build from Source

Clone the repository and build the Docker images locally. Useful if you want to modify MailFlow or follow the development branch.

git clone https://github.com/maathimself/mailflow.git mailflow
cd mailflow
cp .env.example .env
# edit .env with your secrets (see Step 2 above), then:
docker compose up -d --build

The first build takes 2–3 minutes. For Let's Encrypt from source:

docker compose -f docker-compose.yml -f docker-compose.https.yml --profile https up -d --build

Email Provider Setup

MailFlow supports any standard IMAP/SMTP server. Provider-specific instructions are below.

Environment Variables

All configuration lives in .env. The four required fields must be set before starting; everything else is optional.

User Management

The first account registered on a fresh installation automatically becomes the admin. The admin has access to the full Settings panel including user management, system email, and integrations.

Closing registration

After creating your account, close open registration so no one else can self-register: go to Settings → Users and disable Open registration. Use the invite system to onboard additional users.

Inviting users

From Settings → Users, click Invite User. You can either copy an invite link to send manually, or have MailFlow send an invitation email automatically (requires a system email account to be configured in Settings → Users → System Email).

Two-factor authentication

MailFlow supports three 2FA methods, configurable per user from Settings → Security:

Admin enforcement policy — Admins can require 2FA for all users under Settings → Security → MFA Policy. Options are off (users opt in) or required (enforced on next login). Admin accounts should always have 2FA enabled regardless of policy.

SSO / OIDC

MailFlow supports single sign-on via any OpenID Connect provider (Authelia, Keycloak, Authentik, etc.). Configure in Settings → SSO. Once configured, users can log in with their SSO credentials instead of a local password. You can also optionally disable password login entirely so that SSO is the only sign-in method.

Group claim → admin role mapping — If your identity provider includes group membership in the OIDC token, MailFlow can automatically grant the admin role to members of a specified group. In Settings → SSO, set the Group claim name (e.g. groups) and the Admin group value to the group identifier your IdP uses. Any user whose token contains that value in the specified claim will be promoted to admin on sign-in.

Integrations

Todoist

Connect a Todoist account to create tasks directly from emails. Once linked, a Todoist button appears in the message toolbar.

1. 1

   Link your Todoist account

   Go to Settings → Apps → Todoist and click Connect Todoist. You'll be redirected to Todoist to authorise access, then returned to MailFlow.

2. 2

   Create a task from an email

   Open any email and click the Todoist icon in the message toolbar. Choose a project, set a due date and priority, and click Add Task. The task is created in Todoist with a link back to the email subject.

Backups & Restore

MailFlow's state lives entirely in the PostgreSQL database (messages, accounts, users, settings). Back it up regularly — a daily cron job is recommended for production deployments.

Backup

docker exec mailflow-postgres pg_dump -U mailflow mailflow \
  > mailflow-$(date +%Y%m%d).sql

Restore

cat mailflow-YYYYMMDD.sql | \
  docker exec -i mailflow-postgres psql -U mailflow -d mailflow

Updates

Database migrations run automatically on startup — no manual steps required when updating.

Pre-built images (Option A)

docker compose pull
docker compose up -d

Build from source (Option B)

git pull
docker compose up -d --build

Command Reference

# View all container logs (live)
docker compose logs -f

# View backend logs only
docker compose logs -f backend

# Restart all containers
docker compose restart

# Stop all containers (data preserved)
docker compose down

# Stop and delete all data volumes (destructive — no undo)
docker compose down -v

# Check container health
docker compose ps

Security Hardening

MailFlow ships with sensible defaults. Follow these steps for a production-hardened deployment:

• Close open registration — go to Settings → Users and disable open registration as soon as your admin account is created.
• Enable TOTP 2FA — especially for the admin account (Settings → Security).
• Use strong secrets — generate all three secrets with openssl rand, never reuse them across installs.
• Use HTTPS — either the built-in Let's Encrypt profile or your own TLS-terminating reverse proxy. Never expose MailFlow over plain HTTP on the internet.
• Protect the server — PostgreSQL and Redis are not exposed outside the Docker network by default. Don't publish their ports.
• Back up regularly — IMAP credentials are encrypted at rest. Losing the ENCRYPTION_KEY means users must re-enter passwords, so back up both the database and your .env.
• Rate limiting is on by default — login and registration are limited to 10 attempts per 15 minutes per IP. No configuration needed.
• Session cookies are HttpOnly, SameSite=Lax, with a 7-day TTL. The Secure flag is set automatically when HTTPS is detected.

Adding Email Accounts

MailFlow supports an unlimited number of email accounts per user. Each account connects via IMAP for reading and SMTP for sending.

1. 1

   Open the account settings

   Click the gear icon (Settings) → Accounts → Add Account.

2. 2

   Choose a preset or enter custom details

   Select Gmail or iCloud for automatic server configuration, or choose Custom and enter your IMAP host, port, SMTP host, and port manually.

3. 3

   Enter your credentials

   Your username (usually your email address) and password (App Password for Gmail/iCloud — see Email Providers). MailFlow tests the connection before saving.

4. 4

   Wait for the initial sync

   MailFlow fetches recent messages in the background. You'll see them appear in the unified inbox within a few seconds.

Interface Overview

Reading Mail

Composing Email

Click the compose button (pencil icon) or use the keyboard shortcut C to open the compose window.

• From address — automatically selected based on the account you're viewing. Change it with the From dropdown to send from any connected account.
• Smart address parsing — paste comma-separated addresses including display names like Smith, John <[email protected]> and they'll parse correctly.
• Rich text editor — format text, add links, and insert images. Choose your font family group and font size directly from the composer toolbar. Switch to plain text mode if preferred.
• Reply & Forward — use the Reply, Reply All, and Forward buttons in the message toolbar. Original message is quoted automatically.
• Email priority — set message priority (low, normal, high, or urgent) from the composer toolbar. Recipients see the priority flag in their mail client.
• Per-account SMTP routing — each account uses its own SMTP server. Replies are automatically sent from the same account that received the original message.

Search

MailFlow's full-text search scans across all connected accounts simultaneously. Results are sorted by relevance and show the matching account and folder.

Keyboard Shortcuts

MailFlow supports a full set of keyboard shortcuts. Press ? at any time to view the shortcut reference inside the app. All shortcuts are customisable in Settings → Shortcuts. Use Ctrl+K (or ⌘+K on Mac) to open the command palette.

Appearance

Open Settings → Appearance to customize how MailFlow looks.

Notifications

MailFlow supports two types of new-mail notifications:

In-app toast notifications

Real-time WebSocket toasts appear at the bottom of the screen whenever new mail arrives — no configuration required. These work as long as you have MailFlow open in a browser tab.

Unread badges

MailFlow can display unread counts as badges in two places, each independently togglable in Settings → Notifications:

• App icon badge — shows the total unread count on the PWA or browser app icon (uses the Web Badging API; supported on Chrome/Edge and most mobile browsers).
• Favicon badge — overlays the unread count on the browser tab favicon so you can see it at a glance without switching tabs.

Web Push (OS-level notifications)

Push notifications deliver new-mail alerts even when you don't have MailFlow open. They work on desktop browsers and on mobile when MailFlow is installed as a PWA.

1. 1

   Generate VAPID keys (server admin)

   bash Copy

   npx web-push generate-vapid-keys

   Copy the output into VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT in .env, then restart.

2. 2

   Enable notifications in the browser

   In MailFlow, go to Settings → Notifications and click Enable Push Notifications. Your browser will ask for permission — click Allow.

3. 3

   Optional: Install as PWA

   For mobile or desktop, install MailFlow as a Progressive Web App. In Chrome/Edge click the install icon in the address bar; in Safari use Share → Add to Home Screen. The PWA receives push notifications like a native app even when not open.