If you run your own mail server — or even if you just forward mail through your Proxmox homelab before it hits Gmail or Office 365 — you've probably dealt with spam that slips past your provider's filters, or worse, a phishing attempt that almost fooled someone on your team. Most people patch this with whatever filtering their mail provider bundles in and hope for the best.
Proxmox actually ships a dedicated product for this exact problem, and a lot of Proxmox VE users don't even know it exists. It's called Proxmox Mail Gateway, or PMG, and it's a free, open-source spam and virus filter that sits in front of your real mail server and only lets clean mail through.
This guide walks through installing PMG as a virtual machine on a Proxmox VE host you already have running, then getting it to the point where it's actually filtering mail for a domain. By the end you'll have a working gateway, understand the two settings that make or break it, and know where to look when something isn't flowing the way you expect.
What You Will Learn
- What Proxmox Mail Gateway actually does, and how it's different from spam filtering your email provider already does
- Why you'd bother running your own mail filter instead of relying on Gmail or Microsoft's built-in filtering
- How to create a VM for PMG and run through the installer, including the settings that actually matter
- How to configure Relay Domains and Transports so mail actually flows through to your real mailbox server
- The commands you'll use to check that PMG's services are actually running
- Common errors people hit in their first week, and how to fix each one
What Is This Feature?
Proxmox Mail Gateway is a standalone product from the Proxmox team, built on the same Debian base as Proxmox VE and Proxmox Backup Server, but designed to do one job: sit between the internet and your real mail server, scan every message that passes through, and stop the bad ones before they reach an inbox.
Under the hood it's Postfix (the same mail transfer agent that runs on countless Linux servers) wired up with spam scoring and antivirus scanning, plus a proper web GUI on top so you're not editing Postfix config files by hand. When mail arrives, PMG checks it against spam rules, scans attachments for known malware signatures, and then either delivers it, rejects it outright, or drops it in quarantine for review — depending on how suspicious it looks.
It's not a mail server itself. PMG doesn't store mailboxes or let you check email through it. It's a filter that sits in the path, which is why it needs a "Transport" setting telling it where to actually forward the clean mail once it's done scanning — more on that in a bit.
Why Would You Use It?
If you already forward everything to Gmail or Microsoft 365, their filtering is genuinely decent, and I won't pretend PMG makes it dramatically better for a small personal domain. But there are a handful of situations where running your own gateway earns its keep.
You're running a self-hosted mail server. If you've set up something like Mailcow, Poste.io, or plain Postfix and Dovecot on your own hardware, you don't get any of the spam infrastructure a big provider builds behind the scenes. PMG fills that gap without you having to hand-configure SpamAssassin and ClamAV yourself.
You want the filtering decisions in your hands. Big providers occasionally mark legitimate mail as spam with zero explanation and no easy way to whitelist a sender for your whole organization. With PMG, the rules, thresholds, and quarantine are yours to adjust.
You're protecting an internal mail relay. Some homelabs and small businesses run an internal SMTP relay that everything routes through before hitting an external provider. Dropping PMG in front of that relay catches junk before it ever leaves your network, which matters more than people expect once you're relaying for more than one domain.
You want to actually learn how mail filtering works. Honestly, this is reason enough for a lot of homelab users. Watching real spam get scored and quarantined teaches you more about how mail security works than reading about it ever will.
Prerequisites
- A working Proxmox VE host (8.x or 9.x) with enough free resources to run another VM
- At least 2 GB of RAM and 8 GB of disk space for the PMG VM — 4 GB RAM and 32 GB disk is a more realistic starting point if you plan to actually use it
- A domain name you control, if you intend to filter real inbound mail rather than just testing internally
- An existing mail server (self-hosted or otherwise) that PMG can forward clean mail to — PMG filters mail, it doesn't store it
- Basic comfort with DNS records, since pointing your MX record at PMG is part of putting it into production
Step-by-Step Tutorial
Step 1: Download the PMG ISO
Grab the current Proxmox Mail Gateway ISO from the official downloads page at proxmox.com. As of writing, the current release is PMG 9.1, and it comes as a hybrid ISO — the same file works whether you mount it directly in a Proxmox VE VM or write it to a USB drive for bare metal. For a homelab, you'll almost always want the VM route rather than dedicating a physical machine to it.
Upload the ISO to your Proxmox VE host's local storage the same way you would for any other install image: Datacenter → your node → local storage → ISO Images → Upload.
Step 2: Create the VM
Click Create VM on your Proxmox VE host. On the General tab, give it a name like pmg or mailgateway — something that won't get confused with your actual mail server later. On the OS tab, select the PMG ISO you just uploaded and set the guest OS type to Linux.
For System, the defaults are fine. On Disks, give it at least 32 GB — PMG's own installer only needs 8 GB minimum, but quarantine storage and logs add up faster than you'd think once real traffic starts flowing. For CPU, 2 cores is plenty to start. For Memory, set 4096 MB; you can drop to 2048 MB if resources are tight, but spam scanning and antivirus definitions want the headroom.
On the Network tab, leave it on vmbr0 (or whichever bridge has real network access) unless you have a specific reason to isolate it. Since this VM is going to receive mail from the actual internet eventually, it needs a real network path, not an internal-only bridge.
Step 3: Run the installer
Boot the VM and you'll land in an installer that looks almost identical to the Proxmox VE installer, since it shares the same installation framework. Accept the EULA, then pick your target disk on the next screen — ext4 is the default and it's fine for a mail gateway workload.
Set your country, time zone, and keyboard layout. Getting the time zone right actually matters here more than it does on a regular VM, because mail headers and spam scoring both depend on accurate timestamps.
Next comes the password and email screen. Set a strong root password — this account has full control over mail flow for your domain, so don't reuse something weak. The email address field here isn't cosmetic either; it's where PMG sends its own administrative notifications, like disk space warnings.
The network configuration screen is the one to slow down on. Set a static IP address (DHCP works for testing, but a production mail gateway needs a fixed address, full stop). The hostname field wants a proper fully qualified domain name, like mail.yourdomain.com, not just pmg. This hostname shows up in mail headers and matters for how other mail servers perceive your gateway, so it's worth getting right the first time rather than renaming it later.
Confirm your settings and let the installer run. It takes about five to eight minutes on typical homelab hardware.
Step 4: Log in and reach the web GUI
After the reboot, the console shows the IP address and URL for the web interface. Open a browser and go to https://<your-pmg-ip>:8006 — the same port Proxmox VE uses, which makes sense since it's built on the same web framework.
You'll get a certificate warning. That's expected; PMG generates a self-signed certificate on install, just like PVE does, and browsers don't trust it by default. Click through the warning (in Chrome, "Advanced" then "Proceed") and log in with username root, realm Linux PAM, and the password you set during installation.
Step 5: Add your Relay Domains
This is the setting that determines what mail PMG will even accept. Go to Configuration → Mail Proxy → Relay Domains and add every domain you want PMG to handle mail for, like yourdomain.com.
Anything addressed to a domain not on this list gets rejected outright. That's a safety feature, not a bug — without it, PMG would accept mail for absolutely any domain and forward it wherever the Transport setting points, which is precisely how mail servers become open relays that spammers abuse to send junk through your IP.
Step 6: Configure a Transport
Relay Domains tells PMG what mail to accept. Transports tell it where that mail actually goes once it's been scanned and cleared. Go to Configuration → Mail Proxy → Transports and add one.
You'll specify the domain this transport applies to, the destination host (the IP or hostname of your real mail server — the one that actually stores mailboxes), the protocol (SMTP for most setups, LMTP if your backend supports it), and the port, which defaults to 25.
Skip this step and PMG will happily accept mail for your domain and then have nowhere to send it, which just means it piles up in the queue going nowhere.
Step 7: Point real mail traffic at PMG
Once you're ready to go live, update your domain's MX record to point at PMG's public IP instead of your mail server's IP directly. On your router or firewall, forward inbound TCP port 25 to the PMG VM, not to your actual mail server — PMG needs to be the first thing that sees inbound mail, or it can't filter anything.
If your outbound mail also needs to route through PMG (common if your ISP or hosting provider blocks direct outbound port 25 from your mail server), you can set a smarthost in PMG's configuration to relay outgoing mail through a provider that allows it.
Step 8: Send a test message
From an external mailbox — not one hosted on the same network, since some ISPs route local traffic oddly — send a test email to an address at your domain. Watch it come through, get scanned, and land in the real mailbox on your backend server. If it doesn't show up, the troubleshooting section below covers where to look first.
Commands Explained
Most day-to-day PMG administration happens through the GUI, but a handful of command-line checks are worth knowing when something's not behaving.
| Command | What it does |
|---|---|
pmgversion -v | Shows the installed PMG version and the versions of its component packages — useful when checking whether you're on a current release before opening a support thread. |
systemctl status postfix | Checks whether the Postfix mail transfer agent is running. If mail isn't moving at all, this is the first thing to check. |
systemctl status pmg-smtp-filter | Checks the PMG filtering daemon, which is what actually scores mail for spam and hands attachments off for virus scanning. |
systemctl status pmgproxy pmgdaemon pmgpolicy | Checks the remaining PMG services: the web proxy, the backend API daemon, and the policy engine that enforces your rules. |
tail -f /var/log/mail.log | Live-tails the mail log, showing every message as it's accepted, scored, and either delivered or rejected. This is where you'll spend most of your troubleshooting time. |
journalctl -u pmg-smtp-filter -n 50 | Shows the last 50 log entries specifically for the filtering service, handy when the GUI's task log doesn't show enough detail. |
Common Errors
Relay access denied
Postfix is rejecting a message because the destination domain isn't in your Relay Domains list, or you're trying to send mail through PMG to a domain it wasn't configured to accept. Double-check the domain spelling in Configuration → Mail Proxy → Relay Domains.
Connection timed out on port 25
Either your router isn't forwarding port 25 to the PMG VM, or your ISP is blocking it. A surprising number of residential ISPs and even some cloud VPS providers block outbound and inbound port 25 by default to cut down on spam abuse — if a test from an external mailbox never arrives and everything on the PMG side looks fine, this is worth ruling out with your provider directly.
Mail stuck in the queue, never delivered
This almost always traces back to a missing or misconfigured Transport. PMG accepted the mail because the domain matched a Relay Domain, but it has nowhere to actually send it. Check Configuration → Mail Proxy → Transports and confirm the destination host is reachable from the PMG VM.
Browser certificate warning on first login
Expected behavior, not a bug. PMG ships a self-signed certificate out of the box, same as a fresh Proxmox VE install. It's safe to proceed past the warning on your own network; for a public-facing gateway you'll eventually want to replace it with a certificate from a trusted CA.
Troubleshooting
- Start with the mail log, not the GUI.
tail -f /var/log/mail.logduring a test send shows you exactly where a message stopped — accepted, scored, quarantined, rejected, or bounced — faster than clicking through GUI panels. - Check that all five PMG services are actually running. A partial service failure (say, pmgpolicy crashed but postfix is fine) can produce confusing symptoms where mail arrives but filtering rules don't apply correctly.
- Verify DNS before blaming PMG. If external mail never arrives at all, confirm your MX record actually points at PMG's IP with a quick
dig MX yourdomain.comfrom an outside network. A stale MX record pointing at your old mail server is a common gotcha. - Watch the clock. If NTP drifted during setup, TLS handshakes with other mail servers can fail in ways that look like a networking problem but aren't. Confirm the VM's time is correct before digging further.
- Test locally before testing externally. Send a test message from a mail client on your own network first. If that fails too, you've ruled out ISP and firewall issues and can focus on PMG's own configuration.
Best Practices
- Never leave Relay Domains open or overly broad. List only the domains you're actually responsible for filtering — a misconfigured gateway that accepts mail for anything is exactly how servers end up blacklisted.
- Keep the PMG web interface off the public internet where you can. Restrict access to your management network or a VPN, the same way you'd treat the Proxmox VE GUI itself.
- Update regularly. Spam and virus signatures go stale fast, and PMG updates through the standard
aptworkflow, same as Proxmox VE. A gateway running months-old signatures isn't catching much. - Back up the PMG VM separately from your mail server. It's a distinct node with its own configuration and quarantine data, and losing it isn't the end of the world, but it's an annoying rebuild if you skip backups entirely.
- Don't crank spam scoring thresholds to maximum on day one. Start with the defaults, watch what lands in quarantine for a week or two, and tighten gradually. Aggressive settings out of the gate tend to catch legitimate mail along with the junk.
- Check quarantine regularly, at least at first. It's easy to forget it exists until someone asks why an expected email never showed up.
Frequently Asked Questions
Is Proxmox Mail Gateway actually free?
Yes. Like Proxmox VE, PMG is fully usable without a subscription. Paid subscriptions exist for enterprise support and access to a more conservative update repository, but nothing about core filtering functionality is locked behind one.
Can I install PMG in an LXC container instead of a VM?
No. PMG needs its own kernel and behaves like a full operating system installation, the same as Proxmox VE and Proxmox Backup Server. It has to run as a VM.
Does PMG replace my existing mail server?
No, and it's not trying to. PMG filters mail and forwards the clean messages to whatever server you point it at through the Transport setting. Your actual mailboxes, users, and storage still live on your existing mail server.
Do I need a public IP address to use PMG?
Only if you're filtering mail for a domain that receives from the public internet. If you're just testing internally or filtering mail on a private relay, PMG works fine without any public exposure.
Can I run more than one PMG node for redundancy?
Yes, PMG supports multi-node clustering similar to Proxmox VE, which is worth considering once you're filtering mail for a domain you actually depend on and can't afford downtime on.
Conclusion
Getting PMG running takes maybe twenty minutes of actual clicking once the VM boots, but understanding Relay Domains and Transports is what actually determines whether it works or just sits there rejecting everything. Get those two settings right and the rest — spam scoring, quarantine, virus scanning — mostly takes care of itself with the defaults.
If you've been meaning to get real visibility into what's actually hitting your domain's inbox, spinning up a PMG VM on hardware you already own is a low-risk way to find out.