Skip to content

Development_API

Jump to bottom
Chris Caron edited this page Jun 7, 2025 · 34 revisions

Table of Contents

The Apprise Object

Instantiation

import apprise

apobj = apprise.Apprise()

add(): Register Notification Services

Add one or more service URLs to your notification pool:

# Single service
ok = apobj.add('mailto://user:[email protected]')

# Multiple services
ok = apobj.add([
    'growl://192.168.1.50',
    'windows://',
])
  • Returns: True if all URLs parsed and added; False otherwise.

notify(): Send Notification(s)

Send to all—or filter by tag:

# Broad notification
apobj.notify(
    title='Deployment Complete',
    body='Version 2.1.0 has been successfully deployed!',
)

# Filtered by tag
apobj.notify(
    title='Error Alert',
    body='Service X failed to respond',
    tag='critical'
)

Tagging

Apprise tagging allows you to group and filter notifications. Two main design patterns exist:

  1. Inclusive
    Define department- or role-based tags and notify any combination:

    import apprise

apobj = apprise.Apprise()

# 1. Register each department’s notification endpoint with its tag
apobj.add('slack://hooks.slack.com/services/FINANCE_WEBHOOK_URL',   tag='finance')
apobj.add('slack://hooks.slack.com/services/DEVOPS_WEBHOOK_URL',    tag='devops')
apobj.add('slack://hooks.slack.com/services/DEVELOPERS_WEBHOOK_URL', tag='developers')
apobj.add('slack://hooks.slack.com/services/MANAGEMENT_WEBHOOK_URL', tag='management')

# 2. Now fire notifications to whichever groups you need:

# A budget alert → finance team only
apobj.notify(
    title='Budget Exceeded',
    body='Q2 marketing spend is now 120% of planned.',
    tag='finance'
)

# A CI/CD pipeline failure → devops AND developers
apobj.notify(
    title='Pipeline Failed',
    body='Build #492 on main branch failed unit tests.',
    tag=['devops', 'developers']
)

# A high-level executive summary → management only
apobj.notify(
    title='Monthly Operations Summary',
    body='All systems green; revenue +8% month-over-month.',
    tag='management'
)

# A system-wide alert → broadcast to all teams
apobj.notify(
    title='Service Outage',
    body='API gateway is down; investigating root cause.',
    tag=['finance', 'devops', 'developers', 'management']
)

  2. Exclusive
    Use specialized tags (e.g. 'warning-download', 'warning-upload'). Apprise ignores unmatched tags silently.

    # Add services expecting specific warnings
apobj.add('json://localhost/download/',     tag='warning-download')
apobj.add('json://localhost/upload/',       tag='warning-upload')

# Only 'warning-upload' triggers
apobj.notify(
    title='Upload Issue',
    body='Upload failed',
    tag='warning-upload'
)

# 'warning-parse' is ignored if no service has that tag
apobj.notify(
    title='Parse Problem',
    body='Parse failed',
    tag='warning-parse'
)

General filter expressions follow:

Filter Selected services
'TagA' Has TagA
['TagA', 'TagB'] OR between tags
[('TagA','TagC'), 'TagB'] (AND within tuple) OR others
[('TagB','TagC')] AND between tags

Message Types and Themes

By default, all notifications use NotifyType.INFO with the default theme. Available types:

Notification Type Text Representation Image
NotifyType.INFO info info
NotifyType.SUCCESS success success
NotifyType.WARNING warning warning
NotifyType.FAILURE failure failure

Use a different type:

from apprise import NotifyType

apobj.notify(
    title='Disk Space Low',
    body='Only 5% left',
    notify_type=NotifyType.WARNING,
)

async_notify(): Awaitable Notifications

Use inside your existing asyncio loop:

import asyncio

async def main():
    results = await apobj.async_notify(
        title='Async Test',
        body='This was sent asynchronously',
    )
    print(results)

asyncio.run(main())

len(): Count Services

print(f"There are {len(apobj)} services loaded")

clear(): Reset Service List

apobj.clear()

details(): Inspect Configuration & Schemas

info = apobj.details()

Returns a dict containing:

  • version — Apprise version
  • asset — current AppriseAsset settings
  • schemas — supported services and URLs
  • details — templates, tokens, args, kwargs
Example JSON 
{
  "version": "1.0.0",
  "asset": { /* ... */ },
  "schemas": [ /* ... */ ],
  "details": { /* ... */ }
}

The AppriseAsset Object

AppriseAsset is the central configuration object that controls the look, feel, and behaviour of your notifications. Even when you simply instantiate Apprise(), it creates a default AppriseAsset() under the hood (using the “default” theme in apprise/assets/themes/default). By customizing AppriseAsset, you can:

  • Override the application identifier, description, and URL
  • Point to your own local or hosted images (logos and type-specific icons)
  • Enable or disable asynchronous delivery, logging filters, and escape-sequence interpretation
  • Configure persistent storage (caching) for repeated notifications
  • Add your own plugin directories or files

Constructor Signature

from typing import Union, List, Optional
import apprise

asset = apprise.AppriseAsset(
    # Theme & app identity
    theme: str = "default",
    app_id: str = "Apprise",
    app_desc: str = "Apprise Notifications",
    app_url: str = "https://github.com/caronc/apprise",

    # Image settings
    default_extension: str = ".png",
    image_path_mask: str = "/…/apprise/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}",
    image_url_mask: str = (
        "https://raw.githubusercontent.com/caronc/apprise/master"
        "/apprise/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}"
    ),
    image_url_logo: Optional[str] = None,

    # Plugin discovery
    plugin_paths: Union[str, List[str]] = None,

    # Delivery behaviour
    async_mode: bool = True,
    interpret_escapes: bool = False,
    encoding: str = "utf-8",
    secure_logging: bool = True,

    # Persistent storage (caching)
    storage_mode: Optional[str] = None,    # "auto" | "flush"
    storage_path: Optional[str] = None,
)

