In today’s fast-paced digital environment, having a reliable notification system is crucial for monitoring applications, services, and infrastructure. Enter Apprise API – a powerful, lightweight REST framework that wraps the popular Apprise notification library, allowing you to send notifications to over 100+ services through a single, unified interface.
What is Apprise API?
Apprise API is a microservice that provides a RESTful interface to the Apprise notification library. It enables you to:
- Send notifications to 100+ different services through a consistent API
- Store notification configurations for easy reuse
- Tag and group notification endpoints
- Attach files to your notifications
- Create a centralized notification gateway for your entire infrastructure
The API was designed to seamlessly integrate into existing ecosystems, making it an ideal solution for DevOps teams, system administrators, and developers looking for a unified notification service.
Key Features
- Wide Service Support: Send notifications to Telegram, Discord, Slack, Email, SMS services, and many more
- Simple REST Interface: Easy-to-use API endpoints for sending notifications
- Stateful or Stateless: Use it with persistent storage or as a simple pass-through service
- Configuration Manager: Built-in web UI for managing configurations
- File Attachments: Support for sending files with your notifications
- Tagging System: Group services together with customizable tags
- Docker Ready: Quick and easy deployment using containers
Installation with Docker
Installing Apprise API with Docker is straightforward using the LinuxServer.io image. Here’s how to get started:
Basic Installation
The simplest way to run Apprise API is to pull the LinuxServer.io image from Docker Hub:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# Pull the latest LinuxServer.io Apprise API image docker pull lscr.io/linuxserver/apprise-api:latest # Run the container with basic settings docker run -d \ --name=apprise-api \ -e PUID=1000 \ -e PGID=1000 \ -e TZ=Etc/UTC \ -p 8000:8000 \ -v /path/to/apprise-api/config:/config \ --restart unless-stopped \ lscr.io/linuxserver/apprise-api:latest |
Once running, you can access the web interface at http://localhost:8000.
Advanced Installation with Attachments Support
If you want to enable file attachment support in notifications:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# Create directories for persistent storage mkdir -p /path/to/apprise-api/config mkdir -p /path/to/apprise-api/attachments # Run with attachment support docker run -d \ --name=apprise-api \ -e PUID=1000 \ -e PGID=1000 \ -e TZ=Etc/UTC \ -e APPRISE_ATTACH_SIZE=200 \ -p 8000:8000 \ -v /path/to/apprise-api/config:/config \ -v /path/to/apprise-api/attachments:/attachments \ --restart unless-stopped \ lscr.io/linuxserver/apprise-api:latest |
Using Docker Compose
For easier management, you can use Docker Compose. Create a docker-compose.yml file:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
--- services: apprise-api: image: lscr.io/linuxserver/apprise-api:latest container_name: apprise-api environment: - PUID=1000 - PGID=1000 - TZ=Etc/UTC - APPRISE_ATTACH_SIZE=200 #optional volumes: - /path/to/apprise-api/config:/config - /path/to/apprise-api/attachments:/attachments #optional ports: - 8000:8000 restart: unless-stopped |
Then start the service:
|
1 2 3 |
docker-compose up -d |
Environment Variables
The LinuxServer.io Apprise API container offers customization options through environment variables:
Variable | Description |
|---|---|
PUID & PGID | User and group ID the container runs as (default: 1000) |
TZ | Specify a timezone (e.g., Etc/UTC, America/New_York) |
APPRISE_ATTACH_SIZE | Max attachment size in MB (set to 0 to disable attachments) |
Volume Mappings
The container uses these volume mappings:
Volume | Function |
|---|---|
/config | Persistent configuration files |
/attachments | Temporary storage for files sent with notifications |
For additional container configuration details, refer to the LinuxServer.io documentation.
Using the API
Sending a Simple Notification
Once your Apprise API is running, you can send notifications with a simple HTTP request:
|
1 2 3 4 5 |
# Send a notification to a specified service curl -X POST -d 'urls=tgram://bottoken/ChatID&body=Hello from Apprise API!' \ http://localhost:8000/notify |
With Configuration Files
For a more organized approach, you can save configurations:
|
1 2 3 4 5 6 7 8 9 10 |
# Save a configuration with the key "myservices" curl -X POST -d 'urls=discord://webhook_id/webhook_token,slack://TokenA/TokenB/TokenC' \ http://localhost:8000/add/myservices # Send a notification using the saved configuration curl -X POST -d 'body=Alert: Server CPU usage high!' \ http://localhost:8000/notify/myservices |
Using Tags
Tags allow you to group services:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# Configure services with tags # YAML configuration with tags for different teams curl -X POST -F 'config= urls: - discord://webhook_id/webhook_token: tag: devops alerts - slack://TokenA/TokenB/TokenC: tag: devops management - mailto://user:pass@gmail.com: tag: management ' -F 'format=yaml' http://localhost:8000/add/company-alerts # Notify only DevOps team curl -X POST -d 'tag=devops&body=Deployment completed successfully' \ http://localhost:8000/notify/company-alerts |
Supported Notification Services
Apprise supports an impressive list of over 100 notification services, including:
- Chat Platforms: Discord, Slack, Telegram, Microsoft Teams, Google Chat
- Email Services: SMTP, Gmail, Office 365, SendGrid, Mailgun
- SMS Services: Twilio, Vonage, MessageBird, AWS SNS
- Push Notifications: Pushover, PushBullet, Gotify
- Social Media: Twitter, Mastodon, Reddit
- Ticketing Systems: Jira, PagerDuty
- Desktop Notifications: Windows, MacOS, Linux (GNOME, KDE)
The complete list of supported services can be found in the Apprise Wiki.
Security Considerations
By default, Apprise API does not include authentication. For production use, consider:
- Restricting access using a reverse proxy with authentication
- Using the built-in authentication option with NginX configuration
- Running the API on an internal network only
- Setting up environment variables like
APPRISE_CONFIG_LOCKfor a read-only configuration
Thoughts
Apprise API offers a powerful, unified way to handle notifications across your entire infrastructure. With its Docker-based installation, you can be up and running in minutes, sending notifications to any of the 100+ supported services through a consistent, easy-to-use interface.
Whether you’re building a monitoring system, need alerts for your CI/CD pipeline, or want to consolidate all your notification needs into a single service, Apprise API has you covered.
