---
name: simple-nixos-mailserver
description: Simple NixOS Mailserver recipe for open-forge. Complete declarative mailserver solution using the Nix ecosystem. Postfix + Dovecot + Rspamd (spam) + ClamAV (virus) + DKIM + ACME TLS. NixOS only. Source: https://gitlab.com/simple-nixos-mailserver/nixos-mailserver
---

# Simple NixOS Mailserver (SNM)

Complete mailserver solution built for the Nix ecosystem. Declaratively configure Postfix (SMTP), Dovecot (IMAP/POP3), Rspamd (spam filtering + DKIM), ClamAV (virus scanning), ACME TLS certificates, and user accounts — all in a single NixOS module. Multiple domains, aliases, catch-all, Sieve scripts, ManageSieve, LDAP users, and SRS forwarding. GPL-3.0 licensed. **NixOS only.**

Upstream: <https://gitlab.com/simple-nixos-mailserver/nixos-mailserver> | Docs: <https://nixos-mailserver.readthedocs.io>

## Compatible combos

| Infra | Runtime | Notes |
|---|---|---|
| NixOS | NixOS module (flakes or tarball import) | The only supported runtime |

> **Not compatible with non-NixOS systems.** If you're not running NixOS, use a different mailserver solution (e.g. Mailcow, Mailu, stalwart-mail).

## Inputs to collect

| Phase | Prompt | Notes |
|---|---|---|
| preflight | NixOS server with stable public IPv4 (+ recommended IPv6) | |
| preflight | Reverse DNS (PTR record) configurable for your IP | Many hosters provide this in their control panel |
| preflight | Port 25/tcp open | Some hosters block this — request it if needed |
| preflight | Registered domain with DNS management | |
| config | `fqdn` | Mail server hostname, e.g. `mail.example.com` |
| config | `domains` | List of mail domains, e.g. `["example.com"]` |
| config | User accounts + hashed passwords | Hash with `nix-shell -p mkpasswd --run 'mkpasswd -s'` |
| config (optional) | TLS method | ACME (recommended) or custom certificates |

## Software-layer concerns

### Stack

| Service | Role |
|---|---|
| Postfix | SMTP (port 25 inbound, 465 TLS / 587 StartTLS outbound) |
| Dovecot | IMAP (993 TLS / 143 StartTLS), POP3 (995/110) |
| Rspamd | Spam filtering + DKIM signing/verification |
| ClamAV | Virus scanning |
| ACME | Automatic TLS certificate management |

### Versioning

Use the SNM branch matching your NixOS release:

| NixOS version | SNM branch |
|---|---|
| 25.11 | `nixos-25.11` |
| 25.05 | `nixos-25.05` |
| unstable | `main` |

## DNS records required

| Record | Value |
|---|---|
| `mail.example.com` A | Your server IPv4 |
| `mail.example.com` AAAA | Your server IPv6 (recommended) |
| Reverse PTR for IPv4 | → mail.example.com |
| MX for `example.com` | → mail.example.com |
| SPF TXT for `example.com` | `v=spf1 mx ~all` |
| DKIM TXT | Generated by SNM — find in `/var/dkim/<domain>/<selector>.txt` after first run |
| DMARC TXT | `v=DMARC1; p=none; rua=mailto:postmaster@example.com` |

## Install — NixOS module (tarball import)

In your NixOS configuration (`/etc/nixos/configuration.nix` or a module file):

```nix
{ config, ... }:
{
  imports = [
    (builtins.fetchTarball {
      url = "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/nixos-25.11/nixos-mailserver-nixos-25.11.tar.gz";
      # Get sha256 with:
      # nix-prefetch-url --unpack "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/nixos-25.11/nixos-mailserver-nixos-25.11.tar.gz"
      sha256 = "your-sha256-here";
    })
  ];

  security.acme.acceptTerms = true;
  networking.firewall.allowedTCPPorts = [ 80 ];
  services.nginx.virtualHosts.${config.mailserver.fqdn}.enableACME = true;

  mailserver = {
    enable = true;
    stateVersion = 4;
    fqdn = "mail.example.com";
    domains = [ "example.com" ];
    x509.useACMEHost = config.mailserver.fqdn;

    accounts = {
      "user@example.com" = {
        hashedPasswordFile = "/path/to/hashed-password-file";
        aliases = [ "postmaster@example.com" ];
      };
    };
  };
}
```

```bash
# After editing configuration:
nixos-rebuild switch
```

## Install — Flakes

See https://nixos-mailserver.readthedocs.io/en/latest/flakes.html for flake-based setup.

## Generating password hashes

```bash
nix-shell -p mkpasswd --run 'mkpasswd -s'
# Enter password at prompt → outputs hash to store in hashedPasswordFile
```

## Upgrade procedure

```bash
# Update the SNM tarball URL/sha256 or flake input to the new version
# Then:
nixos-rebuild switch
```

## Gotchas

- **NixOS only** — SNM is a NixOS module and cannot run on Debian, Ubuntu, or other distros.
- **Port 25 must be open** — many cloud/VPS providers block port 25 by default to prevent spam. Request it to be opened before setup.
- **Reverse DNS (PTR) is critical** — if the PTR record for your IP doesn't match `fqdn`, most receiving mail servers will reject or flag your emails.
- **DKIM keys are auto-generated** on first run — after `nixos-rebuild switch`, find the public DKIM key at `/var/dkim/<domain>/<selector>.txt` and add it as a TXT record in DNS.
- **Match SNM branch to NixOS version** — using the wrong branch will cause nixpkgs version mismatches and broken builds.
- Use `hashedPasswordFile` (referencing a file on disk) rather than inline `hashedPassword` for secrets management — keeps password hashes out of the Nix store.

## Links

- Source: https://gitlab.com/simple-nixos-mailserver/nixos-mailserver
- Documentation: https://nixos-mailserver.readthedocs.io
- Setup guide: https://nixos-mailserver.readthedocs.io/en/latest/setup-guide.html
- Flakes guide: https://nixos-mailserver.readthedocs.io/en/latest/flakes.html
- Matrix community: https://matrix.to/#/#nixos-mailserver:nixos.org
