SMSTunnel for Proxmox VE and Backup Server

Failed backups and other alerts, by text from your own phone

Built into Proxmox VE 8.3+ and PBS 3.3+ · no plugin
Webhook notification target
Proxmox notification docs

A text when a backup fails

When a backup job fails, a replication breaks or a datastore check goes wrong, Proxmox hands the notification to your SMSTunnel account and your own Android phone texts it to you from your own number. A matcher decides which notifications deserve a text, so successful nightly jobs stay quiet.

1. Get your key

  1. 1. Install the SMSTunnel app from Google Play on your Android phone and sign in.
  2. 2. In your dashboard, open Apps → Add an app, pick Script or server, name it (for example "Proxmox") and click Create the key.
  3. 3. Copy the key right away: it's shown only once. You can stop or delete the app there anytime, and Proxmox can't send texts anymore.

Get the steps with your key in them

It opens Add an app with Script or server picked. Once the key is made, the dashboard shows every step and command with the key already filled in, ready to copy.

2. Add a Webhook target

In Proxmox VE, open Datacenter → Notifications; in Proxmox Backup Server, Configuration → Notifications. Under Notification Targets, click Add → Webhook and fill in:

Endpoint Name
smstunnel
Method/URL
POST https://smstunnel.io/api/v1/sms/send
Headers
Content-Type = application/json (Add Header)
Headers
X-API-Key = {{ secrets.apikey }}
Secrets
apikey = your key (Add Secret; it stays masked)
Body
the line below
Body (Proxmox VE): your number, in international format
{"to": "+14155550123", "message": "{{ escape title }}"}
Body (Proxmox Backup Server, whose titles don't name the host)
{"to": "+14155550123", "message": "PBS {{ fields.hostname }}: {{ escape title }}"}
  • Keep the Content-Type header: Proxmox doesn't send one of its own.
  • {{ escape title }} puts the notification's title in the text, escaped for JSON. Leave {{ message }} out: for a backup job it holds the whole task log, far longer than the 1600 characters a text can have.
  • Save, select the target and click Test: your phone texts "Test notification".

3. Text only what matters

  1. 1. Notification Matchers → Add: name it (for example "sms-errors"), and in Match Rules add Match Severity with Error (and Warning, if you want those too).
  2. 2. In Targets to notify, tick smstunnel. Leave the built-in default-matcher alone: it sends everything.
  3. 3. Make sure backup jobs use the notification system: in Proxmox VE 9, the job's Notifications tab, Use global notification settings; in Proxmox VE 8, Notification mode: Notification system; in PBS, each datastore's Options → Notifications. A job left on the old e-mail mode skips the webhook.

What the texts look like

vzdump backup status (pve1.example.com): backup failed
Replication Job: '101-0' failed
Test notification

Worth knowing

  • One text per backup run, not one per VM. Proxmox waits 10 seconds for an answer and doesn't retry; a failed call shows in the system log as "could not notify via target".
  • Several people? One Webhook target per number, all ticked in the matcher. SMSTunnel sends one text to one number per request.
  • Disk (SMART) warnings come with severity Unknown. Add it to the matcher only if you want those texts.
  • Phone offline? The text waits and goes out as soon as the phone is back.

If it doesn't work

  • Test works but a backup sends nothing: the job is still on the old e-mail notification mode, or the matcher doesn't match its severity (failed backups are Error).
  • 401 "Invalid or expired API key": the key is wrong or was deleted. "API key is required. Use X-API-Key header.": the key isn't in an X-API-Key header. SMSTunnel reads the key only from that header: Bearer or Basic authentication won't work.
  • 403 with PERMISSION_REQUIRED: the key may not send texts. Make a new one under Apps → Add an app.
  • 400 "property … should not exist": the body has a field SMSTunnel doesn't know. Send only to and message (and, if you need them, deviceId and defaultCountryCode). "message must be shorter than or equal to 1600 characters": shorten the text. "Phone number must contain…": put the number in international format, like +14155550123.
  • 400 with "to must be a string" and "message must be a string": the body didn't arrive as JSON. Add the header Content-Type: application/json.
  • 404 "Cannot GET /api/v1/sms/send": the tool sent a GET. Choose POST.
  • 429: too many texts at once. SMSTunnel takes 30 send requests a minute. Wait a minute and try again.
  • No text, but no error? If your phone is offline, the text waits and goes out as soon as the phone is back online. Open the SMSTunnel app on the phone to check it's linked.

Build it with an AI assistant

Copy this prompt into Claude, ChatGPT, Cursor or Copilot and replace the part in [brackets]. Don't paste your API key into the chat: the prompt doesn't need it. 

Help me get Proxmox VE or Proxmox Backup Server notifications (failed backups, replication, updates) as text messages from my own phone, with SMSTunnel.

About SMSTunnel (https://smstunnel.io): my own apps and tools hand text messages (SMS) to my SMSTunnel account, and my own Android phone sends them from my own number, on my own SIM and plan. The phone runs the SMSTunnel app from Google Play (https://play.google.com/store/apps/details?id=io.smstunnel.app), signed in to my account.

What I want: [describe what should send a text, to whom, and when]

How it works:
- No plugin: the Webhook notification target (Proxmox VE 8.3+, Proxmox Backup Server 3.3+). PVE: Datacenter → Notifications → Notification Targets → Add → Webhook. PBS: Configuration → Notifications, same dialog.
- Endpoint Name: smstunnel. Method/URL: POST https://smstunnel.io/api/v1/sms/send. Headers: Content-Type = application/json and X-API-Key = {{ secrets.apikey }}. Secrets: apikey = <my key>. Body: {"to": "+14155550123", "message": "{{ escape title }}"} (PBS: {"to": "+14155550123", "message": "PBS {{ fields.hostname }}: {{ escape title }}"}).
- Proxmox adds no Content-Type of its own. {{ escape title }} escapes the title for JSON; a bare {{ title }} is pasted raw. Use the title only: {{ message }} holds the whole task log (backup jobs) and can be far longer than the 1600 characters a text allows.
- Notification Matchers → Add: Match Rules "Match Severity" = Error (and Warning if wanted), Targets to notify: smstunnel. Don't attach it to default-matcher, which sends everything.
- Backup jobs only use the notification system when set to: PVE 9 job → Notifications → "Use global notification settings"; PVE 8 "Notification mode" = "Notification system"; PBS datastore → Options → Notifications. A job with an email address in legacy mode skips targets and matchers.
- The Test button sends the title "Test notification". Proxmox waits 10 seconds and doesn't retry.
- One recipient per request: SMSTunnel sends one text to one number. For several people, one request (or one notification) per number. In Proxmox, one webhook target per number, all listed in the matcher.
- Answers: 200 {"success": true, "messageId": "…"}; 401 wrong or deleted key; 403 the key lacks a permission ("code": "PERMISSION_REQUIRED"); 400 a missing, unknown or too long field; 429 too many requests (30 sends a minute, with Retry-After): wait and retry; without Retry-After, the plan's limit for the day or month is reached. If my phone is offline the text waits and goes out when it is back, within 3 days.
- The API key comes from my SMSTunnel dashboard (https://dashboard.smstunnel.io): Apps → Add an app → Create the key. It is shown only once and can send texts and check whether they went out.

Rules for your answer:
- Do not ask for my SMSTunnel password or API key and do not put a real key in your answer; I will not paste it in this chat.
- Phone numbers must be in international format (+ and the country code).
- Help me test it with my own number first.
- Only send texts people expect from me. No unsolicited texts.
- Help me write matchers that text only errors (failed backups), not every successful job.

Responsible use

Built for alerts to yourself and your team, and texts people expect from you. One text goes to one number. Sending unsolicited messages from a consumer SIM generally breaches mobile carrier terms of service.

Proxmox is a trademark of Proxmox Server Solutions GmbH. SMSTunnel is a third-party integration and is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.

More texts from your own tools

Synology DSM
NAS alerts by text
Healthchecks.io
Missed cron job texts
Uptime Kuma
Down and up texts

No phone paired yet?

Install the Android app and sign in with your account, and you're ready in about a minute.

Get it on Google Play