Key Attributes

Name Type Default Description
theme str "default" Which theme directory to use (maps into {THEME}).
app_id str "Apprise" A short identifier/name for your application.
app_desc str "Apprise Notifications" A brief description of your notification system.
app_url str "https://github.com/caronc/apprise" A URL where users can learn more about your app.
default_extension str ".png" Default image file extension (e.g. ".png", ".jpeg").
image_path_mask str Local path mask using {THEME}, {TYPE}, {XY}, {EXTENSION}. Where on disk to find your images/icons.
image_url_mask str Remote URL mask using {THEME}, {TYPE}, {XY}, {EXTENSION}. Where to fetch hosted images/icons.
image_url_logo Optional[str] None A single logo URL for your app (uses {THEME} if provided).
html_notify_map Dict[NotifyType,str] Maps each NotifyType (INFO/SUCCESS/WARNING/FAILURE) → a hex colour code. Used by some services that support colourised HTML. An example of this can be found below
async_mode bool True Send notifications concurrently (if the service/client supports it).
interpret_escapes bool False Convert \r and \n etc., in your title/body before sending.
encoding str "utf-8" Character encoding for your content.
secure_logging bool True Filter out secrets (passwords, tokens) from debug logs.
plugin_paths List[str] [] One-level scan of directories or explicit .py files for custom notification plugins.
storage_mode Optional[str] None Enable persistent storage: "auto" (on-demand) or "flush" (per notification).
storage_path Optional[str] None Custom file path to use for persistent storage (overrides default).

Here is an example of what the html_notify_map may look like (below is the default settings):

html_notify_map = {
    NotifyType.INFO:    '#3AA3E3',
    NotifyType.SUCCESS: '#3AA337',
    NotifyType.FAILURE:  '#A32037',
    NotifyType.WARNING: '#CACF29',
}

Templating Placeholders

When resolving image_path_mask or image_url_mask, the following tokens are replaced:

Placeholder Runtime Value Example Description
{THEME} asset.theme "default" The theme folder name to reference.
{TYPE} lower-cased NotifyType "warning" Type of notification (info, success, warning, failure, etc.).
{XY} resolution string "72x72" Pixel dimensions of the icon. Apprise ships 32x32, 72x72, 128x128, 256x256 by default.
{EXTENSION} asset.default_extension ".png" File extension for your images.

Usage Example

import apprise
from apprise import AppriseAsset

# 1. Define your custom asset:
asset = AppriseAsset(
    app_id="MyApp",
    app_desc="MyApp Alerts",
    app_url="https://example.com",
    theme="custom-theme",
    default_extension=".jpeg",
    image_path_mask="/opt/images/{THEME}/{TYPE}-{XY}{EXTENSION}",
    image_url_mask=(
        "https://cdn.example.com/assets/{THEME}/{TYPE}-{XY}{EXTENSION}"
    ),
    plugin_paths=[
        "/opt/myapp/plugins",       # Scan this directory for .py plugins
        "/opt/myapp/custom.py",     # Load this single plugin file
    ],
    async_mode=False,               # Send one notification at a time
    storage_mode="flush",           # Persist every notification to disk
    storage_path="/var/cache/myapp.db",
)

# 2. Create Apprise with your asset:
apobj = apprise.Apprise(asset=asset)

# 3. Add your services and send a notification:
apobj.add("mailto://user:[email protected]")
apobj.add("discord://webhook_id/webhook_token")
apobj.notify(
    title="Deployment Complete",
    body="Version 2.1.0 has been successfully deployed!",
)

Tip: You can also override any attribute on the fly:

asset.theme = "night-mode"
asset.secure_logging = False

The Apprise Notification Object

The The Apprise Object actually already does a really good managing these for you. But if you want to manage the notifications yourself here is how you can do it:

# Import this library
import apprise

# Instantiate an object. This is what the apprise object
# would have otherwise done under the hood:
 obj = apprise.Apprise.instantiate('glib://')

# Now you can use the notify() function to pass notifications.
# notify() is similar to Apprise.notify() except the overhead of
# of tagging is not present.  There also no handling of the
# the text input type (HTML, MARKUP, etc).  This is on you
# to manipulate before passing in the content.
obj.notify(
    body=u"A test message",
    title=u"a title",
)

# send() is a very low level call which directly posts the
# body and title you specify to the remote notification server
# There is NO data manipulation here, no overflow handling
# nothing.  But this allows you to free form your own
# messages and pass them along using the apprise handling
obj.send(
    body=u"A test message",
    title=u"a title",
)

Features

Pickle/Serialization Support

You can Serialize your loaded notifications so they can be restored later on:

import apprise
import pickle

# Instantiate our object
apobj = apprise.Apprise()

# Add our URLs
apobj.add("json://localhost")
apobj.add("xml://localhost")
apobj.add("form://localhost")
apobj.add("mailto://user:pass@localhost")

# Now serialize our object for any purpose
serialized = pickle.dumps(apobj)

# Consider even storing it to disk if you wanted:
with open("myfile.txt", "w") as file:
    file.write(serialized)

With respect to the above example, we could later (or in another application) reload our object back as it was without having to re-add all the URLs again:

# Restore our Apprise Object
apobj = pickle.loads(serialized)

# Perhaps we previously wrote it to disk, well we can load our data this way as well:
with open("myfile.txt", "r+") as file:
   apobj = pickle.loads(file.read())

Quick Links:

Clone this wiki locally