NtfyPwsh - A PowerShell Module to Send Ntfy Messages

📱 NtfyPwsh - A PowerShell Module to Send Ntfy Messages

🚀 Simplifying Push Notifications with NtfyPwsh: A PowerShell Module for Ntfy.sh

📖 Introduction

Ntfy is an amazing tool for push notifications. It’s simple, efficient, and can be self-hosted or used for free (as of this post) at https://ntfy.sh. As a lightweight pub-sub notification service, Ntfy allows you to send notifications to your phone or desktop from any script, application, or service.

To make interacting with Ntfy even easier for PowerShell users, I’ve developed a PowerShell module called NtfyPwsh that provides a simple interface for the Ntfy API.

🔗 Links

• NtfyPwsh on GitHub
• NtfyPwsh on PowerShell Gallery

📥 Installing NtfyPwsh

NtfyPwsh can be installed from the PowerShell Gallery with a simple command:

Install-Module -Name NtfyPwsh -Scope CurrentUser

⚙️ Requirements

Before you get started, make sure you have:

• 🔹 PowerShell 7 or higher
• 🔹 Access to the internet or your self-hosted Ntfy server
• 🔹 Windows or Linux (-Delay and -Email are not working under linux)

🛠️ Core Functions

NtfyPwsh offers two primary functions:

1. 📤 Send-NtfyMessage: For sending notifications
2. 🔘 Build-NtfyAction: For creating interactive action buttons in notifications

Let’s explore these functions and how they can be used.

🌐 Ntfy Server

When using NtfyPwsh, you can specify which Ntfy server to use:

• If you don’t specify a -URI parameter, NtfyPwsh will default to using https://ntfy.sh.
• If you’re using a self-hosted instance, simply include your server URL with the -URI parameter:

$ntfy = @{
    URI   = 'https://ntfy.yourdomain.com'  # Your self-hosted instance
    Topic = 'ntfypwsh'
    Title = 'Custom Server Notification'
    Body  = 'This message is sent to your private Ntfy server'
}
Send-NtfyMessage @ntfy

This flexibility allows you to use either the public Ntfy service or your own private instance without changing your code structure.

📨 Sending Basic Notifications

The simplest way to send a notification is with a topic, title, and body:

$ntfy = @{
    Topic = 'ntfypwsh'
    Body  = 'This is a test message'
    Title = 'Test Title'
}
Send-NtfyMessage @ntfy

This sends a notification to the public “ntfypwsh” on ntfy.sh. Anyone subscribed to this topic will receive the notification.

🔐 Adding Authentication

If you’re using a self-hosted Ntfy server or need to authenticate with the public server, NtfyPwsh supports two authentication methods (as of v0.4.0):

Note: As of v0.4.0, authentication uses -TokenCreds (API token via Get-Credential) or -Credential (username/password via Get-Credential). The -TokenPlainText parameter has been removed.

Ntfy supports both Basic (username/password) and Bearer (token) authentication. In PowerShell, you can use a PSCredential object for both methods:

• Username/Password (Basic Auth): Use your username and password with Get-Credential or create a PSCredential manually.
• API Token (Bearer or Basic): Use Get-Credential -UserName 'token' and enter your API token as the password, or create a PSCredential with username ‘token’ and the token as the password.

The module will use the correct Authorization header for you.

🔑 Using API Token (Bearer/Basic authentication)

# Prompt for API token (recommended for interactive use)
$Creds = Get-Credential -UserName 'token' -Message 'Enter API Token as password'
$ntfy = @{
    URI   = 'https://ntfy.mydomain.com'
    Topic = 'ntfypwsh'
    Body  = 'This is a test message'
    Title = 'Test Title'
    TokenCreds = $Creds
}
Send-NtfyMessage @ntfy

# Or create a PSCredential manually (for scripting)
$Token = ConvertTo-SecureString 'tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2' -AsPlainText -Force
$Creds = [PSCredential]::new('token', $Token)
$ntfy = @{
    URI   = 'https://ntfy.mydomain.com'
    Topic = 'ntfypwsh'
    Body  = 'This is a test message'
    Title = 'Test Title'
    TokenCreds = $Creds
}
Send-NtfyMessage @ntfy

🔑 Using Username/Password (Basic authentication)

# Prompt for username and password
$Creds = Get-Credential -UserName 'admin' -Message 'Enter user password'
$ntfy = @{
    URI   = 'https://ntfy.mydomain.com'
    Topic = 'ntfypwsh'
    Body  = 'This is a test message'
    Title = 'Test Title'
    Credential = $Creds
}
Send-NtfyMessage @ntfy

# Or create a PSCredential manually (for scripting)
$Password = ConvertTo-SecureString 'fakepassword' -AsPlainText -Force
$Creds = [PSCredential]::new('testuser', $Password)
$ntfy = @{
    URI   = 'https://ntfy.mydomain.com'
    Topic = 'ntfypwsh'
    Body  = 'This is a test message'
    Title = 'Test Title'
    Credential = $Creds
}
Send-NtfyMessage @ntfy

ℹ️ The module automatically generates the correct Authorization header for you, whether you use username/password or an API token.

🔘 Creating Interactive Notifications with Actions

One of the most powerful features of Ntfy is the ability to add interactive action buttons to notifications. NtfyPwsh makes this easy with the Build-NtfyAction function:

