apprise

README

apprise-go

A Go port of Apprise - Push Notifications That Work with Everything

Features • Installation • Usage • Releases • Contributing

Latest parity report: GitHub Actions parity workflow

---

About

apprise-go is a Go port of Apprise by Chris Caron. It aims to provide the same powerful notification capabilities in a standalone, compiled binary with no runtime dependencies.

Note: This project is not affiliated with or endorsed by the upstream Apprise project.

Features

• Multi-Platform Support: Send notifications to 100+ services
• Standalone Binary: No Python runtime required
• Cross-Platform: Linux, macOS, and Windows builds
• CLI Interface: Easy command-line usage
• Storage Support: Persistent notification configurations
• Schema Details: Full service configuration information

Installation

Pre-built Binaries

Download the latest release for your platform from the Releases page.

macOS (ARM64)

# Download and extract (replace VERSION with the latest version)
curl -LO https://github.com/unraid/apprise-go/releases/download/vVERSION/apprise-go-darwin-arm64.zip
unzip apprise-go-darwin-arm64.zip
chmod +x apprise-go
sudo mv apprise-go /usr/local/bin/

Linux (AMD64)

# Download and extract (replace VERSION with the latest version)
curl -LO https://github.com/unraid/apprise-go/releases/download/vVERSION/apprise-go-linux-amd64
chmod +x apprise-go-linux-amd64
sudo mv apprise-go-linux-amd64 /usr/local/bin/apprise-go

Windows

Download the .exe file from the Releases page and add it to your PATH.

Build from Source

git clone https://github.com/unraid/apprise-go.git
cd apprise-go
go build -o apprise-go ./cmd/apprise

Usage

Library Usage

package main

import (
	"log"

	apprise "github.com/unraid/apprise-go"
)

func main() {
	client := apprise.New()
	if err := client.Add("discord://webhook_id/webhook_token"); err != nil {
		log.Fatal(err)
	}

	if err := client.Send(
		"Something happened!",
		apprise.WithTitle("Alert"),
		apprise.WithNotifyType(apprise.NotifyWarning),
	); err != nil {
		log.Fatal(err)
	}
}

For one-off sends, use apprise.Send(urls, body, options...).

Basic Notification

# Send a simple notification
apprise -b "Hello from apprise!" "discord://webhook_id/webhook_token"

Multiple Services

# Send to multiple services at once
apprise -b "Multi-platform notification" "discord://..." "slack://..."

With Title

# Add a title to your notification
apprise -t "Alert" -b "Something happened!" "discord://..."

Schema and Service Information

# Get full Apprise schema as JSON
apprise --schema

# Print details about all supported services
apprise --details

Storage Support

# Store and reuse configurations
apprise --storage-path /path/to/config -b "Using saved config"

Configuration Files

apprise-go supports Apprise-style TEXT and YAML configuration files. YAML tagged URLs should use the upstream mapping form where the URL has a trailing colon:

version: 1
groups:
  now: my_now_pers
urls:
  - tgram://token_id/chat_id/?format=markdown&mdv=v1:
      tag: my_now_pers

Do not put tag under a bare scalar URL; that is not valid YAML and will not be loaded as a tagged Apprise URL.

Releases

Latest Release

The latest stable release can always be found on the GitHub Releases page.

Release Assets

Each release includes:

• Pre-built binaries for multiple platforms:
  • apprise-go-darwin-amd64.zip - macOS Intel (signed & notarized)
  • apprise-go-darwin-arm64.zip - macOS Apple Silicon (signed & notarized)
  • apprise-go-linux-amd64 - Linux AMD64
  • apprise-go-linux-arm64 - Linux ARM64
  • apprise-go-linux-386 - Linux 32-bit
  • apprise-go-linux-armv7 - Linux ARMv7 (Raspberry Pi, etc.)
  • apprise-go-windows-amd64.exe - Windows AMD64
  • apprise-go-windows-arm64.exe - Windows ARM64
  • apprise-go-windows-386.exe - Windows 32-bit
  • apprise-go-freebsd-amd64 - FreeBSD AMD64
  • apprise-go-freebsd-arm64 - FreeBSD ARM64
• Source code (zip and tar.gz)
• SHA256 checksums for verification

Versioning

This project maintains its own semantic versioning independent of upstream Apprise. Compatibility with the upstream caronc/apprise project is tracked via internal/version.UpstreamVersion.

Changelog

All notable changes are documented in CHANGELOG.md. The changelog follows the Keep a Changelog format.

Release Process

Releases are automated through GitHub Actions:

1. Version bumps and changelog updates use Knope
2. The release workflow builds, signs (macOS), and notarizes (macOS) binaries
3. Assets are automatically uploaded to GitHub Releases
4. Upstream version parity is tracked via automated checks

See PROCESS.md for detailed release procedures.

Project Structure

apprise-go/
├── cmd/           # Command-line application
├── internal/      # Internal Go packages
├── assets/        # Default notification icons and themes
├── dist/          # Build output directory
├── scripts/       # Build and release scripts
├── .github/       # GitHub Actions workflows
├── CHANGELOG.md   # Version history and changes
├── PROCESS.md     # Development and release processes
├── AGENTS.md      # Agent configuration documentation
└── README.md      # This file

