Introduction

Apprise is a free Python based notification tool that just makes our lives easier. It allows you to interact with just about all of the most popular Notification Services available to us today! I mean right now while writing this blog, there are already 28 supported services you can use! We’re talk about services like Discord, Telegram, Slack, Pushbullet, IFTTT, Amazon Web Service (SNS), Email, etc, etc.

How Does It Work?

You could be sending our system stats via an email from the command line:

# top will print all of the processes running on our Linux system
# Then we pipe that result into apprise and send it in an email:
top -b -n 1 -c | \
   apprise -t "my system stats" mailto://user:password@hotmail.com

Or maybe you’re a Microsoft Windows user! No problem, Apprise is not OS dependent at all! You could still send your services running to your email like so:

# TASKLIST will print all of the services running on our Widows system
# Then we pipe that result into apprise and send it in an email:
TASKLIST /svc ^ \
   apprise -t "my system stats" mailto://user:password@hotmail.com

The tool itself is pretty simple to use:

apprise [Options] [[[URI1] [URI2] ...]

Here are what the options look like:

Option	Description
-t, –title TEXT	Specify the message title. This field is optional.
-b, –body TEXT	Specify the message body. If you don’t specify this value, then STDIN is used instead.
-n, –notification-type TYPE	Specify the message type (default=info). The other options are success, warning, and error.
-T, –theme THEME	Specify the default theme. This isn’t discussed in this blog entry, but I’ll talk about it soon!
-v, –verbose	By default apprise is pretty quiet. By specifying -v (or a few more -vv and -vvv) you can increase the verbosity of the script. This is useful if you’re trying to figure out why a service might not be working for you.

To make a notification you must provide:

1. One or more Uniform Resource Identifier(s) (URI). These are used to identify and configure Apprise with the service you wish to access (Email, Discord, etc). I’ll explain a more about this in the next section.
2. A message body to pass along with the notification you’re going to make. This could be piped in from STDIN like in the examples above, or you can pass the message in via the –body (-b) switch.

Note: In the not so distant future, the message body requirement won’t be required for all services as it is today. An example where the body isn’t always necessary is for IFTTT requests. The message body also isn’t required for most home automation services that Apprise may support in the future!

The Apprise Notification URI

The Uniform Resource Identifier (URI) is the magic one-liner configuration that tells Apprise everything it needs to in order to notify your service(s).

Generally URI looks like this:

• service://user@host:port
• service://password@host:port
• service://user:password@host:port
• service://host:port
• service://host

We see these every day when we access a website such as https://nuxref.com.

Take an Apprise Email URI for example:

mailtos://nuxref:mypass@gmail.com
  ^         ^      ^       ^
  |         |      |       |
service   login    |   email domain
                   |
               password

In the above example, Apprise knows you want to send an email because of the mailto:// service identified in front. From there it can acquire all of the server information it needs about this service based upon the rest of the URI provided. Email (URI) configuration can get complicated depending on what you want to do… But for most email providers, Apprise makes it really easy! You can read more about email URIs here.

There are other Apprise URIs that are really easy to use too. For example, if you’re on a Microsoft Windows PC, you can use the windows:// URI and send your system a broadcast message without any effort at all:

apprise -t "Apprise Is Awesome" -b "A Windows Notification" windows://

Note: This only works on a Microsoft Windows PC. It also requires you to have the pypiwin32 bundle installed (if you don’t have it already).

If you’re on a Linux PC you can use the gnome:// or kde:// to achieve the same effects as The MS Windows users get:

# Gnome Messages:
apprise -t "Apprise Is Awesome" -b "A Gnome Notification" gnome://

# KDE Messages
apprise -t "Apprise Is Awesome" -b "A KDE Notification" kde://

There are so many supported notification services, and the list continues to grow.

The other advantage of having all of your configuration in a single URI is that can chain them all together. Apprise will notify each and every one you specify with the message you put in place. There is no limit to the number of servers that you specify.

# The below fires off a pushbullet (pbul://) notification
# and an email (mailto://)
apprise -b "visit nuxref.com" \
   mailto://myusername:mypassword@yahoo.com \
   pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b

By uniquely mapping services to their own URIs, we can additionally allow for custom options this way too. For example, let’s say we want our email to be text formatted instead of the default html. No problem:

# Send all of our log files in a text based email format:
cat /var/log/messages | apprise -t "Logging" \
   mailtos://nuxref:mypass@gmail.com?format=text 

Notification Types

Notification Type	Image
info
success
warning
failure

By default all of your notifications are sent as an info message. This comes into play depending on what kind of notification service you’re using. Some services really don’t care, while others will give you a richer experience as a result of knowing the message type.

Notification services like Slack and Telegram can decorate the message you send it with an icon.

Meanwhile other services like SMS Messages (sent from AWS) or Emails won’t use this feature at all.

# The below sends a success message to the general channel on
# slack (slack://):
apprise -b "visit nuxref.com" -t "success" \
   slack:///T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F/#general

Note: You will need to build your own URI for your own services that you use. the URIs I use in my example are made up just to demonstrate how it works.

Wait… Exposing My Password On The Command Line Is a Terrible Idea!

I couldn’t agree more! Thankfully Apprise supports configuration files

# Place your URLs into a configuration file in our home directory:
cat << _EOF > ~/.apprise
mailto://myusername:mypassword@yahoo.com
pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b
slack:///T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F/#nuxref
_EOF

# Now secure the file so no one can peak at what is personal
# to you:
chmod 400 ~/.apprise

# Now we can call apprise and source the file for our service URIs:
# By default apprise looks in ~/.apprise so now the command line
# gets even easier to use (and more secure too!)
apprise -b 'Apprise Rocks!'

# The above command would fire the notification to all 3 of the
# services you identified in the ~/.apprise file.

# If you want to manage multiple files, you can easily do this too
# just use the --config switch on the command line and point to
# your file:
apprise -b 'My Message Body' --config=/path/to/config

Microsoft Windows users could do a similar solution:

# Prepare ourselves a file (use a text editor is more ideal
# then what I'm putting here):
mkdir  %APPDATA%/Apprise
echo "mailto://myusername:mypassword@yahoo.com" > %APPDATA%/Apprise/apprise
echo "pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b" >> %APPDATA%/Apprise/apprise
echo "slack:///T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F/#nuxref" >> %APPDATA%/Apprise/apprise

# Set permissions on this file at this point if you want

# Now we can call apprise and source the file for our service URIs:
apprise -b 'Apprise Rocks!'

# If you want to manage multiple files, you can easily do this too
# just use the --config switch on the command line and point to
# your file:
apprise -b 'My Message Body' --config=C:\path\to\config

How Do I Get Apprise?

Assuming you’ve got Python (2.7 or 3.x) already installed, then PyPI is probably the best place to go. But if you have pip installed, just could also just do the following:

pip install apprise

That’s it! You’re ready to go!

Sources

• Apprise GitHub Page
• Apprise Wiki
• Apprise PyPI Page