How to Enable Email Notifications in Proxmox VE for Backup and System Alerts

Introduction

Nothing ruins a Sunday morning quite like discovering your nightly backup job silently failed three days ago and nobody told you. Proxmox VE will happily let a backup fail, a disk fill up, or a cluster node drop out, and unless you're staring at the web UI when it happens, you'll never know. Email notifications fix that — Proxmox can email you the moment something goes wrong, without you needing to log in and check.

This guide covers setting up email notifications in Proxmox VE from scratch: configuring a mail server connection, wiring it up to actual events like backup jobs, and testing that mail actually arrives instead of vanishing into a spam folder.

What You Will Learn

• How Proxmox VE's notification system is structured (targets and matchers)
• Why email alerts matter more than most people think, until they don't have them
• How to configure an SMTP mail relay in the Proxmox web UI
• How to test and troubleshoot notifications that aren't arriving
• Which events are actually worth alerting on, and which ones just create noise

What Is This Feature?

Proxmox VE's notification system, found under Datacenter > Notifications, is built around two pieces: targets and matchers.

A target is the actual delivery mechanism — where the notification goes. Proxmox supports a few types, but the one most homelab users want is SMTP, which sends a regular email through a mail server (Gmail, your ISP's relay, a self-hosted mail server, whatever you have). There's also a Sendmail target, which uses the local sendmail binary on the Proxmox host instead of an external SMTP server, and a Webhook target for pushing alerts into things like Slack or Discord via a URL.

A matcher is the rule that decides which events actually get sent to a given target. Out of the box, Proxmox ships a default matcher that routes every notification to every configured target, but you can create more specific matchers — for example, only send backup-related alerts to your phone's email, while sending everything else to a general inbox.

This replaced the older, simpler setup in Proxmox VE 7 and earlier, where you just set an email address per user and that was it. The newer system is more flexible, though it does mean there's a bit more to configure the first time around.

Notifications also carry a severity level — info, notice, warning, or error — and matchers can filter on that too. A backup job that completes successfully fires an info-level event, while one that fails fires an error. This is useful once you've lived with the system for a while: you can route error-level events to your phone's email and let info-level ones just pile up in a general inbox you check occasionally, instead of treating every event the same way.

Why Would You Use It?

If you only run one thing on Proxmox, this might feel unnecessary. The moment you have a handful of VMs, a couple of scheduled backup jobs, and maybe a cluster with more than one node, it stops being optional.

A few situations where this actually saves you:

• Failed backup jobs. Backups fail more often than people expect — a full disk on the backup target, an expired snapshot, a VM that got renamed. Without an alert, you might not notice for weeks.
• Storage running low. Proxmox can warn you before a datastore fills up completely and starts causing write failures.
• Cluster quorum issues. If a node drops out of the cluster, you'll want to know immediately, not after your HA-managed VMs have already been affected.
• Update and package events. Some notification types can tell you when updates are available, which is handy if you don't log in to check every week.

I'll be honest — most homelab users only really care about backup failures and node health. You don't need to enable every single notification type. Turning on everything just trains you to ignore your inbox, which defeats the point.

Prerequisites

• A working Proxmox VE installation (this guide covers Proxmox VE 8.x, where the notification system described here lives).
• Access to an SMTP server you can actually send mail through — this could be a Gmail account with an app password, a provider like SendGrid or Mailgun, or an internal mail relay.
• Admin access to the Proxmox web UI (or root shell access if you prefer editing config by hand).
• A destination email address you actually check.

If you're planning to use Gmail as your SMTP relay, you'll need an app password rather than your normal account password — Google blocks plain password authentication for this kind of use. Two-factor authentication needs to be enabled on the account first before Google will let you generate one.

Step-by-Step Tutorial

Step 1: Open the Notifications panel

In the Proxmox web UI, click Datacenter in the left tree, then select Notifications. You'll see two tabs: Targets and Matchers. Start with Targets — you need somewhere for alerts to go before you can route anything to it.

Step 2: Add an SMTP target

1. Under the Targets tab, click Add and choose SMTP.
2. Give it a Name, something recognizable like gmail-alerts.
3. Fill in the Server field with your SMTP host — for Gmail this is smtp.gmail.com.
4. Set the Port — typically 587 for STARTTLS, or 465 for implicit TLS.
5. Enter the Username and Password (the app password, if using Gmail).
6. Fill in From Address — the address mail will appear to come from.
7. Add one or more recipient addresses — where the alerts actually get delivered.
8. Click Create.

Once saved, there's a Test button next to the target in the list. Use it now, before configuring anything else — if a test email doesn't arrive, there's no point building matchers on top of a broken target.

Step 3: Create a matcher

Matchers decide what actually gets routed to your new target. Proxmox includes a default "catch-all" matcher, but it's worth creating a specific one so you understand how they work:

1. Go to the Matchers tab and click Add.
2. Give it a name, like backup-failures.
3. Under Match Field, you can filter by things like notification type (for example, just backup-job events) or severity.
4. Under Target, select the SMTP target you created in Step 2.
5. Save it.

If you'd rather keep things simple and just get every notification, the default matcher already handles that — you can skip creating a custom one and just make sure the default matcher includes your new target.

Step 4: Test with a real backup job

The cleanest way to confirm everything works end-to-end is to run an actual backup and watch what happens. Go to a VM, click Backup, and run one manually. Within a minute or two of it finishing, you should get an email. If you want to test the failure path specifically, you can point a backup job at a storage target that's deliberately offline and confirm you get a failure alert rather than silence.

Commands Explained

pvesh is Proxmox's built-in API shell tool — it lets you query and modify almost anything in Proxmox from the terminal, using the same API the web UI itself talks to.

Common Errors

• "Could not send mail: Connection timed out" — usually means port 587 or 465 is blocked outbound, either by your router, your ISP, or a firewall on the Proxmox host itself.
• "535 5.7.8 Username and Password not accepted" — with Gmail specifically, this almost always means you're using your real account password instead of an app password.
• Test email succeeds but real alerts never arrive — check your matcher configuration. It's easy to create a target that works fine on its own but isn't actually attached to any matcher.
• Emails land in spam — common with a "From" address that doesn't match the sending domain's SPF/DKIM records. Less of an issue with Gmail as the relay, more common with a self-hosted mail server.

Troubleshooting

Start by isolating whether the problem is Proxmox or your mail provider. Use the Test button on the target itself — if that fails, the issue is almost certainly your SMTP credentials, port, or an outbound firewall rule, not anything Proxmox-specific.

If the test succeeds but real events don't trigger anything, check the Matchers tab again. A matcher with an overly narrow filter — say, one that only matches a specific severity level — will silently swallow events that don't fit its criteria. When in doubt, temporarily broaden a matcher to "match everything" and confirm mail starts flowing, then narrow it back down.

For connection-level issues, test the SMTP connection directly from the Proxmox shell:

openssl s_client -connect smtp.gmail.com:587 -starttls smtp

If this hangs or refuses to connect, the problem is network-level — check outbound firewall rules on the Proxmox host and anything upstream, like your router or ISP blocking port 587/465 (some residential ISPs do this to cut down on spam relays).

Also worth checking: the Proxmox host's own clock. TLS handshakes can fail in odd ways if the system time is significantly off, which occasionally happens on freshly installed nodes before NTP has synced.

Best Practices

• Use an app password or a dedicated transactional mail provider (Mailgun, SendGrid, Amazon SES) rather than your personal email password wherever possible.
• Create a matcher specifically for backup failures — that's the single most valuable alert for most homelab setups.
• Don't route every low-severity event to your phone. Alert fatigue is real, and you'll start ignoring notifications altogether if every minor event pings you.
• Test the failure path, not just the success path. A backup job that fails silently is exactly the scenario you're trying to catch — make sure a deliberately broken job actually triggers an alert.
• If you're running a cluster, configure notifications once at the datacenter level rather than per-node — the configuration is shared across the cluster automatically.
• Keep a second delivery method as a backup. If your only alerting path is email through a relay that itself goes down, you won't hear about it. A webhook to something like Discord alongside email costs almost nothing to set up and gives you a second path.

It's also worth revisiting your matchers every few months. Homelabs change — you add a VM, retire an old backup job, switch NAS devices — and a matcher built around last year's setup can quietly stop covering the thing you actually care about now.

Frequently Asked Questions

Can I send notifications to multiple email addresses?

Yes, an SMTP target accepts multiple recipient addresses, so you can send the same alert to more than one inbox.

Do I need a mail server running on the Proxmox host itself?

Not if you use an SMTP target — it connects out to whatever mail server you specify. The Sendmail target is the one that relies on local mail handling on the host.

Can I use this to alert on things other than backups?

Yes. Matchers can filter on cluster health, replication failures, storage status, and several other event types, not just backup jobs.

Why didn't my test email arrive within a few seconds?

A short delay is normal, especially with free providers like Gmail. If nothing shows up after a couple of minutes, check spam first, then move on to the troubleshooting steps above.

Does this work the same way on a single standalone node as it does in a cluster?

Yes — the notification system works identically whether you have one node or a full cluster, since the configuration lives in the shared /etc/pve filesystem either way.

Conclusion

Setting up email notifications takes maybe fifteen minutes, and it's the difference between finding out about a failed backup immediately versus discovering it three weeks later when you actually need that backup and it isn't there. Start small — one SMTP target, one matcher for backup failures — and expand from there once you know it's actually delivering mail reliably.