$ntfy = @{
    URI   = 'https://ntfy.sh'
    Topic = 'ntfypwsh'
    Body  = 'This is a test message with actions'
    Title = 'Test Notification'
    Action = @(
        (Build-NtfyAction -ActionView -Label 'View Dashboard' -URL 'https://dashboard.example.com')
        (Build-NtfyAction -ActionHttp -Label 'Acknowledge' -URL 'https://api.example.com/acknowledge' -Method POST -Body '{"status":"acknowledged"}')
    )
}
Send-NtfyMessage @ntfy

You can include up to three actions per notification. The supported action types are:

• 🌐 -ActionView: Opens a URL when clicked (requires -Label and -URL)
• 🔄 -ActionHttp: Makes an HTTP request when clicked (requires -Label and -URL, supports -Method, -Headers, -Body)
• 📱 -ActionBroadcast: Broadcasts an Android intent (for Android only, requires -Label, supports -Intent, -Extras)

Note: As of 0.4.0 the -Action parameter in Build-NtfyAction has been replaced with explicit switches: -ActionView, -ActionHttp, or -ActionBroadcast. Update your scripts accordingly.

Example: Broadcast Action

$action = Build-NtfyAction -ActionBroadcast -Label 'Take Screenshot' -Extras @{ cmd = 'screenshot' }
Send-NtfyMessage -Topic 'ntfypwsh' -Body 'Please take a screenshot.' -Action $action

📎 Sending Notifications with Attachments

Need to include an image or file with your notification? NtfyPwsh supports attachments:

$ntfy = @{
    URI            = 'https://ntfy.sh'
    Topic          = 'ntfypwsh'
    Body           = 'Check out this screenshot'
    Title          = 'System Alert'
    AttachmentPath = 'C:/path/to/screenshot.png'
    AttachmentName = 'screenshot.png'
}
Send-NtfyMessage @ntfy

💼 Real-World Use Cases

🖥️ System Monitoring

# Check disk space and send alert if below threshold
$diskC = Get-PSDrive C
if ($diskC.Free / $diskC.Used -lt 0.1) {
    $ntfy = @{
        Topic    = 'ntfypwsh'
        Title    = '⚠️ Low Disk Space Alert'
        Body     = "Drive C: has only $([Math]::Round($diskC.Free / 1GB, 2)) GB free"
        Priority = 'High'
        Tags     = 'warning'
    }
    Send-NtfyMessage @ntfy
}

🚀 Deployment Notifications

# Notify team when deployment completes
try {
    # Deployment code here
    $ntfy = @{
        Topic = 'ntfypwsh'
        Title = '✅ Production Deployment Successful'
        Body  = "v1.2.3 deployed to production at $(Get-Date)"
        Tags  = 'check'
        Action = Build-NtfyAction -ActionView -Label 'View Dashboard' -URL 'https://dashboard.example.com'
    }
    Send-NtfyMessage @ntfy
} catch {
    $ntfy = @{
        Topic    = 'ntfypwsh'
        Title    = '❌ Production Deployment Failed'
        Body     = "Error: $($_.Exception.Message)"
        Priority = 'High'
        Tags     = 'x'
    }
    Send-NtfyMessage @ntfy
}

📅 Schedule Notifications

# Schedule a meeting reminder with action to join
$ntfy = @{
    Topic  = 'ntfypwsh'
    Title  = '📅 Team Meeting'
    Body   = 'Weekly team meeting starts in 15 minutes'
    Delay  = '15m'
    Action = Build-NtfyAction -ActionView -Label 'Join Meeting' -URL 'https://meet.example.com/team'
}
Send-NtfyMessage @ntfy

📊 Notification Priority Levels

Ntfy supports different priority levels for your notifications, which NtfyPwsh makes easy to set:

Priority	Description	Use Case
Max	Urgent notification, highest importance	Critical system failures
High	Important notification	Security alerts
Default	Regular notification	Normal updates
Low	Low priority notification	Informational messages
Min	Minimal priority, least disruptive	Debug information

Example:

$ntfy = @{
    Topic    = 'ntfypwsh'
    Title    = '🔥 Server Outage'
    Body     = 'Production server is not responding'
    Priority = 'Max'
    Tags     = 'rotating_light'
}
Send-NtfyMessage @ntfy

🏷️ Using Tags in Notifications

Ntfy supports various emoji tags that you can add to your notifications. NtfyPwsh makes it easy to include these tags:

$ntfy = @{
    Topic = 'ntfypwsh'
    Title = 'System Update'
    Body  = 'System update completed successfully'
    Tags  = 'arrow_up,partying_face'
}
Send-NtfyMessage @ntfy

For a complete list of supported tags, check the Ntfy documentation.

📖 More Examples: NtfyPwsh TMI Edition

Looking for even more detailed usage scenarios, advanced parameter combinations, and real-world scripts? Check out the companion post:

➡️ NtfyPwsh TMI Edition: Full Examples — A comprehensive guide with full examples and explanations for every parameter and advanced scenario in the NtfyPwsh module.

🔄 Conclusion

The NtfyPwsh PowerShell module simplifies the process of integrating push notifications into your PowerShell scripts. Whether you’re monitoring systems, automating workflows, or just need a simple way to send yourself reminders, NtfyPwsh combined with the Ntfy service provides a powerful notification solution.

Give it a try and let me know what you think! Contributions and feedback are always welcome on the GitHub repository.

📚 Resources

• 📂 NtfyPwsh GitHub Repository
• 📦 NtfyPwsh on PowerShell Gallery
• 📘 Ntfy Documentation

---

Licensed under the MIT License. Created by ptmorris1.