Install & Setup Guide

Desktop Suite — Windows, Mac & Linux

One download gives you five native apps — MailFlow (email), CalendarFlow, NoteFlow, ContactFlow, and ChatFlow — with per-app taskbar/Dock icons, unread badges, desktop notifications, and one sign-in shared across all of them.

Step 1 — Download

One file per platform installs the whole suite:

Step 2 — Install

• Windows: run MailFlow-Suite-Setup-1.5.0-Windows.exe. It's a per-user install (no admin rights needed) — the apps land in %LOCALAPPDATA%\MailFlowSuite with Start-menu shortcuts under MailFlow Suite. The installer asks which app shortcuts to create — all five apps are always installed, because each app's switcher menu can launch its siblings. Optionally let it make MailFlow the default handler for mailto: links. First launch: Windows SmartScreen may show "Windows protected your PC" because the apps aren't code-signed. Click More info → Run anyway. This only happens once per app.
• Android: download MailFlow-Suite-1.5.0-Android.apk and open it (allow "install unknown apps" for your browser if asked — it is not from the Play Store). The app signs in against your MailFlow server account; notifications arrive natively once permission is granted on first launch.
• macOS: open the downloaded MailFlow-Suite-1.5.0-macOS.dmg and drag the apps (or the whole window's contents) into Applications. All five apps work side by side; the app-switcher menu in any of them launches (or focuses) its siblings.
• Linux: extract MailFlow-Suite-1.5.0-Linux-x86_64.tar.gz and run ./install.sh from the extracted folder. It's a per-user install (no root): the five apps land in ~/.local/share/mailflow-suite with menu entries and icons. You can also run the apps straight from the extracted folder. The app-switcher menu in any of them launches (or focuses) its siblings.

Step 3 — First run: pick a mode

The first time you open any suite app it asks how you'll use it:

• Hosted instance — enter your MailFlow server's URL (e.g. https://mail.yourcompany.com) and sign in once with your email address and mail password. Every suite app shares that sign-in: open CalendarFlow or ChatFlow next and you're already logged in.
• Direct mail server — the classic single-user mode: point the app at your IMAP/SMTP server (same settings any mail client uses — see the table below) and sign in with your existing mail account. Mail, calendar, contacts, and notes all work locally; no server required.

MailFlow authenticates directly against your IMAP server — there is no separate MailFlow account to create and your password never leaves your machine (it's stored encrypted locally).

Your first sign-in starts the initial sync — existing folders and message history are pulled in, then kept current with IMAP IDLE push. New mail shows a desktop notification and the MailFlow taskbar badge counts unread.

Step 4 — The five apps

• MailFlow — email: labels & filters, spam training, scheduled send, delegation.
• CalendarFlow — calendars with attendee invites & reminders; badge counts today's remaining events.
• NoteFlow — markdown notes with version history and sharing.
• ContactFlow — contacts with labels and grouping.
• ChatFlow — team chat; needs a hosted MailFlow instance (see the web edition below).
• The app-switcher menu in any app launches (or focuses) its sibling apps — that's why all five install together.

Where your data lives

The first holds the suite's apps and shared settings; the second holds your local database, attachments, and per-app logs. Updating on Windows = run the new installer — your data and sign-in are untouched (or just click Install when the in-app update banner appears). Updating on macOS = download the new DMG and drag over the old apps — data and sign-in are untouched. Updating on Linux = download the new tar.gz and re-run install.sh — data and sign-in are untouched. Uninstalling = Windows Settings → Apps → MailFlow Desktop Suite, on macOS drag the apps to the Trash, or on Linux remove ~/.local/share/mailflow-suite and the mailflow-suite-* menu entries (data folders remain until you delete them).

Web Edition — Self-Hosted Server

The full multi-user deployment: one Go binary and a web-based setup wizard. Point it at your MariaDB or use the built-in SQLite, connect your existing IMAP/SMTP server, paste your license key — done. Serves your team at https://mail.yourcompany.com.

Requirements

• Any Linux or macOS server (a small VM is plenty), or Docker if you prefer containerizing it yourself.
• Optional: MariaDB 10.x / MySQL 8 for larger teams — or choose the built-in SQLite database in the wizard (single file, zero admin; ideal for small teams).
• An IMAP/SMTP mail server (mailcow, Dovecot, Gmail, Exchange-with-IMAP, …).
• A reverse proxy with HTTPS (Caddy or nginx) — required for passkey login.
• A MailFlow license key — required: the web edition does not run unlicensed. Standard = 10 users, Business = 50, Enterprise = unlimited. Get one via the contact form.

Step 1 — Run the binary

The server is a single static binary. Run it from its own directory:

[Unit]
Description=MailFlow
After=network.target

[Service]
WorkingDirectory=/opt/mailflow
ExecStart=/opt/mailflow/mailflow-go
Restart=on-failure
User=mailflow

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now mailflow

Step 2 — The setup wizard

On first boot (no configuration present) MailFlow serves a setup wizard at http://your-server:5174/ instead of the app. It walks you through:

1. Database — MariaDB/MySQL host, port, name, credentials (with a live Test connection button; the database is created for you if it doesn't exist and your user has privileges) or the built-in SQLite engine.
2. Mail servers — IMAP and SMTP host/port/TLS, each testable live before you continue.
3. License — paste the key CTI sent you and verify what it unlocks (customer name, tier, user count). Required — the wizard does not finish without a valid key.
4. HTTPS & Install — optionally enable built-in Let's Encrypt HTTPS (see Step 3), review the summary, and install: MailFlow writes setup.json, runs the database migrations with a progress bar, and tells you when to restart the service.

After the restart the app is live: browse to it and sign in with your own email address and mail password — MailFlow validates credentials against your IMAP server. The first account to sign in automatically becomes the admin. Teammates simply sign in with their mailbox credentials; accounts are provisioned on first login (up to your tier's user limit).

All the wizard settings can still be provided (or overridden) the classic way via a .env file — see the environment reference below. The wizard's setup.json takes precedence over .env for the sections it defines.

Step 3 — HTTPS

Built-in (recommended): MailFlow embeds Caddy's TLS engine. Add one line to .env (or fill the HTTPS box in the wizard) and it obtains and renews Let's Encrypt certificates itself — no proxy, no certbot, no cron:

AUTO_TLS_DOMAINS=mail.example.com   # your DNS name, pointed at this server
# AUTO_TLS_EMAIL=you@example.com   # optional ACME contact
# DISABLE_HTTP=true                # optional: turn off the plain-HTTP port

MailFlow then serves https:// on port 443 directly (HTTP/2 included) and redirects port 80 to it. Your DNS record must point at the server and ports 80/443 must be reachable from the internet — validation happens over HTTP-01/TLS-ALPN-01, no DNS provider setup needed.

Own proxy instead? Fine — just don't set AUTO_TLS_DOMAINS. MailFlow stays plain HTTP on its port and you terminate TLS wherever you like:

mail.example.com {
    reverse_proxy 127.0.0.1:5174
}

nginx works too (proxy_pass to 127.0.0.1:5174; leave buffering on). HTTPS isn't optional in practice — browsers only allow passkey registration on secure origins.

Step 4 — First login & users

1. Browse to https://mail.example.com and sign in with your own email address and mail password — MailFlow validates credentials against your IMAP server.
2. The first account to sign in automatically becomes the admin (server settings, user list, backups).
3. There is no user-creation screen for everyone else: teammates simply sign in with their mailbox credentials and their account is provisioned on first login.
4. Each user can register a passkey from Settings → Passkeys and generate API keys from Settings → API Keys.

Environment reference (.env)

Every wizard setting has an environment-variable equivalent in .env (next to the binary, same directory you run it from) and a command-line flag (mailflow-go --port=8080 — run --help for the list). setup.json — written by the wizard — takes precedence over .env for the sections it defines; command-line flags override everything.

Updating & backups

• Updates: replace the binary, restart the service. Schema migrations run automatically on startup (idempotent — safe to restart on the same version).
• Backups: the admin panel (Settings → Admin) has built-in scheduled backups; your data is the MariaDB database (or the SQLite file) plus the ATTACHMENT_DIR folder.
• License: your tier lives in setup.json (written by the wizard) or LICENSE_KEY in .env. The admin panel (Settings → Admin → License) shows the current license and lets an admin apply a new key live — e.g. to upgrade tiers without reinstalling.
• Need a hand? CTI deploys, migrates and manages MailFlow for licensed customers — get in touch.