Attribution and License

• Upstream Apprise is created by Chris Caron and licensed under the BSD 2-Clause License
• This project reimplements Apprise behavior in Go and includes modifications
• See LICENSE for the full license text
• See NOTICE.md for additional attribution information

Contributing

Contributions are welcome! Please see PROCESS.md for development guidelines and the release process.

Quick Start for Contributors

# Clone the repository
git clone https://github.com/unraid/apprise-go.git
cd apprise-go

# Build the project
go build -o apprise-go ./cmd/apprise

# Run tests
go test ./...

Support

• Issues: Report bugs or request features via GitHub Issues
• Upstream Apprise: For questions about the original Python project, see caronc/apprise

Related Projects

• caronc/apprise - The original Python implementation
• caronc/apprise-api - RESTful API for Apprise

---

Made with ❤️ by the developers of Unraid

Learn more about Unraid OS

Documentation

Index

• Constants
• Variables
• func Send(rawURLs []string, body string, options ...Option) error
• func SupportedSchemas() []string
• func SupportsSchema(schema string) bool
• type Apprise
  • func New() *Apprise
  • func (a *Apprise) Add(rawURL string) error
  • func (a *Apprise) AddAll(rawURLs ...string) error
  • func (a *Apprise) Send(body string, options ...Option) error
  • func (a *Apprise) URLs() []string
• type NotifyType
  • func ParseNotifyType(raw string) (NotifyType, bool)
• type Option
  • func WithAttachmentMaxBytes(maxBytes int64) Option
  • func WithAttachments(rawAttachments ...string) Option
  • func WithInputFormat(inputFormat string) Option
  • func WithNotifyType(notifyType NotifyType) Option
  • func WithTitle(title string) Option
• type TargetError
  • func (e *TargetError) Error() string
  • func (e *TargetError) Unwrap() error

Constants

const (
	// NotifyInfo sends an informational notification.
	NotifyInfo = notify.NotifyInfo
	// NotifySuccess sends a success notification.
	NotifySuccess = notify.NotifySuccess
	// NotifyWarning sends a warning notification.
	NotifyWarning = notify.NotifyWarning
	// NotifyFailure sends a failure notification.
	NotifyFailure = notify.NotifyFailure
)

Variables

var ErrNoTargets = errors.New("apprise: no notification URLs configured")

ErrNoTargets is returned when Send is called without any configured URLs.

Functions

func Send

func Send(rawURLs []string, body string, options ...Option) error

Send sends body to rawURLs without explicitly creating an Apprise client.

func SupportedSchemas

func SupportedSchemas() []string

SupportedSchemas returns the URL schemas supported by this build.

func SupportsSchema

func SupportsSchema(schema string) bool

SupportsSchema reports whether schema is supported by this build.

Types

type Apprise

type Apprise struct {
	// contains filtered or unexported fields
}

Apprise stores notification target URLs and sends messages to them.

func New

func New() *Apprise

New creates an empty Apprise client.

func (*Apprise) Add

func (a *Apprise) Add(rawURL string) error

Add validates and stores a notification target URL.

func (*Apprise) AddAll

func (a *Apprise) AddAll(rawURLs ...string) error

AddAll validates and stores multiple notification target URLs. It stops on the first error, leaving any earlier valid URLs configured.

func (*Apprise) Send

func (a *Apprise) Send(body string, options ...Option) error

Send sends body to all configured target URLs.

func (*Apprise) URLs

func (a *Apprise) URLs() []string

URLs returns a copy of the configured notification target URLs.

type NotifyType

type NotifyType = notify.NotifyType

NotifyType identifies the semantic type of a notification.

func ParseNotifyType

func ParseNotifyType(raw string) (NotifyType, bool)

ParseNotifyType parses an Apprise notification type string.

type Option

type Option func(*notifyOptions)

Option configures a Send call.

func WithAttachmentMaxBytes

func WithAttachmentMaxBytes(maxBytes int64) Option

WithAttachmentMaxBytes sets the maximum size for each remote attachment.

func WithAttachments

func WithAttachments(rawAttachments ...string) Option

WithAttachments attaches one or more local file paths or trusted attachment URLs to the notification. Attachment URLs are fetched as provided; do not pass untrusted end-user URLs.

func WithInputFormat

func WithInputFormat(inputFormat string) Option

WithInputFormat sets the source body format before target-specific conversion.

func WithNotifyType

func WithNotifyType(notifyType NotifyType) Option

WithNotifyType sets the semantic notification type for a Send call.

func WithTitle

func WithTitle(title string) Option

WithTitle sets the notification title for a Send call.

type TargetError

type TargetError struct {
	URL string
	Err error
}

TargetError wraps a failure from one configured target URL.

func (*TargetError) Error

func (e *TargetError) Error() string

func (*TargetError) Unwrap

func (e *TargetError) Unwrap() error