caronc/apprise repository overview

⁠Apprise API

Take advantage of Apprise⁠ through your network with a user-friendly API.

• Send notifications to more than 150+ services.
• An incredibly lightweight gateway to Apprise.
• A production-ready micro-service at your disposal.
• A simple website to build, verify and test your configuration with.
• An Android app⁠ to notify and manage your server from your phone.

Apprise API was designed to easily fit into existing (and new) ecosystems that are looking for a simple notification solution.

Visit the Official Documentation⁠ site for more information on the Apprise API.

⁠Screenshots

The built-in Configuration Manager lets you save, review and test your notification setup from any browser:

More screenshots: Review⁠ · Notifications⁠

⁠Apprise Mobile (Android)

Apprise Mobile is the Android companion app for Apprise API. Send a message, photo, or file to one destination, a group, or every destination you've configured. The app connects to your running Apprise API server; it is not a standalone notification service.

Get Apprise Mobile on Google Play⁠

To connect, open the Configuration Manager in your browser and reveal the Apprise Mobile Quick Setup QR code on any saved configuration. Scanning it from the app adds your server and loads that configuration in one step.

Screenshots: Dashboard⁠ · URL Builder⁠ · Delivery Report⁠

Visit the Apprise Mobile⁠ page for more details, the privacy policy and terms.

⁠Installation

The following options should allow you to access the API at http://localhost:8000/ from your browser.

⁠Docker

# Retrieve container
docker pull caronc/apprise:latest

# Start it up
docker run --name apprise \
   -p 8000:8000 \
   --user "$(id -u):$(id -g)" \
   -v /path/to/local/config:/config \
   -v /path/to/local/plugin:/plugin \
   -v /path/to/local/attach:/attach \
   -e APPRISE_STATEFUL_MODE=simple \
   -e APPRISE_WORKER_COUNT=1 \
   -e APPRISE_DEFAULT_FORMAT=text \
   -e TZ=America/Toronto \
   -d caronc/apprise:latest

• /config holds your saved configuration. Persistent storage lives under /config/store, so one volume is enough.
• /plugin is optional and holds your own custom Apprise plugins.
• /attach holds uploaded attachments.
• /tmp holds temporary files and is suitable for tmpfs in hardened deployments.

⁠Docker Compose

services:
  apprise:
    image: caronc/apprise:latest
    container_name: apprise
    ports:
      - "8000:8000"
    environment:
      APPRISE_STATEFUL_MODE: simple
      APPRISE_WORKER_COUNT: "1"
      APPRISE_DEFAULT_FORMAT: "text"
      TZ: America/Toronto
    volumes:
      - ./config:/config
      - ./plugin:/plugin
      - ./attach:/attach

⁠Apprise URLs

📣 To send a notification, you first need one or more Apprise URLs⁠ for the services you want to use. Visit https://appriseit.com/services/⁠ to see the ever-growing list.

⁠API Details

⁠Health Checks

⁠Stateless Solution

⁠Persistent (Stateful) Storage Solution

⁠Other Endpoints

⁠Notification Payload

Both /notify/ and /notify/{KEY} accept form or JSON payloads:

• body: Your message. Optional when an attachment is provided.
• title: An optional title.
• type: info, success, warning or failure. Defaults to info.
• format: text, markdown or html.
• tag: Select saved destinations by tag (stateful only).
• attach: One or more files or web URLs to attach.
• template: Values for a saved YAML configuration written with ${NAME} markers (stateful only).

Add ?stream=yes (or Accept: text/event-stream) to watch delivery progress live.

⁠Example Usage

# Stateless notification
curl -X POST -d 'urls=mailto://user:[email protected]&body=test message' \
    http://localhost:8000/notify

# Stateless notification using JSON
curl -X POST -H "Content-Type: application/json" \
    -d '{"urls": "mailto://user:[email protected]", "body":"test message"}' \
    http://localhost:8000/notify

# Stateful notification via {KEY}
curl -X POST -d "body=test message" http://localhost:8000/notify/abc123

# Notify only destinations tagged devops
curl -X POST -d 'tag=devops&body=test message' \
    http://localhost:8000/notify/abc123

# Send an attachment
curl -X POST -F 'body=test message' -F [email protected] \
    http://localhost:8000/notify/abc123

# Keep the Config ID out of the URL
curl -X POST -H "X-Apprise-Config-ID: abc123" \
    -d "body=test message" http://localhost:8000/notify

⁠Authentication

Apprise API can protect its endpoints with HTTP Basic Auth:

docker run --name apprise \
   -p 8000:8000 \
   -v /path/to/local/config:/config \
   -e APPRISE_AUTH_REQUIRED=yes \
   -e APPRISE_USER=admin \
   -e APPRISE_PASSWORD=your-password-here \
   -d caronc/apprise:latest

• The administrator can access and manage every Config ID.
• Each Config ID can have its own login, so people only reach their own configuration.
• Each Config ID has an access mode: user, locked, public or disabled. locked and public require a specific tag when notifying.
• Only user access may send stateless notifications, and it must pass its X-Apprise-Config-ID header.

See the Authentication⁠ section for the full details.

⁠Environment Variables

Below are the most common settings. See the full list⁠ for everything else (storage, pruning, streaming, Kubernetes and nginx overrides).

⁠Apprise Integration

⁠Apprise CLI

apprise -vv --body="test message" \
   --config=http://localhost:8000/get/{KEY}

⁠Python

import apprise

# Point our configuration to this API server
config = apprise.AppriseConfig()
config.add('http://localhost:8000/get/{KEY}')

# Create our Apprise instance and send a test message
a = apprise.Apprise()
a.add(config)
a.notify('test message')

For webhooks, custom plugins, Kubernetes, live streaming and the complete API reference, visit the Apprise API Repository⁠ and the Official Documentation⁠.