How to Set Up Email Notifications in Proxmox VE

Why Email Notifications Matter

A Proxmox server that fails silently is worse than one that fails loudly. Email notifications alert you when backups complete or fail, when storage runs low, when HA failovers occur, and when scheduled tasks encounter errors. Without notifications, you might not discover a broken backup job for weeks, and by then it is too late. Setting up email takes about ten minutes and can save you from serious data loss.

Configuring Postfix as a Relay

Proxmox VE includes Postfix, a mail transfer agent, out of the box. Rather than running a full mail server, the most reliable approach is to configure Postfix as a relay that forwards all outgoing mail through an established SMTP provider like Gmail, Outlook, or a dedicated transactional email service.

Install the required SASL authentication packages:

# Install SASL authentication support
apt update
apt install -y libsasl2-modules mailutils

Setting Up Gmail App Password

Google requires an app-specific password for third-party mail clients. To generate one, enable two-factor authentication on your Google account, then navigate to Security > App Passwords and create a new password for "Mail".

Store the credentials in a Postfix-compatible format:

# Create the SASL password file
echo "[smtp.gmail.com]:587 your-email@gmail.com:your-app-password" > /etc/postfix/sasl_passwd

# Secure the file and generate the hash database
chmod 600 /etc/postfix/sasl_passwd
postmap /etc/postfix/sasl_passwd

Configuring /etc/postfix/main.cf

Edit the Postfix main configuration file to set Gmail as the relay host and enable TLS encryption with SASL authentication:

# Add or modify these lines in /etc/postfix/main.cf
relayhost = [smtp.gmail.com]:587

# TLS settings
smtp_use_tls = yes
smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache

# SASL authentication
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd

# Rewrite sender address to match Gmail account
smtp_header_checks = regexp:/etc/postfix/header_checks

Gmail rejects messages that come from addresses it does not recognize as belonging to your account. Create a header rewrite rule to fix the sender address:

# Create the header check file
echo '/^From:.*/ REPLACE From: Proxmox Server <your-email@gmail.com>' > /etc/postfix/header_checks

# Reload Postfix to apply all changes
systemctl restart postfix

Testing the Configuration

Send a test email to verify everything works before relying on it for critical alerts:

# Send a test email
echo "This is a test email from Proxmox VE on $(hostname)" | mail -s "Proxmox Test Email" your-email@gmail.com

# Check the mail log for delivery status
tail -n 20 /var/log/mail.log

If the email does not arrive, check the mail log for errors. Common issues include incorrect app passwords, missing SASL modules, or firewall rules blocking outbound port 587:

# Debug common issues
# Check if Postfix is running
systemctl status postfix

# Verify SASL password database exists
ls -la /etc/postfix/sasl_passwd.db

# Check for TLS or authentication errors
grep -i "error\|warning\|fatal" /var/log/mail.log | tail -20

# Test SMTP connectivity
openssl s_client -starttls smtp -connect smtp.gmail.com:587 /dev/null | head -5

Configuring Proxmox Notification Targets

Starting with Proxmox VE 8.1, the notification system supports flexible routing with matchers and endpoints. Configure these through the web interface under Datacenter > Notifications, or edit the configuration files directly:

# View current notification configuration
cat /etc/pve/notifications.cfg

# The default target sends to root@pam's email
# Set the email for the root user
pveum user modify root@pam -email your-email@gmail.com

You can also configure notification targets via the command line for more control:

# Create a sendmail notification endpoint
pvesh create /cluster/notifications/endpoints/sendmail \
    --name admin-email \
    --mailto your-email@gmail.com \
    --from-address proxmox@yourdomain.com \
    --comment "Primary admin notifications"

# Create a matcher for backup notifications
pvesh create /cluster/notifications/matchers \
    --name backup-alerts \
    --match-severity warning,error \
    --target admin-email \
    --comment "Send backup failures to admin"

Backup Job Email Alerts

Configure backup jobs to send notifications on completion. When creating or editing a backup job, set the notification mode:

# Create a backup job with email notification on failure
pvesh create /cluster/backup \
    --vmid 100,101,200 \
    --storage backup-nas \
    --schedule "0 2 * * *" \
    --mode snapshot \
    --compress zstd \
    --notification-mode auto \
    --mailnotification failure

The mailnotification parameter accepts always (notify on both success and failure) or failure (notify only on errors). For production systems, always is recommended so you can confirm backups are running, not just catch failures.

Using Alternative SMTP Providers

If you prefer not to use Gmail, the same Postfix relay configuration works with any SMTP provider. Just change the relay host and credentials:

# For Microsoft 365 / Outlook
relayhost = [smtp.office365.com]:587

# For Mailgun
relayhost = [smtp.mailgun.org]:587

# For a self-hosted mail server
relayhost = [mail.yourdomain.com]:587

Email notifications are a critical layer of any well-managed Proxmox setup. Once configured, you get immediate visibility into backup results, HA events, and system issues. For real-time mobile alerts and quick server checks when you are away from your desk, ProxmoxR complements email notifications by putting your cluster status in your pocket.