Proxmox VE 8 Notification System: Endpoints, Matchers, and Configuration

The New Notification Framework in PVE 8

Proxmox VE 8 overhauled the notification system with a flexible framework that replaces the legacy email-only approach. The new system introduces two key concepts: endpoints (where notifications are sent) and matchers (rules that determine which notifications go where). This lets you route different types of alerts to different destinations — backups to email, critical errors to a push notification service, and informational messages to a logging endpoint.

Notification Endpoints

Proxmox VE 8 supports several endpoint types out of the box:

SMTP Endpoint

The most common endpoint for sending email notifications:

# Create an SMTP endpoint via pvesh:
pvesh create /cluster/notifications/endpoints/smtp \
    --name smtp-main \
    --server smtp.gmail.com \
    --port 587 \
    --mode starttls \
    --username your-email@gmail.com \
    --password "your-app-password" \
    --mailto admin@example.com \
    --from-address proxmox@example.com \
    --comment "Main email notifications"

# List existing SMTP endpoints:
pvesh get /cluster/notifications/endpoints/smtp

# Update an endpoint:
pvesh set /cluster/notifications/endpoints/smtp/smtp-main \
    --mailto admin@example.com,backup-team@example.com

# Delete an endpoint:
pvesh delete /cluster/notifications/endpoints/smtp/smtp-main

You can also configure SMTP endpoints from the web UI: Datacenter > Notifications > Add > SMTP.

Gotify Endpoint

Gotify is a self-hosted push notification server. Proxmox VE 8 has native Gotify support:

# Create a Gotify endpoint:
pvesh create /cluster/notifications/endpoints/gotify \
    --name gotify-alerts \
    --server http://gotify.homelab.local:8080 \
    --token "your-gotify-app-token" \
    --comment "Push notifications via Gotify"

# List Gotify endpoints:
pvesh get /cluster/notifications/endpoints/gotify

# Update the endpoint:
pvesh set /cluster/notifications/endpoints/gotify/gotify-alerts \
    --server https://gotify.homelab.local:443

Notification Matchers

Matchers control which notifications reach which endpoints. Without a matcher, an endpoint will not receive any notifications. Matchers filter by severity, notification type, and other criteria:

# Create a matcher that sends all notifications to the SMTP endpoint:
pvesh create /cluster/notifications/matchers \
    --name all-to-email \
    --target smtp-main \
    --comment "Send everything to email"

# Create a matcher for critical alerts only:
pvesh create /cluster/notifications/matchers \
    --name critical-to-gotify \
    --target gotify-alerts \
    --match-severity error \
    --comment "Only critical errors to push notifications"

# Create a matcher for backup notifications:
pvesh create /cluster/notifications/matchers \
    --name backups-to-email \
    --target smtp-main \
    --match-field type=vzdump \
    --comment "Backup notifications to email"

# List all matchers:
pvesh get /cluster/notifications/matchers

# Update a matcher:
pvesh set /cluster/notifications/matchers/critical-to-gotify \
    --match-severity error,warning

# Delete a matcher:
pvesh delete /cluster/notifications/matchers/all-to-email

Severity Filters

Proxmox uses these severity levels for notifications:

• info — Informational messages (backup completed successfully, replication finished)
• notice — Normal but significant events
• warning — Warning conditions that may need attention
• error — Error conditions (backup failed, HA failover occurred)

# Match multiple severity levels:
pvesh create /cluster/notifications/matchers \
    --name warnings-and-errors \
    --target smtp-main \
    --match-severity warning,error \
    --comment "Only warnings and errors to email"

# Match everything except info:
pvesh create /cluster/notifications/matchers \
    --name important-only \
    --target gotify-alerts \
    --match-severity notice,warning,error

Configuration Files

The notification configuration is stored in cluster-wide configuration files:

# View the notification config directly:
cat /etc/pve/notifications.cfg

# Example content:
# smtp: smtp-main
#     server smtp.gmail.com
#     port 587
#     mode starttls
#     username your-email@gmail.com
#     mailto admin@example.com
#     from-address proxmox@example.com

# gotify: gotify-alerts
#     server http://gotify.homelab.local:8080

# matcher: all-to-email
#     target smtp-main

# Private data (passwords, tokens) is stored separately:
cat /etc/pve/priv/notifications.cfg
# This file contains sensitive data and is only readable by root

Test Notifications

Always test your notification configuration after setup:

# Send a test notification via pvesh:
pvesh create /cluster/notifications/targets/smtp-main/test

# Test a Gotify endpoint:
pvesh create /cluster/notifications/targets/gotify-alerts/test

# If the test fails, check the logs:
journalctl -u pvedaemon --since "5 minutes ago" | grep -i notif

# Test from the web UI:
# Datacenter > Notifications > Select endpoint > Test button

Migration from Legacy Email

If you previously used the legacy email notification system (configured per-user in the web UI), Proxmox VE 8 automatically creates a default SMTP endpoint using your existing Postfix configuration. You can then add matchers to control routing:

# Check if a default endpoint was created:
pvesh get /cluster/notifications/endpoints/sendmail

# The default sendmail endpoint uses the local Postfix installation
# You can keep it and add additional endpoints for different channels

Practical Setup Example

Here is a complete notification setup that routes backup notices to email and failures to Gotify:

# 1. Create SMTP endpoint for email:
pvesh create /cluster/notifications/endpoints/smtp \
    --name email-main \
    --server smtp.example.com --port 587 --mode starttls \
    --username notify@example.com --password "password" \
    --mailto admin@example.com --from-address proxmox@example.com

# 2. Create Gotify endpoint for push alerts:
pvesh create /cluster/notifications/endpoints/gotify \
    --name push-alerts \
    --server http://gotify:8080 --token "app-token"

# 3. Route all backup notifications to email:
pvesh create /cluster/notifications/matchers \
    --name backup-email --target email-main --match-field type=vzdump

# 4. Route errors and warnings to Gotify:
pvesh create /cluster/notifications/matchers \
    --name errors-push --target push-alerts --match-severity error,warning

# 5. Test both endpoints:
pvesh create /cluster/notifications/targets/email-main/test
pvesh create /cluster/notifications/targets/push-alerts/test

Having a robust notification system is important, but sometimes you just need a quick glance at your infrastructure's health. ProxmoxR complements your notification setup by providing a mobile dashboard where you can instantly check node status, VM health, and resource usage — without waiting for a notification to tell you something is wrong.

Summary

The Proxmox VE 8 notification system provides flexible, multi-channel alerting through endpoints and matchers. Configure SMTP for email notifications, add Gotify for push alerts, and use matchers to route specific event types and severity levels to the right channels. Use pvesh commands for scripted configuration or the web UI for interactive setup, and always test your endpoints after configuration to ensure alerts are delivered reliably.