# Shoutrrr A notification library for gophers and their furry friends.
Heavily inspired by caronc/apprise. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/nicholas-fedor/shoutrrr/badge)](https://scorecard.dev/viewer/?uri=github.com/nicholas-fedor/shoutrrr) [![codecov](https://codecov.io/gh/nicholas-fedor/shoutrrr/branch/main/graph/badge.svg)](https://codecov.io/gh/nicholas-fedor/shoutrrr) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/47eed72de79448e2a6e297d770355544)](https://www.codacy.com/gh/nicholas-fedor/shoutrrr/dashboard?utm_source=github.com&utm_medium=referral&utm_content=nicholas-fedor/shoutrrr&utm_campaign=Badge_Grade) [![report card](https://goreportcard.com/badge/github.com/nicholas-fedor/shoutrrr)](https://goreportcard.com/badge/github.com/nicholas-fedor/shoutrrr) [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/nicholas-fedor/shoutrrr) [![github code size in bytes](https://img.shields.io/github/languages/code-size/nicholas-fedor/shoutrrr.svg?style=flat-square)](https://github.com/nicholas-fedor/shoutrrr) [![license](https://img.shields.io/github/license/nicholas-fedor/shoutrrr.svg?style=flat-square)](https://github.com/nicholas-fedor/shoutrrr/blob/main/LICENSE) [![Pulls from DockerHub](https://img.shields.io/docker/pulls/nickfedor/shoutrrr.svg)](https://hub.docker.com/r/nickfedor/shoutrrr) [![godoc](https://godoc.org/github.com/nicholas-fedor/shoutrrr?status.svg)](https://godoc.org/github.com/nicholas-fedor/shoutrrr) [![All Contributors](https://img.shields.io/badge/all_contributors-20-orange.svg?style=flat-square)](#contributors-)
## Table of Contents - [Full Documentation](#full-documentation) - [Installation](#installation) - [From Source](#from-source) - [Binaries](#binaries) - [Container Images](#container-images) - [Go Package](#go-package) - [GitHub Action](#github-action) - [Usage](#usage) - [CLI](#cli) - [Go Package Usage](#go-package-usage) - [Docker](#docker) - [GitHub Action Usage](#github-action-usage) - [Use as a Package](#use-as-a-package) - [Option 1 - Using the direct send command](#option-1---using-the-direct-send-command) - [Option 2 - Using a sender](#option-2---using-a-sender) - [Single URL](#single-url) - [Multiple URLs](#multiple-urls) - [Use Through the CLI](#use-through-the-cli) - [Use as a GitHub Action](#use-as-a-github-action) - [Supported Services](#supported-services) - [Contributors ✨](#contributors-) - [Related Project(s)](#related-projects) ## Full Documentation Visit the project's [GitHub Page](https://shoutrrr.nickfedor.com) for full documentation. ## Installation ### From Source ```bash go install github.com/nicholas-fedor/shoutrrr/shoutrrr@latest ``` ### Binaries Install the latest release binary to `$HOME/go/bin` (ensure it's in your `PATH`). - **Windows (amd64):** ```powershell New-Item -ItemType Directory -Path $HOME\go\bin -Force | Out-Null; iwr (iwr https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | ConvertFrom-Json).assets.where({$_.name -like "*windows_amd64*.zip"}).browser_download_url -OutFile shoutrrr.zip; Add-Type -AssemblyName System.IO.Compression.FileSystem; ($z=[System.IO.Compression.ZipFile]::OpenRead("$PWD\shoutrrr.zip")).Entries | ? {$_.Name -eq 'shoutrrr.exe'} | % {[System.IO.Compression.ZipFileExtensions]::ExtractToFile($_, "$HOME\go\bin\$($_.Name)", $true)}; $z.Dispose(); rm shoutrrr.zip; if (Test-Path "$HOME\go\bin\shoutrrr.exe") { Write-Host "Successfully installed shoutrrr.exe to $HOME\go\bin" } else { Write-Host "Failed to install shoutrrr.exe" } ``` - **Linux (amd64):** ```bash mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*linux_amd64[^"]*\.tar\.gz') | tar -xz --strip-components=1 -C $HOME/go/bin shoutrrr ``` - **macOS (amd64):** ```bash mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*darwin_amd64[^"]*\.tar\.gz') | tar -xz --strip-components=1 -C $HOME/go/bin shoutrrr ``` > [!Note] > Visit the [releases page](https://github.com/nicholas-fedor/shoutrrr/releases) for other architectures (e.g., arm, arm64, i386, riscv64). ### Container Images - **[Docker Hub](https://hub.docker.com/r/nickfedor/shoutrrr):** ```bash docker pull nickfedor/shoutrrr:latest ``` - **[GHCR](https://github.com/users/nicholas-fedor/packages/container/package/shoutrrr):** ```bash docker pull ghcr.io/nicholas-fedor/shoutrrr:latest ``` > [!Note] > Tags: `latest` (stable), `vX.Y.Z` (specific version), `nightly` (development), platform-specific (e.g., `amd64-nightly`). ### Go Package ```bash go get github.com/nicholas-fedor/shoutrrr@latest ``` ### GitHub Action ```yaml - name: Shoutrrr uses: nicholas-fedor/shoutrrr-action@v1 with: url: ${{ secrets.SHOUTRRR_URL }} title: Deployed ${{ github.sha }} message: See changes at ${{ github.event.compare }}. ``` ## Usage ### CLI ```bash shoutrrr send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!" ``` ### Go Package Usage ```go import "github.com/nicholas-fedor/shoutrrr" errs := shoutrrr.Send("slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook", "Hello, Slack!") if len(errs) > 0 { // Handle errors } ``` ### Docker ```bash docker run --rm nickfedor/shoutrrr:latest send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!" ``` ### GitHub Action Usage See installation example [above](#github-action). ### Use as a Package #### Option 1 - Using the direct send command ```go url := "slack://token-a/token-b/token-c" err := shoutrrr.Send(url, "Hello world (or slack channel) !") ``` #### Option 2 - Using a sender ##### Single URL ```go url := "slack://token-a/token-b/token-c" sender, err := shoutrrr.CreateSender(url) sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ }) ``` ##### Multiple URLs ```go urls := []string { "slack://token-a/token-b/token-c" "discord://token@channel" } sender, err := shoutrrr.CreateSender(urls...) sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ }) ``` ### Use Through the CLI ```bash shoutrrr send [OPTIONS] ``` ### Use as a GitHub Action You can also use Shoutrrr in a GitHub Actions workflow. ```yaml name: Deploy on: push: branches: - main jobs: build: runs-on: ubuntu-latest steps: - [Your other workflow steps] - name: Shoutrrr uses: nicholas-fedor/shoutrrr-action@v0.0.11 with: url: ${{ secrets.SHOUTRRR_URL }} title: Deployed ${{ github.sha }} message: See changes at ${{ github.event.compare }}. ``` ## Supported Services | Service | Description | |--------------|--------------------------------------| | Bark | iOS push notifications | | Discord | Discord webhooks | | Generic | Custom HTTP webhooks | | Google Chat | Google Chat webhooks | | Gotify | Gotify push notifications | | IFTTT | IFTTT webhooks | | Join | Join push notifications | | Lark | Lark (Feishu) webhooks | | Logger | Local logging (for testing) | | Matrix | Matrix rooms | | Mattermost | Mattermost webhooks | | MQTT | MQTT message broker | | Notifiarr | Notifiarr message forwarding | | Ntfy | Ntfy push notifications | | Opsgenie | Opsgenie alerts | | PagerDuty | PagerDuty incident notifications | | Pushbullet | Pushbullet push notifications | | Pushover | Pushover push notifications | | Rocket.Chat | Rocket.Chat webhooks | | Slack | Slack webhooks or Bot API | | SMTP | Email notifications | | Teams | Microsoft Teams webhooks | | Telegram | Telegram bots | | Twilio | Twilio SMS notifications | | Zulip | Zulip chat | | XMPP | XMPP messages (if enabled) | ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Nicholas Fedor
Nicholas Fedor

πŸ’» πŸ“– 🚧 πŸ‘€
Amir Schnell
Amir Schnell

πŸ’»
nils mΓ₯sΓ©n
nils mΓ₯sΓ©n

πŸ’» πŸ“– 🚧
Luka Peschke
Luka Peschke

πŸ’» πŸ“–
MrLuje
MrLuje

πŸ’» πŸ“–
Simon Aronsson
Simon Aronsson

πŸ’» πŸ“– 🚧
Arne JΓΈrgensen
Arne JΓΈrgensen

πŸ“– πŸ’»
Alexei Tighineanu
Alexei Tighineanu

πŸ’»
Alexandru Bonini
Alexandru Bonini

πŸ’»
Senan Kelly
Senan Kelly

πŸ’»
JonasPf
JonasPf

πŸ’»
claycooper
claycooper

πŸ“–
Derzsi DΓ‘niel
Derzsi DΓ‘niel

πŸ’»
Joseph Kavanagh
Joseph Kavanagh

πŸ’» πŸ›
Justin Steven
Justin Steven

πŸ›
Carlos Savcic
Carlos Savcic

πŸ’» πŸ“–
PythonGermany
PythonGermany

πŸ’»
Noel O'Brien
Noel O'Brien

πŸ’» πŸ“–
Caleb Lemoine
Caleb Lemoine

πŸ’» πŸ“–
Eddie 'Sergeant' M
Eddie 'Sergeant' M

πŸ“–
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! ## Related Project(s) - [Watchtower](https://github.com/nicholas-fedor/watchtower) - Automate Docker container image updates. - [Shoutrrr GitHub Action](https://github.com/nicholas-fedor/shoutrrr-action) - Notifications using Shoutrrr in GitHub Actions. - [Bezel](https://github.com/henrygd/beszel) - A lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions. - [WatchYourLAN](https://github.com/aceberg/WatchYourLAN) - Lightweight network IP scanner with web GUI. - [DNSControl](https://github.com/StackExchange/dnscontrol)- Infrastructure as code for DNS. - [docker-volume-backup](https://github.com/offen/docker-volume-backup) - Backup Docker volumes locally or to any S3, WebDAV, Azure Blob Storage, Dropbox, Google Drive or SSH compatible storage. - [BirdNET-Go](https://github.com/tphakala/birdnet-go) - An AI solution for continuous avian monitoring and identification.