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. Type your email address and MailFlow picks the provider, or choose Outlook.com, Microsoft 365, Gmail, Yahoo, iCloud or Other (IMAP). 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. Microsoft and Google sign-in are configured by an admin under Settings → Email providers. 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.

Values saved under Settings → Email providers take precedence over the MS_* and GOOGLE_* settings, field by field, and an empty value counts as not set. On Docker these settings reach MailFlow only with the compose file from MailFlow 4.1 or later. If your docker-compose.yml has no MS_CLIENT_ID line, download it again (see Updates).

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, email providers, 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 authorize 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

Updating the compose file

docker compose pull updates the images but not your compose file. For MailFlow 4.1, download the compose file again: it now passes the GOOGLE_* and MS_* settings in your .env to the backend, and gives the backend 30 seconds to stop, so a send in progress can finish during an update. If you changed your compose file, copy the new backend lines into it instead. When you build from source, git pull updates it for you.

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

MailFlow 4.1 adds one database migration (0071) with the tables for scheduled messages. It runs automatically when the backend starts, and your existing data is unchanged. MailFlow 4.2 adds one more (0073) that renumbers the account order in the sidebar, keeping the order you see, so moving an account up or down sticks.

Going back to 4.0.x

docker compose exec postgres psql -U mailflow -d mailflow -c "DROP TABLE scheduled_message_attachments, scheduled_messages; DELETE FROM schema_migrations WHERE version = '0071_scheduled_messages';"

Use your DB_USER and DB_NAME if you changed them. Updating to 4.1 again recreates the tables.

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

Diagnostics

MailFlow can generate a sanitized report you can share when asking for help, from Settings → Diagnostics.

• Includes app versions, your environment, per-account and folder counts, sync error categories, and server health. Account IDs and custom folder names are replaced by one-time hashes.
• Excludes email addresses, names, subjects, message content, passwords, and API keys or tokens.

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, registration, and two-factor verification are limited to 10 attempts per 15 minutes per IP, adjustable under Settings → Security.
• 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 your provider

   Type your email address and MailFlow picks the provider, or choose one: Outlook.com, Hotmail, Live, MSN, Microsoft 365 (work or school), Gmail, Yahoo Mail, iCloud Mail, or Other (IMAP) to enter your IMAP and SMTP servers yourself.

3. 3

   Sign in or enter your password

   Microsoft accounts, and Gmail when your admin has set up Google sign-in, sign in on the provider’s own page. For the others, enter your username (usually your email address) and password (an App Password for Gmail, Yahoo and iCloud, see Email Providers). MailFlow checks that it can reach your mailbox before it reports the account as connected.

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.

5. 5

   If an account can't connect

   The account says why, with the fix next to it: for example, IMAP is turned off in Outlook.com (with the steps to turn it on), the sign-in has expired, or the server rejected the password. Select Try again once it is fixed, or Sign in again for Microsoft and Google accounts.

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 <j@example.com> 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.
• Send later: schedule the message for a time you choose instead of sending it now. See Send Later.

Send Later

Write a message now and have MailFlow send it at the time you choose. The message is stored encrypted on your MailFlow server and sent from there, so once it is scheduled you can close the browser or turn off your computer.

Scheduling a message

On a computer, open the menu on the arrow next to Send, or press Ctrl+Shift+Enter (⌘+Shift+Enter on a Mac). On a phone, tap the clock button next to Send. Then choose when it goes:

Times are in your device’s time zone, which the picker shows. Once the message is scheduled, the composer closes and a notice offers Undo for 10 seconds, which brings it back to the composer. A draft leaves Drafts once it is scheduled. Attachments and forwarded messages are saved with the message when you schedule it, so archiving or deleting the original does not affect the send.

The Scheduled view

While you have scheduled messages, Scheduled appears in the sidebar below Snoozed. It lists them from every account in four groups: Needs attention, Scheduled (soonest first), recently Sent, and Deleted messages you can still restore. Click a message to edit it, and hover it, right-click it or use the keyboard for the rest. On a phone, tap a message to edit it, and long-press it or use its More button for the other actions.

Sent at most once

MailFlow never sends a scheduled message twice on its own. If it cannot tell whether the mail server took the message, for example because the connection dropped in the middle of sending, it does not try again. The message shows Check delivery under Needs attention. Look in your Sent folder, then choose Send anyway (if it did go out, the recipients get it twice) or Mark as sent (MailFlow deletes its content and never sends it).

When the mail server asks MailFlow to try later, or cannot be reached, the message shows Retrying and MailFlow tries again after 1, 5 and 15 minutes, 1 hour and 3 hours, about four hours in all. If every attempt fails, it stops and tells you.

If MailFlow was offline

If your MailFlow server was down when a message was due, it sends the message once it is back, as long as it is at most 6 hours late, and marks it Sent late with the time it was due. Later than that, MailFlow pauses it and asks you, so a “see you in an hour” note never goes out the next day. Open it to send it now or pick a new time.

When a message needs you

A message that cannot go out on its own moves to Needs attention with the reason in words, and the sidebar shows how many are waiting for you. MailFlow also shows a notice in the app, and sends a push notification if you have turned them on.

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 customizable in Settings → Shortcuts. Use Ctrl+K (or ⌘+K on Mac) to open the command palette.

GTD Workflow

An optional Getting Things Done workflow, off by default and enabled per account under Settings → Categories → GTD. When on, a rail beside the message list groups threads into five states, each backed by a real IMAP folder, so the labels are ordinary server-side folders that sync to every mail client and survive MailFlow itself.

AI Assistant

Connect any OpenAI-compatible provider (a local model or a cloud API) under Settings → AI. MailFlow only sends mail to the provider you configure.

Snooze

Snooze a message to get it out of your inbox until you are ready. It disappears now and returns to the top of the inbox at the time you choose.

Spam Reporting

Mark messages as spam or not spam from the context menu, toolbar, or bulk actions. Reported mail moves to the spam folder; this feedback will feed automated filtering in a future release.

Inbox Categorization

Incoming mail is sorted into tabs at the top of the inbox (Primary, Newsletters, Promotions, Automated, and Social) using header detection and sender heuristics. Categorization is optional and can be turned off in settings.

Rules & Block List

Automate what happens to incoming mail. Rules run on delivery, and the block list runs first, before any rules.

Contacts & CardDAV

MailFlow builds a contact list from your mail and can expose it as a CardDAV address book, so your contacts sync to your phone and desktop address books.

Folder Sync

MailFlow keeps each account’s folder list in step with the server, so folders you create or rename in another mail client show up here on their own.

Command Palette

A fast, keyboard-first way to jump to any action or place in MailFlow.

API Tokens

Let scripts and tools, such as an MCP server, use your mail without your password. Create a token under Settings → Security → API tokens.

Mailbox Cleanup

Find bulk mail cluttering your inbox and clear it out, from Settings → Mailbox Cleanup. Choose whether to archive it (kept and searchable) or move it to Trash (recoverable until you empty it).

Plugins

Optional features you can turn on or off for your own account under Settings → Plugins. Enabling a plugin adds its own settings and interface; disabling it removes them again. Activation is per user, so one person enabling a plugin does not change it for anyone else on the server. The GTD workflow described above ships as a plugin.

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.