Frequently Asked Question
Enable Email Notifications
Enabling e‑mail notifications in Proxmox VE 8 & 9
Proxmox sends all alerts (node‑down, backup‑fail, HA events, etc.) through its internal mailer. You should ALWAYS use the settings in the GUI under Datacenter → Options → Email notification).
Below are the three typical ways you might want to deliver those e‑mails:
| Delivery method | When you’d use it | What you have to configure |
|---|---|---|
| (a) Direct to an unauthenticated SMTP relay | Your organisation already runs an open relay on the internal network (e.g. mail.example.com:25). | Only the relay host (and optionally port/encryption) is required. |
| (b) Authenticated SMTP server | You need to send through a service that requires a username/password (e.g. Office 365, Gmail, a corporate Exchange server). | Host, port, encryption, user and password must be supplied. |
| (c) Direct delivery (local MTA) | You prefer Proxmox to hand the message to a locally‑installed MTA (Postfix, Exim, etc.) which then decides how to route it. | Install and configure a local MTA; tell Proxmox to use localhost without authentication. |
Troubleshooting tips
| Symptom | Likely cause | Fix |
|---|---|---|
| No mail arrives, no error in the web UI | Relay blocked by firewall | Open outbound port 25 (or 587) from the Proxmox host. |
| “Connection refused” | Wrong host/port or relay not listening | Verify the relay’s address with telnet relay.internal.example.com 25. |
| “5xx” response from relay | Relay expects authentication | Switch to method (b) below. |
Common pitfalls
| Issue | Reason | Remedy |
|---|---|---|
| “STARTTLS not available” | Server expects SSL on a different port | Use smtpencryption: ssl and the correct port (465 for Gmail). |
| “Connection timed out” | Outbound port blocked by firewall or ISP | Open port 587/465 on the host’s firewall and any upstream device. |
| Password stored in plain text | Security concern | Consider using a vault (e.g., HashiCorp Vault) and a small wrapper script that injects the password at runtime – beyond the scope of standard Proxmox, but possible. |
4. (c) Direct (local) delivery – using a local MTA
If you prefer Proxmox to hand the mail to a mail transfer agent running on the same host, you only need to point the Proxmox mailer at localhost. The local MTA then decides whether to forward, relay or deliver locally.
Step‑by‑step
- Install a lightweight MTA (Postfix is the default choice on Debian‑based Proxmox).
apt update
apt install postfix
During installation you’ll be asked for the “General type of mail configuration”. Choose ‘Internet Site’ unless you have a specific relay‑only setup.
- Configure Postfix (if you need it to forward to an external smarthost, edit
/etc/postfix/main.cf):
# Example: forward everything to an external relay with authentication
relayhost = [smtp.example.com]:587
smtp_use_tls = yes
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
Create /etc/postfix/sasl_passwd:
[smtp.example.com]:587 username:password
Then run:
postmap /etc/postfix/sasl_passwd
chmod 600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
systemctl restart postfix
- Tell Proxmox to use the local MTA
Add/ensure the following lines in /etc/pve/datacenter.cfg:
mailto: admin@example.com
smtpserver: 127.0.0.1
smtpport: 25
smtpencryption: none
(Do not set smtpuser or smtppassword – they are unnecessary for local delivery.)
- Test again with
pveum testmail.
You can also watch the Postfix log for the message:
tail -f /var/log/mail.log
When would you pick this method?
- You already run a corporate mail server on the same box (e.g., for notifications from other services).
- You need full control over DNS‑based routing, DKIM signing, etc., which the external service does not provide.
- You want to keep all e‑mail traffic inside your network and only let the local MTA talk to the outside world.
Quick checklist for a healthy local‑MTA setup
[root]alias present in/etc/aliases(runnewaliasesafter changes).- Firewall allows outbound SMTP (25/587/465) from the Proxmox host.
- Postfix
myhostnamematches the host’s FQDN, otherwise remote servers may reject the mail. - If you use a smarthost, verify that the credentials file (
sasl_passwd) has correct permissions (600).
5. Recap of the three configurations
| Mode | What you set in datacenter.cfg | Extra software required |
|---|---|---|
| a) Unauthenticated relay | smtpserver, smtpport (if not 25), smtpencryption (none/starttls) | None (uses built‑in mailer) |
| b) Authenticated SMTP | All of the above plus smtpuser & smtppassword | None (built‑in mailer) |
| c) Direct/local | smtpserver: 127.0.0.1 (port 25, no encryption) | Install & configure a local MTA (Postfix recommended) |
6. Final practical tips
- Keep the password secure – change file permissions after editing.
- Document the chosen method in your change‑management system; future upgrades (e.g., to Proxmox 10) will retain the file, but a fresh install may need it recreated.
- Regularly test – set a cron job that runs
pveum testmailonce a month and mails the result to you.
Example cron entry (run at 02:00 on the first of each month):
0 2 1 * * root /usr/sbin/pveum testmail >/dev/null 2>&1
- Check logs if something stops working after an upgrade:
journalctl -u pveproxy -u postfix -f
Look for lines containing “mail” or “smtp”.
Following the steps above will get e‑mail notifications working on both Proxmox 8 and Proxmox 9, regardless of whether you prefer a simple relay, an authenticated external server, or a full‑featured local MTA. If you run into any trouble, feel free to raise a support ticket – we’ll be happy to look at the log excerpts with you.
