A failed backup job is only useful information if you actually find out about it. By default, Proxmox tries to email the root user when something goes wrong, using whatever mail setup happens to exist on the host — which, on a fresh install, is usually nothing. Mail just quietly fails to send, and you find out about the problem the hard way, usually when you actually need that backup and it isn't there. Proxmox VE's notification system fixes this properly. It's a genuine SMTP-based setup, not a workaround, and once it's configured you'll get real emails in your real inbox when a backup fails, a disk fills up, or a cluster node drops offline.
What You Will Learn
- How Proxmox's notification system is structured, and why it's not just "add an email address somewhere"
- The difference between a notification target and a matcher
- How to set up an SMTP target using a real mail provider like Gmail or a self-hosted relay
- How to create a matcher so the right events actually reach that target
- How to test it and what to check if emails never arrive
What Is This Feature?
Proxmox's notification system is built around two separate pieces that work together: targets and matchers. A target is a destination — somewhere a notification can actually be sent. The most common target type is SMTP, meaning Proxmox connects directly to a mail server and sends the email itself, without depending on the host's own local mail setup. There are other target types too, like Gotify (a self-hosted push notification service) and webhooks, but SMTP is what most people reach for first since it just lands in a normal inbox. A matcher is the routing logic. It decides which events get sent to which targets, based on rules like severity level, the specific system that generated the event, or even a time window (so you're not getting paged at 3 AM for something that can wait until morning). Without a matcher pointed at it, a target you've configured will just sit there unused — nothing gets routed to it automatically. This two-piece design is a deliberate change from older Proxmox versions, which relied on the host's local mail transfer agent and a single flat list of email addresses. It's more setup up front, but it means you can route backup failures to one address, security-relevant events to another, and silence anything you don't care about — all without touching the underlying mail server config.
Why Would You Use It?
The honest answer: because the alternative is finding out about problems by noticing them yourself, days later. A backup job failing silently for a week is a genuinely common way people lose data they assumed was safe. Beyond backups, Proxmox fires notifications for things like replication failures, storage running low, and — if you're running a cluster — node or quorum issues. None of these are things you want to discover by opening the web interface and happening to notice a red icon. If you're running a single homelab server with nothing critical on it, you might reasonably decide this isn't worth setting up. But the moment you're storing anything you'd actually be upset to lose — family photos, a self-hosted service other people depend on, backups of other machines — five minutes of setup here is cheap insurance. There's also a cluster angle worth mentioning even for people who aren't clustered yet. If you ever do add a second node down the line, notifications become the way you find out about quorum problems and replication failures between nodes — issues that don't show up as an obvious red icon somewhere you'd stumble across it, but that absolutely affect whether your VMs stay running.
Prerequisites
- A running Proxmox VE install, 8.1 or later (this notification system replaced the older one starting in 8.1)
- Access to an SMTP mail provider — this can be a real account like Gmail or Outlook, or a self-hosted relay like Postfix if you're already running one
- If using Gmail specifically, an app password rather than your normal account password, since Google blocks plain password authentication for this kind of use
- Root or admin access to the Proxmox web interface
Step-by-Step Tutorial
Step 1: Open the Notifications panel
In the web interface, click Datacenter in the left tree, then Notifications. You'll see two tabs: Targets and Matchers. Start with Targets.
Step 2: Create an SMTP target
Click Add → SMTP and fill in:
- Name — a short identifier for this target, like
gmail-alerts - Server — your provider's SMTP hostname, for example
smtp.gmail.com - Port — typically 587 for STARTTLS, which is what most providers expect
- Username / Password — your mail account credentials, or an app password if required
- From Address — the address Proxmox will send as; some mail relays reject messages where this doesn't match the authenticated account
- Mailto — the address (or addresses) you actually want to receive these notifications
Click Create. This saves the target but doesn't route anything to it yet — that's what matchers are for.
Step 3: Send a test notification
Select your new target in the list and click Test. Proxmox sends a sample notification through it immediately. If it doesn't arrive within a minute or two, stop here and fix the connection before moving on — there's no point building routing rules for a target that doesn't actually work yet. Check the Troubleshooting section below for the usual culprits.
Step 4: Create a matcher
Switch to the Matchers tab and click Add. Give it a name, then configure:
- Target — the SMTP target you just created and tested
- Match Severity — restrict this matcher to specific severity levels, like only
warninganderror, if you don't want routine informational events cluttering your inbox - Match Calendar — optionally restrict when this matcher is active, using the same time syntax as scheduled backup jobs
Leave the matching rules empty if you want everything routed to this target with no filtering — a matcher with no rules always matches, which is a reasonable starting point while you're getting the system set up.
Step 5: Trigger a real event to confirm
The cleanest real-world test is a backup job. Run a manual backup of any VM (Backup tab → Backup Now) and, if you want to confirm failure notifications specifically work too, deliberately point it at a storage location that doesn't exist and watch for the failure email to arrive.
Commands Explained
This feature is almost entirely GUI-driven, but the configuration lives in plain text files if you ever need to inspect or script it:
/etc/pve/notifications.cfg— stores target and matcher definitions, excluding anything sensitive./etc/pve/priv/notifications.cfg— stores sensitive fields separately, like SMTP passwords and auth tokens, kept out of the main config for permission reasons.pvesh get /cluster/notifications/targets— lists configured notification targets from the command line, useful for confirming a target saved correctly without opening the GUI.pvesh create /cluster/notifications/targets/<name>/test— triggers a test notification for a specific target from the shell, the CLI equivalent of the Test button.
Common Errors
| Error / symptom | What's happening |
|---|---|
| Test notification never arrives, no error shown | Usually a spam filter on the receiving end, or an authentication failure that the SMTP server accepted quietly before dropping the message. Check spam first. |
| 535 Authentication failed | Wrong username/password, or — with Gmail specifically — using your normal account password instead of a generated app password. |
| Connection timed out on port 587 | A firewall between Proxmox and the mail server is blocking outbound traffic on that port. Common on hosts with restrictive outbound rules or certain VPS providers. |
| Notification saved but real events never trigger it | A target with no matcher pointing at it never receives anything automatically. Double-check the Matchers tab, not just Targets. |
Troubleshooting
If the test button itself fails, check the exact error Proxmox shows — it usually names the actual SMTP response, which is more useful than guessing. A 535 error means credentials; a timeout means network/firewall; a 550 relaying-denied error usually means the From address doesn't match what your provider allows for that account. If the test succeeds but real backup failure emails never show up, confirm your matcher's severity filter actually includes the level a backup failure generates — if you set it to match only "error" and a particular failure only generates a "warning," it'll be silently filtered out exactly as configured. Gmail specifically requires 2-factor authentication enabled on the account before it'll let you generate an app password at all. If you don't see the app password option in your Google account settings, that's almost always why. For self-hosted mail relays, make sure the relay itself is actually configured to accept connections from your Proxmox host's IP — a Postfix relay set to only accept local connections will reject Proxmox's SMTP attempts even with correct credentials. One more thing that catches people out: when a matcher has multiple match rules, there's a mode setting controlling whether it requires all of them to match or just any one of them. If you've stacked a severity rule and a calendar rule expecting either one to trigger the matcher on its own, but left mode set to "all," neither will fire unless both conditions are true at the same time. There's also an invert-match option that flips a rule's result entirely — worth checking if a matcher seems to be firing on exactly the events you excluded.
Best Practices
- Test the target immediately after creating it, before building matchers around it. Confirming the pipe works first saves time debugging the wrong layer later.
- Use a dedicated mailbox or app password for Proxmox notifications rather than your primary personal account credentials.
- Start with one broad matcher covering everything, then narrow it down once you've seen what kind of notification volume you're actually dealing with — it's easier to filter down than to guess filters up front.
- If you manage more than one Proxmox host, use distinct From addresses or subject conventions per host so you can tell at a glance which server an alert came from.
- Don't rely on notifications as your only monitoring. They tell you something already went wrong — they're not a substitute for actually checking in on the system periodically.
Frequently Asked Questions
Do I have to use SMTP, or are there other notification options?
SMTP is the most common choice, but Proxmox also supports Gotify for self-hosted push notifications and generic webhooks for integrating with tools like Slack or Discord through a bridge service.
Can I route different types of events to different email addresses?
Yes — that's exactly what matchers are for. Create multiple targets and matchers, each with its own filtering rules, to split events however makes sense for you.
Will this replace the old root email notification behavior?
Yes, on current Proxmox VE versions this system is what actually handles notifications now. The old approach of relying on a local MTA and the root user's mail is effectively superseded by targets and matchers.
Do I need a paid email account to make this work?
No, a free Gmail or Outlook account works fine for SMTP notifications, as long as you generate an app password where the provider requires one.
Does every Proxmox event go through this system?
Most system-generated events do — backups, replication, storage warnings, cluster health — but not every possible log message. It's built for actionable alerts, not a full log stream.
Conclusion
Setting up notifications properly is one of those tasks that feels like busywork right up until the first time a backup silently fails and you get an email about it instead of finding out three weeks later when you actually needed the file. Targets and matchers take a little longer to wrap your head around than a single email field would, but the flexibility is worth the extra five minutes. If you've been putting this off since your last install, it's a good one to knock out today — before you actually need it to have been working.