Introduction

Apprise-compatible Rust library, CLI and HTTP server to send notifications to 150+ services via a single URL. It ships as a single static binary. Installing covers the binaries, the container image and building from source.

Send a notification

Each URL names a service and carries its credentials and options. Find the format of yours in the service list.

mercurio -t "Backup" -b "Finished in 42s" ntfy://my-topic "discord://ID/TOKEN"

# body from stdin
df -h / | mercurio -t "Disk usage" mailto://user:password@example.com 

# advanced formatting
mercurio -n failure -i markdown -b "**db-1** is down" tgram://BOT_TOKEN/CHAT_ID

-n sets the type (info, success, warning, failure), which services turn into colours, icons or priorities. -i declares the body’s markup; mercurio converts it for each service (Formats). mercurio check URL... validates URLs without sending. -d lists what would be notified. The exit code is 0 sent, 1 failed, 2 usage error, 3 nothing matched the tags, 4 partly sent (Command line).

Use a configuration file

Without URLs on the command line, mercurio reads ~/.config/apprise/apprise.conf:

version: 1
urls:
  - ntfy://my-topic
  - mailto://user:password@example.com:
      - to: oncall@example.com
        tag: critical
  - slack://xoxb-token/#ops:
      tag: devops, critical

mercurio -b "untagged entries only"           # ntfy
mercurio -g critical -b "page someone"        # e-mail and Slack
mercurio -g all -d                            # list everything

See Configuration files for the TEXT and YAML formats, tags, includes and templates.

Use the library

#![allow(unused)]
fn main() {
use mercurio::{Mercurio, Message, NotifyType};

let mut m = Mercurio::new();
m.add("ntfy://my-topic")?;
m.add("slack://xoxb-token/#alerts")?;
let report = m.notify(&Message::new("Deploy finished").title("ci").kind(NotifyType::Success));
assert!(report.is_success());
Ok::<(), mercurio::Error>(())
}

notify blocks until every service has answered, the Report lists each URL’s outcome. Services are sans-IO: they return a plan of requests, so any transport (async, proxy, test double) can run them and tests need no accounts. See Using the library.

Run the HTTP server

Mercurio ships an Apprise-compatible http server:

mercurio serve --bind 127.0.0.1:8000
curl -X POST -d 'urls=ntfy://my-topic' -d 'body=hello' http://127.0.0.1:8000/notify

See HTTP server.

How this book is organised

• User guide: the command line, URLs, configuration files, messages and the HTTP server. All of it applies to the library as well.
• Library: using mercurio from Rust. The API reference is rustdoc (api/mercurio in the published book).
• Services: one page per service: URL formats, every query parameter with its default, examples and known differences.
• Reference: Differences with Apprise.

Installing

Every GitHub release ships a prebuilt mercurio binary with support for every service.

Cargo

cargo binstall mercurio-cli

Container

In server mode:

docker run --rm -p 8000:8000 ghcr.io/alphajack/mercurio

Any other arguments go to the CLI:

docker run --rm ghcr.io/alphajack/mercurio -t "Backup" -b "Finished" ntfy://my-topic

Installer script

Linux and macOS:

curl -LsSf https://github.com/AlphaJack/mercurio/releases/latest/download/mercurio-cli-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/AlphaJack/mercurio/releases/latest/download/mercurio-cli-installer.ps1 | iex"

Both put mercurio in $CARGO_HOME/bin (~/.cargo/bin). Archives and their .sha256 checksums are on the releases page.

AUR

The compiled binary and systemd unit can be installed from the Arch User Repository as mercurio-bin

Command line

mercurio --help:

Apprise-compatible Rust library, CLI and HTTP server to send notifications to 150+ services via a single URL.

Usage: mercurio [OPTIONS] [URL]... [COMMAND]

Commands:
  services  List the supported services
  check     Validate URLs or configuration; send nothing
  serve     Run the HTTP notification server
  storage   Show (`list`) or clean (`prune`, `clear`) the persistent storage

Arguments:
  [URL]...  Notification URLs

Options:
  -b, --body <TEXT>                Message body [default: read stdin]
  -t, --title <TEXT>               Message title
  -n, --notification-type <TYPE>   `info`, `success`, `warning` or `failure` [default: info]
  -i, --input-format <FORMAT>      Markup of the body: `text`, `html` or `markdown`
  -a, --attach <PATH|URL>          Attach a file: path, `file://`, `http(s)://` or `memory://` (repeatable)
  -c, --config <PATH|URL>          Load a TEXT or YAML configuration (repeatable)
  -g, --tag <TAG>                  Notify services tagged TAG; `a,b` needs both, repeat for either, `all` notifies everything
      --template-var <NAME=VALUE>  Value for `${NAME}` in a YAML configuration (`-tv`, repeatable)
  -R, --recursion-depth <N>        Configuration `include` levels to follow [default: 1]
  -e, --interpret-escapes          Turn `\n`, `\r`, `\t` and `\\` in the title and body into the characters
  -T, --theme <THEME>              Image theme, the `{THEME}` of image URLs [default: default]
  -j, --interpret-emojis           Replace `:shortcode:` emoji in the title and body (a URL's `?emojis=no` still wins)
  -d, --dry-run                    Show what would be notified; send nothing
      --disable-async              Notify services one after another (`-Da`)
  -S, --storage-path <PATH>        Persistent storage directory [env: APPRISE_STORAGE_PATH=] [default: ~/.local/share/mercurio/cache]
      --storage-prune-days <N>     `storage prune` removes files older than N days (`-SPD`) [env: APPRISE_STORAGE_PRUNE_DAYS=] [default: 30]
      --storage-uid-length <N>     Characters of the URL ids naming persistent storage, at least 2 (`-SUL`) [env: APPRISE_STORAGE_UID_LENGTH=] [default: 8]
      --storage-mode <MODE>        When persistent storage is written: `auto` (after each send), `flush` (also before each step) or `memory` (never) (`-SM`) [default: auto]
  -l, --details                    Same as `mercurio services`
      --json                       With `services`: print JSON
      --bind <ADDR>                With `serve`: address to listen on [default: 127.0.0.1:8000]
  -v, --verbose...                 More log output on stderr (repeat for more)
  -h, --help                       Print help
  -V, --version                    Print version

Environment:
  APPRISE_URLS               URLs to notify when none are given and there is no -c
  APPRISE_CONFIG_PATH        configuration files instead of the defaults (separated by ; or newlines)
  APPRISE_TEMPLATE_<NAME>    value for ${NAME} when -tv and the configuration give none

Exit codes:
  0  every selected service was notified (or -d, check, services, storage succeeded)
  1  every selected service failed, or a source, attachment or stdin could not be read
  2  usage error, or no URLs given or configured
  3  services were loaded but none matched the tags (-g)
  4  some services were notified and some failed

Default configuration files (.yaml instead of .conf for YAML):
  ~/.config/apprise/apprise.conf
  /etc/apprise/apprise.conf

The short flags are the usual ones for notification tools: -t title, -b body, -n type, -c configuration, -g tag. Compatibility notes are in the README.

Sending

mercurio -t "Backup" -b "Finished in 42s" ntfy://my-topic "discord://ID/TOKEN"
echo "disk 91% full" | mercurio -n warning tgram://BOT_TOKEN/CHAT_ID
mercurio -c ~/alerts.yml -g devops -b "deploy done"

• Without -b, the body is read from standard input until end of file. A dry run (-d) does not read it.
• The title is optional. Services without a title field get it merged into the body (see Messages).
• All matching services are notified concurrently. -Da sends one after another.
• A word send before the URLs is accepted and ignored (mercurio send -b hi ntfy://topic).

Verbosity

Without -v only errors are printed; -v adds warnings (skipped configuration entries, retries), -vv informational messages, -vvv debug and -vvvv trace output. Log lines look like WARNING - ....

Where services come from

The first of these sources that gives anything is used; the rest are ignored:

1. URLs on the command line. When -c is also given, the URLs win and a warning is logged (visible with -v).
2. -c / --config files and URLs.
3. $APPRISE_URLS: URLs separated by commas or whitespace.
4. The default configuration files. Every one that exists is loaded.

Put a user configuration in ~/.config/apprise/apprise.conf and a system-wide one in /etc/apprise/apprise.conf (.yaml for YAML), the locations --help shows. For compatibility with older Apprise setups, every one of these is read, in this order ({a,b} is each of a and b, the empty entry meaning no extension):

~/.apprise{,.conf,.yml,.yaml}
~/.config/apprise{,.conf,.yml,.yaml}
~/.apprise/apprise{,.conf,.yml,.yaml}
~/.config/apprise/apprise{,.conf,.yml,.yaml}
/etc/apprise{,.yml,.yaml}
/etc/apprise/apprise{,.conf,.yml,.yaml}

On Windows they are Apprise\apprise{,.conf,.yml,.yaml} under %APPDATA%, %LOCALAPPDATA%, %ALLUSERSPROFILE%, %PROGRAMFILES% and %COMMONPROGRAMFILES%.

Directories are skipped. $APPRISE_CONFIG_PATH replaces the whole list (paths separated by ; or newlines).

The format of each file (TEXT or YAML) is detected; see Configuration files.

Tags and dry run

-g selects configuration entries by tag (Tags); URLs given on the command line are always notified without -g. With -g they are filtered by their ?tag= values. -d loads every source, applies the tags and prints what would be notified, without sending or reading a body:

$ mercurio -c alerts.yml -g all -d
   1. json://localhost:9/...
      tags: devops
   2. ntfys://ntfy.sh/...
      tags: critical, devops
   3. gotify://${GOTIFY_HOST}/...
       uid: - template; unresolved, would not send -
      tags: home
  template: gotify_host (required)

1 of 3 matched entries could not be resolved and would not be sent.

Sending to an unresolved entry fails it; entries that fail to load are skipped with a warning (-v shows them). See Templates.

Output is redacted to the scheme and host. For services whose token sits in the host position (tgram://BOT_TOKEN/...) the token is printed; do not paste dry-run or storage output of such URLs in public places.

URL check

mercurio check parses every URL or configuration entry and prints one line per service (ok ntfy:// (ntfy), error: ...), without applying tags. Exit code 1 when any URL or configuration source is invalid.

Available services

mercurio services lists the services compiled into the binary:

$ mercurio services
46elks                             46elks:// elks://
800.com                            eight00com://
Africas Talking                    atalk://
...

--json prints details for each service.

Exit codes

The exit codes are listed at the end of --help above.

A URL that fails to parse is reported and skipped; the other URLs are still notified. The exit code only counts them. Use check first to catch typos.

Environment variables

The ones the command line reads are in --help above. APPRISE_CONFIG_DIR, APPRISE_STATELESS_URLS and APPRISE_RECURSION_MAX are for mercurio serve only, see HTTP server.

Notification URLs

Main idea:

scheme://[user[:password]@]host[:port][/path/token/target...][?key=value&...]

Notification URLs are not RFC 3986 URLs: tokens may contain :, / or @. The path carries API keys and targets. The query string carries options. Each service page lists the forms it accepts and its parameters; the common parameters work on every URL.

Special characters

Percent-encode @ (%40), : (%3A), / (%2F), ? (%3F), & (%26), # (%23), % (%25) and space (%20) inside a password, token or target. json://user:p%40ss%2Fword@example.com/hook has the password p@ss/word. A + in a query value stays a + (%2B works too). YAML settings written under the URL (user:, password:, to:) need no encoding; the loader encodes them.

?user= and ?pass= (or ?password=) replace the credentials written before @. With ?user= alone, the value before @ becomes the password.

Prefixed parameters: +, - and :

Three query prefixes pass free-form data to services that read them (the custom json://, form:// and xml:// services and some others; their pages say which):

mercurio -b "hi" "json://localhost:8080/hook?+X-Token=abc&:message=text&:type="

form:// and xml:// differ in details (xml:// has no - parameters). Other services use : for template tokens or extra fields. For attachment URLs, + entries are headers only.

Vendor URLs

31 services accept the URL the vendor gives you, among them Discord, Slack, Power Automate workflows, Mattermost, Google Chat, Matrix, ntfy, Zoom, Splunk, IFTTT and Webex Teams. When the scheme is not a known service, each service’s vendor URL parser is tried in turn. The “Vendor URLs accepted” row of a service page says whether it does.

mercurio -b "hi" "https://discord.com/api/webhooks/1234567890/abcdefghijkl"

Validating URLs and secrets

mercurio check URL... parses URLs without sending; each invalid URL prints the reason and makes the exit code 1:

$ mercurio check "json://localhost/x" "unknown://x" "discord://only"
error: unknown://x/...: unsupported URL scheme: unknown://
error: discord://only/...: Discord: an invalid Discord Webhook Token was specified
ok   json:// (JSON)

Log lines, errors, check and --dry-run output show only the scheme and host (json://localhost:8080/...); a token in the host position (tgram://BOT_TOKEN/...) is therefore printed. In the library, Debug output of parsed URLs is redacted the same way. mercurio::redact_url gives the redacted form for your own logs.

Common URL parameters

These query parameters work on every URL. Service-specific parameters are on each service page. In YAML configuration they can also be written as settings under the URL.

Boolean values accept yes, true, on, 1, enable, allow and their opposites (no, false, off, 0, disable, deny, never), case-insensitive.

format

The caller declares the input format (mercurio -i markdown, Message::format); mercurio converts it to the service format. A service with one format uses ?format= if given, else its default. A service with several formats uses ?format= if it supports it, else the input format if it supports that, else its default (the first one on its page). See Formats and conversion.

verify, redirect, cto, rto

?verify=no disables certificate checks for that URL (self-signed servers); attachment URLs and HTTP configuration URLs accept it too. To trust a private CA instead, point SSL_CERT_FILE (or REQUESTS_CA_BUNDLE) at a PEM bundle: it replaces the bundled Mozilla roots for every connection, HTTP and socket services alike. The bundle is read once, at the first TLS connection; restart mercurio serve (or your program) after changing it.

Timeouts are decimal seconds (?cto=2.5). A value that is not a number greater than zero falls back to the default.

retry and wait

mercurio -b "disk full" "ntfy://alerts?retry=3&wait=2"

retry above 10 is capped and wait is clamped to 0–20 s. mercurio only repeats an attempt when repeating cannot deliver the message twice. Every error has an ErrorClass (mercurio::Error::class()):

• An attempt with several errors (one per target) is retried only when every error is RateLimited or Transient.
• Services that make several requests name the failing step first (login: HTTP 500: server error); the class is that of the underlying error.
• Retry-After is read as seconds or as an IMF-fixdate HTTP date. Longer than mercurio::service::MAX_RETRY_AFTER (300 s) ends the retries instead of blocking. A 429 without it waits wait; Discord uses its X-RateLimit-Reset instead.
• Targets and pieces of a split message that an earlier attempt delivered are skipped and reported as delivered. Some services track finer state (Slack channel ids and uploads, Matrix rooms, HumHub post ids, Opsgenie and Jira batches). This tracking lasts one notification and is not written to disk.
• -v logs each retry (WARNING - ntfy: attempt 1/4 failed; trying again). In the library each attempt is in ReportEntry::attempts.

store

?store=no keeps that URL’s state (login tokens, lookups, sessions) in memory, for as long as the target lives, even when a storage path is set.

tag

?tag=a,b tags a URL given on the command line, in APPRISE_URLS or in the library, so --tag / TagFilter can select it like a configuration entry. In a configuration file the values are added to the entry’s tags.

mercurio -g ops -b "on call" "ntfy://ops-alerts?tag=ops" "ntfy://everyone"   # only the first

Configuration files

A configuration file lists notification URLs once, with tags, so commands and programs only say which group to notify. Two formats share tags, include, groups and (YAML only) ${NAME} templates:

# ~/.config/apprise/apprise.yml
version: 1
urls:
  - ntfys://ntfy.example.com/alerts:
      tag: devops
  - mailtos://user:pass@example.com:
      to: oncall@example.com
      tag: devops, critical

# the same in TEXT: ~/.config/apprise/apprise.conf
devops=ntfys://ntfy.example.com/alerts
devops, critical=mailtos://user:pass@example.com?to=oncall@example.com

mercurio -g critical -b "Disk full"

The command line reads the default files when no URL, -c or APPRISE_URLS is given.

Sources

-c (repeatable) and include accept:

~ is expanded in paths. On a bare path ?format= becomes part of the file name. HTTP sources are fetched with POST; user:pass@ becomes Basic authentication, ?+Header=value adds a header and ?verify=no disables certificate checks.

Checking a configuration

mercurio check -c FILE loads the file and prints one line per service. The loader keeps the valid entries of a file and drops invalid ones with a warning, so a service that seems to be missing is explained by -v:

$ mercurio check -v -c alerts.yml
WARNING - Could not load URL discord://only-a-token/... (YAML entry #3, item #1): Discord: an invalid Discord Webhook Token was specified
ok   ntfys:// (ntfy) (template: host, topic)
ok   json:// (JSON) (template: topic)

mercurio -d -c FILE -g TAG applies the tag filter and template values and lists what would be notified, with each entry’s tags.

Limits

• A source larger than 128 KiB is rejected, includes too.
• Files must be UTF-8.
• A file that fails to parse as a whole (invalid YAML, a TEXT line that matches no rule) yields no services; the error is logged.

The same loader is mercurio::Config and Mercurio::add_config in the library.

TEXT format

One entry per line:

# Lines starting with # or ; are comments
; this too

# Untagged: notified when mercurio runs without --tag
json://localhost:8080/untagged

# One or more tags before '=' (separated by commas and/or spaces)
devops=ntfy://ntfy.example.com/alerts
devops, critical=mailtos://user:pass@example.com?to=oncall@example.com
family kitchen=kodi://user:pass@kitchen.local

# Groups: name = tags (a group may contain other groups)
team = devops, family
everyone = team, critical

include /etc/apprise/extra.conf

• A URL starts with a scheme of 1 to 32 letters or digits followed by ://; the rest of the line, trimmed, is the URL. Line endings may be \n or \r\n.
• Tags are letters, digits, _, - and :, lower-cased. A trailing :N (a retry count, ops:3) rejects the tag and its line’s URL with a warning; use ?retry=3. A leading N: (2:ops) is a priority.
• One line that matches no rule invalidates the whole file (ERROR - Invalid TEXT configuration format found on line 2.).
• A URL that does not parse or that its service rejects is skipped with a warning; the other lines still load.

Groups

name = tag1, tag2 gives every entry carrying tag1 or tag2 the extra tag name. Groups may name groups (expanded recursively). A group listed twice adds to its members. Group lines can appear anywhere. With the example above mercurio -d -c alerts.txt -g team selects the ntfy, mailtos and kodi entries, each with team and everyone among its tags. See Tags.

What TEXT cannot express

Every service setting fits in the URL’s query string, so TEXT can configure every service. It lacks YAML’s settings written outside the URL (no percent-encoding), one URL expanded into several services, file-wide tags, asset: overrides and ${NAME} templates.

YAML format

YAML adds what one-line URLs cannot express: settings written next to the URL, several services from one URL, file-wide tags, asset overrides and ${NAME} templates.

version: 1

# Tags added to every URL in this file
tag: home

asset:
  app_id: Backup Bot

groups:
  oncall: devops, critical

urls:
  # A plain URL
  - json://localhost:8080/plain

  # A URL with settings: each key becomes ?key=value
  - ntfys://ntfy.example.com/alerts:
      tag: devops
      priority: high
      format: markdown

  # A list under one URL creates one service per entry
  - mailtos://user:pass@example.com:
      - to: oncall@example.com
        tag: critical
      - to: boss@example.com
        tag: always
        name: Backup Bot

  # Header and payload groups
  - json://localhost:8080/hook:
      tag: devops
      headers:
        X-Token: abc123
      payload:
        message: text

Top-level keys

Other top-level keys are ignored, which makes them a convenient place for YAML anchors (see Anchors).

A file-wide tag: tags every entry, so nothing in that file is notified when mercurio runs without --tag (only untagged entries are). The example above prints no URLs matched the given tags (exit code 3) without -g.

The urls list

Each item is a URL string, a URL with a mapping of settings (one service) or a URL with a list of mappings (one service per item, each with its own settings: one account, several recipients). A URL with nothing after the colon is the plain string form.

How settings are applied

Settings are folded into the URL’s query string, so any parameter of a service page or the common parameters can be written as a setting.

Rules:

• A setting overrides the same parameter written in the URL.
• Writing any + setting (or headers:) replaces all the URL’s own + parameters; the same holds for - (params:) and : (payload:).
• user and password also replace ?user= / ?pass= in the URL.
• Keys must start with a letter or digit (or one of the prefixes). Other keys are ignored with a warning. So is a mapping given as the value of an ordinary key.

Because the loader encodes values, credentials with @, / or : need no escaping. Settings can also complete a URL that does not parse on its own:

urls:
  - json://:
      host: localhost
      port: 8080
      user: bob
      password: "p@ss/word"

Groups

groups:
  oncall: devops, critical
  everyone: [oncall, family]     # groups can contain groups

A list of single-key mappings works too. Naming a group again adds to it. See Tags.

Anchors, aliases and merge keys

Anchors (&name), aliases (*name) and merge keys (<<) work as in YAML 1.1. Merged keys come first and the mapping’s own keys override them.

version: 1
defaults: &defaults
  tag: ops
  format: markdown
urls:
  - json://localhost/hook:
      <<: *defaults
      headers:
        X-Token: abc
  - ntfy://alerts:
      <<: *defaults
      priority: high

Scalars

Values are read with YAML 1.1 rules:

• yes, no, on, off, true, false are booleans (and become yes / no in the URL). Quote them to keep them as text.
• Octal (0755), hex (0x1F), binary and sexagesimal (1:30) integers are numbers. Quote values such as phone numbers or IDs with leading zeros: to: "0711234567".
• ~ and null are null.

Tags

Tags are case-insensitive (stored lower-cased), made of letters, digits, _ and -; duplicates are removed. In a configuration file, ?tag= values are added to the entry’s tags.

Selecting services on the command line

• all as a filter matches everything; do not use it as a tag name.
• Services tagged always join every tagged run (any -g), not the run without -g.
• When nothing matches, mercurio prints no URLs matched the given tags and exits with code 3.
• The library’s TagFilter::parse("a,b") and the HTTP server’s tag=a,b mean a or b; the server’s tag=a b means both. See Using the library.

Groups

A group is a tag that stands for other tags (TEXT group = tag1, tag2, YAML groups:). Every entry with a member tag also gets the group name, so -g group selects them all. Groups may contain groups (expanded recursively, loops ignored). Assigning to an existing group adds members. mercurio -d shows each entry’s expanded tags:

version: 1
groups:
  - oncall: devops, critical
  - oncall: database
urls:
  - json://localhost/a:
      tag: database
  - json://localhost/c:
      tag: always
  - json://localhost/d

$ mercurio -d -c tags.yml -g oncall
   1. json://localhost/...
      tags: database, oncall
   2. json://localhost/...
      tags: always

Priorities

A tag may carry a priority prefix, 2:ops (no prefix is priority 0, the most urgent). A plain filter (-g ops) escalates, as in Apprise:

1. The services matched through ops are grouped by the priority of their ops tag.
2. The most urgent group is sent first. When all of it delivers, the others are not sent at all.
3. When one of its services fails, the next group is sent, and so on.
4. The call succeeds once a group delivers; the failures before it are still reported (ReportEntry::escalated in the library).

Each single-tag alternative (-g ops -g db, tag=ops, db) is its own chain: chains escalate independently and their groups go out together. Services matched otherwise (an AND group such as -g "ops,eu", or always) share one more chain. A filter with a priority (-g 2:ops) matches only services whose ops tag has priority 2 and sends them all at once, without escalation.

A filter’s retry suffix (-g ops:3) sets the number of retries of the services it matches, instead of their ?retry= (at most 10). In configuration files a tag with one (ops:3) is rejected.

Includes

A configuration can pull in other sources, to share services between machines or keep secrets in a file with tighter permissions.

include /etc/apprise/shared.yml
include secrets.conf
include https://config.example.com/get/team
critical=json://localhost:9000/local

version: 1
include:              # or a single string
  - /etc/apprise/shared.yml
  - secrets.conf
urls:
  - json://localhost:9000/local

Each included source has its own format, detected as for -c (Sources). The including file’s services load first, then each include’s, in the order written.

memory:// and any other scheme are skipped with a warning.

Depth

Includes are followed to a limited depth, so loops end. Includes inside an included file count against the same depth.

Which source may include which

Local files may include anything. HTTP sources and in-memory sources (library Config::from_text, configurations stored on the server) may only include HTTP(S) sources, so a remote configuration server cannot make the loader read local files. A forbidden include is skipped with a warning (Including file:// based configuration is prohibited. Ignoring URL file:///...). The library can lift this with ConfigOptions::insecure_includes; the CLI cannot.

Every included source has the same 128 KiB limit. Asset overrides from an included YAML file apply to all services of the load.

Templates

A YAML configuration can leave parts of its URLs open as ${NAME} variables, filled when a notification is sent. In TEXT files ${NAME} is plain text.

version: 1
template:
  - host: ntfy.sh      # has a default
  - topic              # required
urls:
  - ntfys://${HOST}/${TOPIC}:
      tag: alerts
  - json://localhost:8080/${TOPIC}

mercurio -c tmpl.yml -g all -tv topic=backups -b "done"
APPRISE_TEMPLATE_TOPIC=backups mercurio -c tmpl.yml -g alerts -b "done"

Declaring variables

template: is a list (as above) or a mapping (topic: ~ for required, host: ntfy.sh for a default).

• Names are 1 to 32 letters, digits or _, case-insensitive: ${host}, ${HOST} and -tv Host=... are the same variable.
• A default is text, a number or a boolean.
• A name declared twice, an invalid name or an invalid default rejects the whole file.
• Only declared names are replaced; an undeclared ${OTHER} stays as written.

Where values come from

The first available value wins:

1. -tv NAME=VALUE (--template-var, repeatable), TemplateVars in the library or the server request’s template field.
2. The default in template:.
3. APPRISE_TEMPLATE_NAME in the environment (the name in upper case).

An empty value counts as not given. A value may be at most 1,024 characters without control characters; the URL after substitution at most 8,192. -tv without =, with an invalid name or naming a variable twice ends the command with exit code 2; the error shows the name, never the value.

Pending entries

An entry with variables is parsed at load time and kept pending until a notification supplies the values. check marks it (ok json:// (JSON) (template: topic)). A dry run shows what is missing:

$ mercurio -d -g all -c tmpl.yml
   1. ntfys://${HOST}/...
       uid: - template; unresolved, would not send -
      tags: alerts
  template: host (has default), topic (required)
   2. json://localhost:8080/...
       uid: - template; unresolved, would not send -
  template: topic (required)

2 of 2 matched entries could not be resolved and would not be sent.

At send time an entry whose variables cannot all be resolved fails in the report; the others are sent.

Where variables may appear

Values go into the parsed URL field they were written in, after parsing. A value in the host cannot add a path or a query. A / or @ in a value does not change the URL’s structure. A host value may carry a port (example.com:8080) when the URL has none.

Asset overrides

The asset is the application identity shared by all services: the name sent as User-Agent and sender, the description and URL some services show, the per-type images and where persistent state is kept. A YAML configuration can override it (TEXT files cannot):

version: 1
asset:
  app_id: Backup Bot
  image_url_mask: https://img.example.com/{THEME}/{TYPE}-{XY}{EXTENSION}
  storage_path: ~/.cache/backup-bot
urls:
  - json://localhost:8080/hook

timezone (or tz) sets the zone of the dates services write (e-mail Date:, syslog) for URLs without ?tz=: an IANA name, any case, or the location alone (paris). An unknown zone is ignored with a warning (Ignored invalid timezone "...").

Keys without effect

Accepted without effect: image_path_logo, encoding, async_mode, interpret_escapes, abort_on_chain_failure, pem_autogen, secure_logging, http_redirects, lang, language, timezone, tz. Use -e, -Da or ?redirect=no for what some of them control. Keys starting or ending with _ are ignored with a warning; unknown keys (including interpret_emojis, storage_mode, storage_salt, storage_idlen) and values of the wrong type are rejected with a warning (WARNING - Invalid asset key "storage_mode"., visible with mercurio check -v).

Scope

• The overrides apply to every service of that configuration and its includes; when several files of one load set a key, the last one read wins.
• They do not affect other -c sources or URLs on the command line.
• They override the CLI’s --storage-path and the library’s Asset for those services. They only take effect when they set at least one key from the table.
• In the library, Config::asset_for(&base) returns the asset a configuration applies on top of base.

Messages

A notification is a title, a body, a type, an optional input format and optional attachments. Each selected service gets its own copy shaped to its limits and markup.

A message needs a body or at least one attachment; a body-less message fails for services without attachment support.

Services use the type where they have a notion of it: embed colour, icon images, priority or the type field of json://, form:// and xml://. Colours, markers and image URLs come from the asset. Services that send images honour ?image=no.

-e turns \n, \r, \t and \\ in the CLI’s title and body into the characters they stand for (mercurio -e -b 'sda: 91%\nsdb: 40%' ...); other escapes stay as written. The library does not decode escapes.

:shortcode: emoji (:rocket:, :+1:: GitHub’s gemoji names, case-insensitive) become the emoji itself when emoji are on for a URL:

• -j / --interpret-emojis (CLI), APPRISE_INTERPRET_EMOJIS=yes (server) or Asset::interpret_emojis = Some(true) (library) turn them on for every URL, unless a URL says ?emojis=no;
• without those, a URL can turn them on with ?emojis=yes;
• APPRISE_INTERPRET_EMOJIS=no or Some(false) turns them off everywhere.

Unknown names stay as written. The replacement happens before format conversion, in the title and the body.

The pipeline

Every service receives the message through the same steps:

1. Format resolution: input format from the message, else Asset::body_format, else none (passthrough); service format as in ?format=.
2. Conversion of the body to the service format. The title is converted too when the service has no title field. Passthrough messages are not converted.
3. Limits: the service’s limits or limits computed for this message (Matrix sizes them from the rendered content).
4. Title merge: services without a title field (title_maxlen 0) get the title prepended: <b>title</b><br /> for HTML, # title for Markdown, title\r\n for text.
5. Line cap: services with a line limit keep the first N lines.
6. Overflow: upstream, truncate or split (Overflow).
7. Dialect conversion: services with their own markup convert each piece of a declared-format message; pieces that grow past the limit are split again (Formats).
8. Attachments go with the first piece; with overflow=truncate only the first attachment is sent.

Services also see the original Message next to each piece (Telegram rich templates build their payload from it). Target::plan runs the pipeline for the first piece and returns the plan without sending.

Formats and conversion

The input format is what the caller says the body is written in (-i, the server’s format field, Message::format). The service format is what the service renders (its default or ?format=). When they differ, mercurio converts the body. With no input format declared nothing is converted: the body passes through as the service’s own format.

The CLI and the HTTP server declare none unless -i or format is given; the library uses Message::format, else Asset::body_format.

Conversion table

For services without a title field, the title is converted the same way and merged into the body (see the pipeline).

Service formats

Each service declares its formats, the first being its default; the service pages list them under “Body formats”. Most services are text only; e-mail and the mail APIs default to HTML; Slack, Google Chat, Webex Teams, Rocket.Chat and others take Markdown. ?format= picks one (resolution rules). Markdown input to a text-only service is sent unchanged.

Dialects

Some services have their own markup and convert each piece after the generic conversion (Notify::convert):

Dialect conversion only runs for a declared input format. Because the converted text can be longer, size limits are applied again: with overflow=split the converted piece is re-split, with truncate it is cut to fit.

Markdown rendering

Markdown is rendered with pulldown-cmark (CommonMark plus GFM tables); HTML to text and HTML to Markdown use a small HTML tokenizer. When a split cuts Markdown, mercurio repairs unclosed emphasis, code fences and link syntax.

Overflow

Most services limit how long a title or body can be. ?overflow= on a URL says what to do with a message that does not fit:

mercurio -b "$(cat build.log)" 'tgram://BOT_TOKEN/CHAT_ID?overflow=split'
mercurio -b "$(cat build.log)" 'ntfy://builds?overflow=truncate'

split can turn one long message into many. On SMS and other paid channels every piece may be billed.

Limits

Each service has three limits, shown on its page:

Limits count Unicode code points, not bytes. A few services size their limit from the content (Matrix, after rendering HTML). The line cap applies in every overflow mode, including upstream.

How truncate works

The title is cut to title_maxlen characters. The body is cut the way split would cut it. Only the first piece is kept. Leading line breaks and trailing whitespace of the result are removed. For Markdown a trailing lone backslash, which would escape whatever the service appends, is dropped. With truncate and several attachments only the first attachment is sent.

How split works

The body is cut into pieces of at most body_maxlen characters, looking for the best break before the limit, in this order:

1. a newline;
2. a space or tab;
3. punctuation followed by whitespace;
4. a hard cut at the limit.

For HTML it never cuts inside a tag or an entity; for Markdown it does not cut inside a link or an escape and repairs emphasis and code fences that a cut leaves open.

Only the first piece carries the title; the others are sent without one. No [01/03] counters are added.

Services with a dialect convert each piece and split again if the converted text grew past the limit.

Attachments

Files can go with a notification to services that support them: e-mail, Discord, Slack, Telegram, Matrix, Pushover, ntfy, the json://, form:// and xml:// webhooks and many more. The services index has an “Attachments” column and every service page says yes or no. A service without attachment support still gets the text of the message; a message with attachments but no body fails for such a service.

Sources

Remote files are downloaded through the notifier’s transport before sending, so FakeTransport covers them in tests and a custom transport applies to them. Credentials in the URL authenticate the download; treat such URLs as secrets.

URL options

Without ?name=, the name comes from the Content-Disposition header, then the URL path, then mercurio-attachment.<ext> (the extension guessed from the MIME type). Without ?mime=, the type comes from the Content-Type header, then the file extension, then application/octet-stream.

Size limit

Asset::attachment_max_size caps each attachment: 1000 MiB by default, 0 for no limit. The check uses the file size, the Content-Length header and the downloaded body.

Command line

mercurio -t 'Nightly backup' -b 'See the log' \
  -a /var/log/backup.log \
  -a 'https://example.com/report?id=7&name=report.pdf' \
  'mailto://user:pass@example.com'

-a is repeatable. A file that cannot be loaded is an error before anything is sent.

The HTTP server accepts multipart file parts and attach fields holding http(s):// URLs; a local path or file:// is rejected with HTTP 400, so clients cannot read files on the server.

Library

Message::attach takes an in-memory Attachment (name, MIME type, bytes). AttachmentSet parses the sources above and loads them:

#![allow(unused)]
fn main() {
use mercurio::testing::FakeTransport;
use mercurio::{attachment::AttachSource, AttachmentSet, Asset, Attachment, Message, transport::Response};

let fake = FakeTransport::new();
fake.respond_with(Response::new(200, "a,b\n1,2\n").with_header("Content-Type", "text/csv"));

let mut set = AttachmentSet::new();
set.add("https://example.com/export?id=7&name=readings.csv")?;
set.push(AttachSource::text("generated in memory", Some("notes.txt")))?;

let mut msg = Message::new("Nightly export")
    .attach(Attachment::new("hello.bin", "application/octet-stream", vec![1, 2, 3]));
msg.attachments.extend(set.load(&fake, &Asset::default())?);

let names: Vec<&str> = msg.attachments.iter().map(|a| a.name.as_str()).collect();
assert_eq!(names, ["hello.bin", "readings.csv", "notes.txt"]);
assert_eq!(msg.attachments[1].mime, "text/csv");
// `name=` is an option, not part of the download URL.
assert_eq!(fake.requests()[0].url, "https://example.com/export?id=7");
Ok::<(), mercurio::Error>(())
}

Loading stops at the first failure.

When a message is split, the attachments go with the first piece; with overflow=truncate only the first attachment is sent.

Persistent storage

Some services keep state between notifications (an OAuth token, a login session, a channel lookup) in a small key/value store per URL, so the next notification does not log in or look things up again:

Other services write nothing to disk.

Where it lives

The command line uses persistent storage by default:

Each URL gets a namespace directory named after its URL id:

<storage path>/<url id>/cache.json   the entries of this namespace
<storage path>/<url id>/tmp/         staging area for atomic writes
<storage path>/<url id>/var/         service files (Vapid keys and subscriptions)

cache.json maps each key to {"v": value, "x": expiry} (the expiry in Unix seconds or null). The file is read before a URL’s first notification and rewritten when it changed, as the storage mode says (--storage-mode / -SM, APPRISE_STORAGE_MODE for the server, Asset::storage_mode in the library):

• auto (default): once a notification is over;
• flush: also before each request or connection of a notification, so a send cut short keeps what it saved (a token from a login step);
• memory: never; the store lives in memory even with a storage path.

Directories are created on the first write with mode 0700, files with 0600. Files are written to tmp/ and renamed into place. A file that is not valid JSON is removed with a warning. When no saved entry is left, cache.json is deleted.

Services can also keep a value in memory only (an access token, for example): such entries are never written and live as long as the target.

Without a storage path (the library default) every store is in memory. So are the stores of URLs with ?store=no or of services that opt out of URL ids.

URL ids

The namespace is named by a URL id: a SHA-256 hash of the parts that identify the account (scheme, user, password, host, port, path and the secure flag), cut to 8 hexadecimal characters by default. Two URLs that differ only in options share a namespace. Some services hash their own parts instead (for example only the bot token for Telegram).

--storage-uid-length N (-SUL, APPRISE_STORAGE_UID_LENGTH, at least 2; the server accepts 2 to 64) keeps N characters instead, which moves every URL to a new namespace. In the library, Asset::storage_idlen (0 keeps all 64) and Asset::storage_salt (bytes hashed first) work like Apprise’s storage_idlen and storage_salt, so the ids match Apprise’s for the same settings.

?store=no keeps a URL’s store in memory even when a storage path is set.

mercurio storage

mercurio storage [list|prune|clear] [UID-prefix...|URL...] [-S PATH] [-c CONFIG] [-g TAG] [-d]

The action may be abbreviated (l, p, c); clean is accepted for clear. list is the default.

• list: URL ids of the configured services (from URLs on the command line, -c, $APPRISE_URLS or the default configuration files) next to what is on disk. Each row shows the size and a state: active (on disk and configured), unused (configured, nothing stored yet), stale (on disk, not configured; only shown when no -g is given).
• prune: remove store files not modified for -SPD days (default 30).
• clear: remove every store file.

Arguments containing :// select URLs; other arguments are URL id prefixes. -g restricts the action to tagged configuration entries. -d shows what prune or clear would remove without removing it. Empty namespace directories are removed after a prune.

$ mercurio storage -S /tmp/demo/store "json://localhost/hook?tag=ci"
   1. e058d7a2                                             0.00B    unused
      - json://localhost/...
      tags: ci

$ mercurio storage prune -d -S /tmp/demo/store
abcdef12: would remove /tmp/demo/store/abcdef12/cache.json

Prune and clear only remove mercurio’s own files; other files in a namespace directory are left alone.

In the library

Mercurio::new() keeps stores in memory. Give the Asset a storage path to persist them:

#![allow(unused)]
fn main() {
use mercurio::{Asset, Mercurio};

let dir = std::env::temp_dir().join("mercurio-book-storage");
let mut m = Mercurio::new().asset(Asset::default().with_storage(&dir));
m.add("json://example.com/hook")?;
Ok::<(), mercurio::Error>(())
}

A YAML configuration can set the path under asset: (storage_path, a mercurio extension, see Asset overrides). Each ReportEntry carries the url_id of its target.

mercurio::store::PersistentStore is usable on its own; services read their namespace as Context::store.

HTTP server

mercurio serve runs an HTTP notification API in the same binary. Clients send a message to the URLs in the request (stateless) or to a configuration stored on the server under a key (stateful). There is no web UI.

mercurio serve                          # listens on 127.0.0.1:8000
mercurio serve --bind 0.0.0.0:8000 -v   # all interfaces, warnings too

There is no TLS: bind to localhost or put a reverse proxy in front. Turn on authentication before exposing it. The install page has a container image and a systemd unit.

Settings

Every setting is a flag of mercurio serve and an environment variable (named as in apprise-api); the flag wins. Boolean values are true when they start with y, t, 1, e, a or +. --bind ADDR (default 127.0.0.1:8000) sets the listen address. From mercurio serve --help:

      --config-dir <DIR>               Where stored configurations are kept (relative to the working directory) [env: APPRISE_CONFIG_DIR=] [default: mercurio-config]
      --stateful-mode <MODE>           `hash`, `simple` or `disabled`: layout of stored configurations [env: APPRISE_STATEFUL_MODE=] [default: hash]
      --secret-key <KEY>               Salt of `hash` file names [default: built-in] [env: SECRET_KEY]
      --stateless-mode <YES|NO>        `no` refuses stateless `POST /notify` [env: APPRISE_STATELESS_MODE=] [default: yes]
      --stateless-urls <URLS>          URLs used by `POST /notify` when the request gives none [env: APPRISE_STATELESS_URLS]
      --config-lock <YES|NO>           Hide configuration content and management from everyone but the administrator [env: APPRISE_CONFIG_LOCK=] [default: no]
      --admin <YES|NO>                 Offer the `GET /cfg` key list (`simple` mode only) [env: APPRISE_ADMIN=] [default: yes]
      --config-max-length <KIB>        Largest `config` accepted by `/add`, in KiB [env: APPRISE_CONFIG_MAX_LENGTH=] [default: 512]
      --upload-max-memory-size <MIB>   Upper bound of `--config-max-length`, in MiB [env: APPRISE_UPLOAD_MAX_MEMORY_SIZE=] [default: 3]
      --recursion-max <N>              `include` levels followed, and the highest `X-Apprise-Recursion-Count` accepted [env: APPRISE_RECURSION_MAX=] [default: 1]
      --allow-templates <YES|NO>       Honour `template:` sections and `${NAME}` markers [env: APPRISE_ALLOW_TEMPLATES=] [default: yes]
      --default-format <FORMAT>        `text`, `html` or `markdown` for requests without `format` [env: APPRISE_DEFAULT_FORMAT=]
      --deny-services <LIST>           Services that can not be used (one scheme names the whole service) [env: APPRISE_DENY_SERVICES=] [default: windows,dbus,gnome,macosx,syslog]
      --allow-services <LIST>          When set, the only services that can be used (the deny list is ignored) [env: APPRISE_ALLOW_SERVICES=]
      --attach-size <MIB>              Largest attachment in MiB; `0` turns attachments off [env: APPRISE_ATTACH_SIZE=] [default: 200]
      --max-attachments <N>            Attachments per request; `0` means no limit [env: APPRISE_MAX_ATTACHMENTS=] [default: 6]
      --attach-allow-url <PATTERNS>    Attachment URLs that may be downloaded [env: APPRISE_ATTACH_ALLOW_URL=] [default: *]
      --attach-reject-url <PATTERNS>   Attachment URLs that are always refused (checked first) [env: APPRISE_ATTACH_REJECT_URL=] [default: "127.0.* localhost*"]
      --webhook-mapping-max-depth <N>  Deepest nested path a `?:a.b=dest` mapping rule may read [env: APPRISE_WEBHOOK_MAPPING_MAX_DEPTH=] [default: 5]
      --webhook-url <URL>              `http(s)://` URL that receives the result of every notification [env: APPRISE_WEBHOOK_URL]
      --storage-dir <DIR>              Persistent storage for services (tokens, sessions) [default: CONFIG_DIR/store] [env: APPRISE_STORAGE_DIR=]
      --storage-mode <MODE>            `auto` or `flush` write to the storage directory; `memory` keeps nothing [env: APPRISE_STORAGE_MODE=] [default: auto]
      --stateless-storage <YES|NO>     Stateless sends use persistent storage too [env: APPRISE_STATELESS_STORAGE=] [default: no]
      --log-level <LEVEL>              Default detail of returned logs [env: LOG_LEVEL=] [default: INFO]
      --log-format <FORMAT>            Server log on stderr: `text`, or `json` for one JSON object per line [env: LOG_FORMAT=] [default: text] [possible values: text, json]
      --http-redirects <YES|NO>        `no` stops following HTTP redirects for URLs without `?redirect=` [env: APPRISE_HTTP_REDIRECTS=] [default: yes]
      --prune-enabled <YES|NO>         `no` turns off the daily clean-up of old persistent storage and unused logins [env: APPRISE_PRUNE_ENABLED=] [default: yes]
      --prune-interval-seconds <N>     Seconds between clean-ups (at least 2; the first runs at start-up) [env: APPRISE_PRUNE_INTERVAL_SECONDS=] [default: 86400]
      --prune-timeout-seconds <N>      Longest a clean-up may run, in seconds (kept below the interval) [env: APPRISE_PRUNE_TIMEOUT_SECONDS=] [default: 28800]
      --auth-prune-seconds <N>         Age in seconds after which a login without a configuration is removed [env: APPRISE_AUTH_PRUNE_SECONDS=] [default: 2592000]
      --emojis <YES|NO>                `yes` replaces `:shortcode:` emoji unless a URL says `?emojis=no` (also `-j`); `no` never does; unset lets each URL decide [env: APPRISE_INTERPRET_EMOJIS=]
      --stream-worker-count <N>        Live streams sending at the same time [env: APPRISE_STREAM_WORKER_COUNT=] [default: 4]
      --worker-count <N>               Workers: each takes 128 requests in progress at once, more get `503` [env: APPRISE_WORKER_COUNT=] [default: 4]
      --worker-timeout <SECONDS>       Seconds a request head, and each piece of its body, may take to arrive [env: APPRISE_WORKER_TIMEOUT=] [default: 30]
      --stream-queue-size <N>          Further live streams admitted; more get `503` [env: APPRISE_STREAM_QUEUE_SIZE=] [default: 8]
      --auth-required <YES|NO>         Turn on Basic Auth [env: APPRISE_AUTH_REQUIRED=] [default: no]
      --user <NAME>                    Administrator user name (may be empty) [env: APPRISE_USER=]
      --password <PASSWORD>            Administrator password; enables the administrator login [env: APPRISE_PASSWORD]
      --basic-auth-realm <REALM>       Realm shown in login prompts [env: APPRISE_BASIC_AUTH_REALM=] [default: "Mercurio API"]

URL and host rules (APPRISE_ATTACH_*_URL) are separated by spaces or commas. A rule is a host (*.example.com, cdn.net:8080), a URL with an optional path prefix (https://example.com/files/, example.com/files/), or internal for every address that is not public (loopback, private, link-local). * matches any run of characters, ? one.

Limits: a request body up to APPRISE_ATTACH_SIZE plus 1 MiB (at least 8 MiB; 413 beyond), 256 MiB of request bodies being read at once (a request is charged its Content-Length, 1 MiB when it has none; more get 503 with Retry-After: 1), APPRISE_WORKER_COUNT times 128 requests in progress (512 by default; more get 503 with Retry-After: 1). A request head, and each piece of a body, must arrive within APPRISE_WORKER_TIMEOUT seconds (30 by default).

Request log

Every request is one line on stderr, with the fields that apply:

2026-10-20T13:53:41.630353Z  INFO request: method="POST" route="/notify/{key}" status=424 duration_ms=35.555 remote=127.0.0.1 key="k1" apprise_id="chain-1" bytes_in=41 services=2 failed=1 error="One or more notification could not be sent" detail="skipped bogus://x/...: unsupported URL scheme: bogus://"

route is the matched path (absent for a 404), key the Config ID used, services and failed count the services notified, error is the message of an error answer and detail lists problems that did not fail the request. A live stream logs stream=true; its results are not in the line. A /status or /metrics request that succeeds (the container’s health check, a metrics scrape) is not logged. -v adds warnings, -vv everything at INFO, -vvv debug output.

--log-format json (LOG_FORMAT=json) writes one JSON object per line instead, with the same fields as keys, for log collectors:

{"timestamp":"2026-10-20T13:53:41.630353Z","level":"INFO","method":"POST","route":"/notify/{key}","status":424,"duration_ms":"35.555","remote":"127.0.0.1","key":"k1","services":2,"failed":1,"error":"One or more notification could not be sent","target":"request"}

Endpoints

  /status, /status/{key}   GET                health check: OK or the problems found (JSON with Accept: application/json)
  /details                 GET                supported services as JSON; ?all=yes includes disabled ones
  /metrics                 GET                request counters in the Prometheus text format
  /notify                  POST               stateless: send to the URLs in the request
  /notify/{key}            POST               send through the stored configuration
  /add/{key}               POST               store a configuration
  /get/{key}, /cfg/{key}   POST               return the stored configuration
  /del/{key}               POST               delete the stored configuration (and its login)
  /move/{key}              POST               move a configuration and its login to the free key `to`
  /json/urls/{key}         GET                the stored URLs, their tags and template names
  /cfg                     GET                the stored keys (simple mode)
  /auth/{key}              GET, POST, DELETE  read, set or remove the key's login

Keys are 1 to 128 letters, digits, _ or -; a path with any other key is 404. Paths work with or without a trailing slash. A known path with the wrong method returns 405 with an Allow header.

/details describes each service as Apprise’s details() does: URL templates, tokens, args and kwargs, plus a setup_url that links to its page in this book.

/add, /get, /del, /move, /json/urls and /auth also work without the key in the path: send it in an X-Apprise-Config-ID header instead, which keeps it out of access logs. The header wins over a key in the path; an invalid header is 400.

Requests

Every POST accepts form fields (application/x-www-form-urlencoded), a JSON object (Content-Type: application/json) or multipart/form-data (text parts are fields, file parts attachments).

  urls                              /notify, /add  URLs separated by commas or whitespace; a JSON list works too
  body                              notify         message body; required unless there is an attachment
  title                             notify         message title
  type                              notify         info (default), success, warning, failure
  format                            notify         input format: text, html, markdown
  tag, tags                         notify         tag expression
  template                          notify         ${NAME} values: a JSON object, template[name]=value fields or NAME=VALUE strings
  attach, attachment, attachments   notify         http(s):// URLs to download; in JSON also {url, filename} or {base64, filename} objects
  config                            /add           TEXT or YAML configuration
  format                            /add           text, yaml, or empty / auto to detect
  to (JSON), from + to (form)       /move          destination key (form: also the source)

Plain text bodies

A notification can also be the whole request body. The content type sets its format: text/plain, text/html or text/markdown; ?format= wins.

curl -X POST -H 'Content-Type: text/plain' -H 'X-Apprise-Tag: devops' \
    --data-raw 'Deployment completed' http://127.0.0.1:8000/notify/demo

Headers

  X-Apprise-Title            the title
  X-Apprise-Type             the type
  X-Apprise-Tag              the tag expression
  X-Apprise-Template         template values as URL-encoded pairs (api_key=abc&room=ops)
  X-Apprise-Config-ID        the key, instead of the path (kept out of access logs)
  X-Apprise-Log-Level        detail of the returned logs: trace, debug, info, warning, error, critical
  X-Apprise-Recursion-Count  servers this call already went through; above --recursion-max is 406
  X-Apprise-ID               id of the call chain, passed on by apprise:// targets

When a field comes from several places, the first found wins: the payload, then the header, then the query string (?title=, ?type=, ?format=, ?tag=). Header values must be ASCII.

Field mapping

Query parameters starting with : rename payload fields before they are read, for senders that can not use these names:

curl -X POST -H 'Content-Type: application/json' \
    -d '{"subject": "CPU", "event": {"state": "critical"}}' \
    'http://127.0.0.1:8000/notify/demo?:subject=title&:event.state=body'

Alertmanager and Grafana webhooks

A JSON payload with an alerts list and a status, and no body, is read as an Alertmanager or Grafana webhook, so either can post straight to /notify/{key} (or to /notify with urls):

A type (or title, body) in the payload, the query or an X-Apprise-* header still wins, and ?tag= picks the stored entries as usual:

# alertmanager.yml
receivers:
  - name: mercurio
    webhook_configs:
      - url: http://127.0.0.1:8000/notify/ops?tag=oncall

Tags

Entries tagged always are included whenever a tag is given. A JSON list is a list of alternatives; a nested list is an AND group. Characters other than letters, digits, _, -, : and the separators are 400.

Attachments

Multipart file parts become attachments (type from the part, else the file name). URLs are downloaded by the server after the URL rules allow them; anything that is not http(s):// (a server-local path, file://) is refused, so clients can never read files on the server. Any problem with an attachment is 400 Bad Attachment (the reason is logged).

Responses

The response format follows Accept, and, without one (or with */*), the request’s content type:

• JSON (application/json): errors are {"error": "..."}; successes of /add, /del, /move are {"error": null};
• otherwise plain text.

Notifications answer with their log: the library’s own lines for this request (DEBUG - -> HTTP 200, WARNING - ..., URLs redacted) and one line per service (2026-10-17 12:00:00,000 - INFO - Sent json:// (JSON) notification.), in the order they happened and at or above the request’s log level (X-Apprise-Log-Level, default LOG_LEVEL); a JSON failure is {"error":"One or more notifications could not be sent","details":[[level, time, message], ...]}. With Accept: text/html the log is an HTML list (<ul class="logs">).

Live progress

?stream=yes or Accept: text/event-stream answers with server-sent events while sending: a log event per log line as it happens (the same lines as above), : heartbeat comments every 15 s while waiting and one final result event.

: connected

event: log
data: {"asctime":"2026-10-17 12:00:00,000","level":"INFO","message":"Sent json:// (JSON) notification.","service":"json"}

event: result
data: {"status":"SUCCESS"}

The status is SUCCESS, PARTIAL, FAILURE, NOMATCH or TIMEOUT. Streams beyond the stream limits get 503 with Retry-After: 15.

Result webhook

With APPRISE_WEBHOOK_URL, every notification POSTs {"source": "<client address>", "status": 0 | 1, "output": [[level, time, message], ...]} to that URL (credentials in the URL become Basic Auth).

Stored configurations

/add/{key} stores either urls (saved as TEXT, only the URLs that parse) or a config in TEXT or YAML. A configuration with no usable URL is still saved; YAML that can not be read at all is 400. /add answers with X-Apprise-Config-Created, X-Apprise-Config-MTime and X-Apprise-Timezone headers (UTC).

Beside each entry: .<name>.created (creation time) and .<name>.lock (the key’s login). The layout is the one the existing API servers use, so their configuration directory can be mounted as it is (with the same SECRET_KEY in hash mode).

/get returns YAML as text/yaml, TEXT as text/plain or {"format", "config"} as JSON; 204 when nothing is stored. /del returns 200; 204 when nothing was stored. /notify/{key} without a stored configuration is 404.

/json/urls/{key} lists every entry:

{
  "tags": ["devops", "home"],
  "urls": [
    {"id": "1a2b3c4d", "service_name": "JSON", "enabled": true,
     "url": "json://127.0.0.1:8766/ops", "retry": 0, "optional": false,
     "tags": ["devops"],
     "tag_details": [{"name": "devops", "priority": 0, "token": "devops", "exact": "0:devops"}],
     "template": {}}
  ]
}

?privacy=yes hides everything after the host of each URL. template maps each ${NAME} of the entry to its configuration default (null with privacy or APPRISE_CONFIG_LOCK). ?tag= filters, comma separated.

Stored configurations go through the library’s configuration loader: tags, groups, ${NAME} templates (values from the request, the configuration defaults, then APPRISE_TEMPLATE_<NAME>) and include, which may only point at http(s)://.

Authentication

With APPRISE_AUTH_REQUIRED=yes every request needs Basic Auth:

• the administrator (APPRISE_USER / APPRISE_PASSWORD) may do everything;
• a key’s own login may use that key (in the path or X-Apprise-Config-ID), /status and /details;
• anything else is 401 with WWW-Authenticate.

Each key has one access mode:

# The administrator gives a key its own login; the key's user may later
# change the password (not the access). GET reads it, DELETE removes it.
curl -u admin:pw -H 'Content-Type: application/json' \
    -d '{"access": "user", "username": "alice", "password": "s3cret"}' http://127.0.0.1:8000/auth/team

APPRISE_CONFIG_LOCK turns user into locked without changing what is saved. It allows reading or changing configuration content only to the administrator. Logins are stored as salted PBKDF2-SHA256 digests; successful checks are remembered for five minutes. Without APPRISE_AUTH_REQUIRED, saved logins are ignored and /auth answers 403.

Status codes

Using the library

The mercurio crate is the library behind the CLI: same URLs, same configuration files, same services. This page is the crate’s own documentation; every type and method is in the API reference (cargo doc -p mercurio --open).

Apprise-compatible Rust library, CLI and HTTP server to send notifications to 150+ services via a single URL.

Services are addressed by URL scheme and query parameters. They can be grouped in configuration files (TEXT and YAML) with tags and ${NAME} templates. The default API is async on tokio (AsyncMercurio); Mercurio is the blocking one. The core is sans-IO, so any AsyncTransport or Transport (another runtime, wasm, a proxy, a test double) can drive it.

Quick start

#![allow(unused)]
fn main() {
async fn run() -> Result<(), mercurio::Error> {
use mercurio::{AsyncMercurio, Message, NotifyType};

let mut m = AsyncMercurio::new();
m.add("ntfy://my-topic")?;
m.add("discord://webhook_id/webhook_token")?;
let msg = Message::new("Disk almost full").title("server-1").kind(NotifyType::Warning);
let report = m.notify(&msg).await;
for (entry, outcome) in report.failures() {
    eprintln!("{}: {:?}", entry.label, outcome.result);
}
m.close().await;
Ok(()) }
}

AsyncMercurio works on any runtime and spawns nothing. One notify call sends to its targets concurrently inside the calling task (at most 128 sends in flight across the process), so it uses one thread; spawn several calls to use more cores. AsyncMercurio::new does its I/O on tokio and rustls with an in-house HTTP/1.1 client (TokioTransport, feature transport-tokio); AsyncMercurio::with_transport takes any AsyncTransport.

notify never panics and never returns early: every URL gets a ReportEntry in the Report, with one Outcome per target and every Attempt made (more than one with ?retry=). Report::status sums it up as a Status.

Architecture

1. Parse. parse() splits a URL into a ParsedUrl (lenient: tokens may contain :, / or @), finds the ServiceDef for the scheme (service_for_scheme) and calls its parser. The parser validates the URL and returns a typed Notify value, wrapped in a Target.
2. Prepare. Target::prepare runs the message pipeline: payload cap, escapes, format conversion (NotifyFormat), title merging and overflow handling (OverflowMode: upstream, truncate, split). The result is one or more Prepared pieces.
3. Plan. Notify::plan turns each piece into a Plan: HTTP requests with continuations that inspect the responses, socket sessions, datagrams, local commands. No I/O happens here (Target::plan does steps 2 and 3).
4. Execute. Target::send_async walks the plan on an AsyncTransport (TokioTransport by default) and Target::send on a blocking Transport (BlockingTransport, testing::FakeTransport in tests, or your own), both with ?retry= / ?wait= handling based on ErrorClass. Target::send_attempts and Target::send_attempts_async return every attempt.

Around this core:

• Runtime services: a per-notifier Registry, with Registry::register_scheme for a closure and Registry::register for a full ServiceDef.
• Configuration: Config loads TEXT and YAML files from paths, http(s):// or memory, with include, tags and TemplateVars.
• Tags: Tag and TagFilter (all, always, AND/OR groups).
• store: the per-target PersistentStore (tokens, sessions, delivery tracking).
• Attachments: AttachmentSet loads files, http(s):// and memory:// sources into Attachments.
• Asset: branding (app_id, colours, images) and pipeline defaults.

Sans-IO: plans without a network

A Target builds its Plan without sending anything. The plan is a plain value: inspect it or hand it to any transport. testing::FakeTransport records every request and answers from a script:

#![allow(unused)]
fn main() {
use mercurio::testing::FakeTransport;
use mercurio::{Asset, Message, service::Plan};

let target = mercurio::parse("json://localhost/hook")?;
let msg = Message::new("Backup done").title("cron");

// Build the plan: no I/O.
match target.plan(&msg, &Asset::default())? {
    Plan::Http(req, _) => assert_eq!(req.url, "http://localhost/hook"),
    other => panic!("unexpected plan {other:?}"),
}

// Run it on a fake transport.
let fake = FakeTransport::new();
fake.respond(204, "");
assert!(target.send(&msg, &fake, &Asset::default()).is_success());
let req = fake.last_request().unwrap();
assert!(String::from_utf8_lossy(&req.body).contains("Backup done"));
Ok::<(), mercurio::Error>(())
}

Services read the clock and randomness (timestamps, signatures, nonces, multipart boundaries) from the transport’s Env too, through Context::env. testing::FixedEnv freezes both, so two runs build byte-identical requests: FakeTransport::new().with_env(FixedEnv::new(1_700_000_000)).

Custom transport

Implement AsyncTransport (for AsyncMercurio) or Transport (for Mercurio) to add logging, tracing, metrics, a proxy or a test double. Only http, file and sleep are required; connect, datagram and command default to Error::Unsupported and env to SystemEnv, so a wrapper forwards them to keep e-mail, chat protocols, syslog and desktop notifications working:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use std::time::Duration;
use mercurio::{
    transport::AsyncConn, AsyncMercurio, transport::AsyncTransport, transport::BoxFuture, transport::Command, transport::CommandOutput, transport::Datagram, transport::Endpoint, transport::FileOp,
    transport::FileOutput, transport::Request, transport::Response, Result, transport::TokioTransport,
};

/// Logs every operation, then lets tokio do it.
struct Logged(TokioTransport);

impl AsyncTransport for Logged {
    fn http<'a>(&'a self, req: &'a Request) -> BoxFuture<'a, Result<Response>> {
        eprintln!("{} {}", req.method.as_str(), mercurio::redact_url(&req.url));
        self.0.http(req)
    }
    fn connect<'a>(&'a self, ep: &'a Endpoint) -> BoxFuture<'a, Result<Box<dyn AsyncConn>>> {
        eprintln!("connect {ep:?}");
        self.0.connect(ep)
    }
    fn datagram<'a>(&'a self, dg: &'a Datagram) -> BoxFuture<'a, Result<()>> {
        self.0.datagram(dg)
    }
    fn command<'a>(&'a self, cmd: &'a Command) -> BoxFuture<'a, Result<CommandOutput>> {
        eprintln!("run {}", cmd.program);
        self.0.command(cmd)
    }
    fn file<'a>(&'a self, op: &'a FileOp) -> BoxFuture<'a, Result<FileOutput>> {
        self.0.file(op)
    }
    fn sleep(&self, d: Duration) -> BoxFuture<'_, ()> {
        self.0.sleep(d)
    }
}

let mut m = AsyncMercurio::with_transport(Arc::new(Logged(TokioTransport::new())));
m.add("mailto://user:pass@example.com")?;
Ok::<(), mercurio::Error>(())
}

A tracing wrapper does the same with each future wrapped in a span (Instrument::instrument).

Blocking API

Mercurio has the same targets, configuration and reports as AsyncMercurio without a runtime: notify blocks until every service has answered, sending on one thread per target. Mercurio::new uses BlockingTransport (ureq + rustls), which needs the transport-blocking feature:

mercurio = { version = "0.1", default-features = false, features = ["all-services", "transport-blocking"] }

#![allow(unused)]
fn main() {
use mercurio::{Mercurio, Message};

let mut m = Mercurio::new();
m.add("ntfy://my-topic")?;
let report = m.notify(&Message::new("Finished in 42s").title("Backup"));
Ok::<(), mercurio::Error>(())
}

Blocking puts a blocking Transport behind AsyncTransport; AsyncMercurio converts from a Mercurio.

Custom services

Registry::register_scheme adds a URL scheme at run time, to one notifier’s Registry (Mercurio::registry_mut). The closure gets each prepared piece of the message and a Hook (parsed URL, asset, store) and returns a Plan: requests for mercurio to send, or Plan::Done when it did the work itself.

#![allow(unused)]
fn main() {
use mercurio::Mercurio;
use mercurio::service::{Plan, Request};

let mut m = Mercurio::new();
m.registry_mut().register_scheme("bookhook", |msg, hook| {
    let channel = hook.url.text("channel").unwrap_or_else(|| "general".into());
    Plan::send(Request::post(format!("https://{}/notify", hook.url.host())).json(&serde_json::json!({
        "channel": channel,
        "text": format!("{}: {}", msg.title, msg.body),
    })))
})?;
m.add("bookhook://hooks.internal?channel=ops")?;
Ok::<(), mercurio::Error>(())
}

Registry::register adds a full ServiceDef with its own URL parser, limits and Notify type, written like a built-in service. Built-in services always win. Each notifier has its own registry, so two notifiers in one process can map the same scheme to different handlers.

Configuration and tags

Mercurio::add_config loads a file or URL; Mercurio::add_config_text takes the text directly. The format (TEXT or YAML) is detected.

#![allow(unused)]
fn main() {
use std::sync::Arc;
use mercurio::testing::FakeTransport;
use mercurio::{Mercurio, Message, NotifyOptions, TagFilter};

let yaml = "
version: 1
urls:
  - json://localhost/devops:
      tag: devops, critical
  - json://localhost/always:
      tag: always
  - json://localhost/untagged
";
let fake = Arc::new(FakeTransport::new());
let mut m = Mercurio::with_transport(fake.clone());
assert_eq!(m.add_config_text(yaml, None)?, 3);

// "devops" matches the devops entry; `always` joins every tagged run.
let report = m.notify_with(&Message::new("deploy failed"), NotifyOptions::new().tags(&TagFilter::parse("devops")));
assert_eq!(report.entries.len(), 2);

// Without a tag (the CLI default) only untagged entries are notified.
let report = m.notify_with(&Message::new("fyi"), NotifyOptions::new().tags(&TagFilter::untagged()));
assert_eq!(report.entries.len(), 1);
Ok::<(), mercurio::Error>(())
}

Testing your integration

testing::FakeTransport works with the whole stack, so application code that sends notifications can be tested without accounts or a network:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use mercurio::testing::FakeTransport;
use mercurio::{Mercurio, Message, Status};

let fake = Arc::new(FakeTransport::new());
fake.respond(500, "server error");
let mut m = Mercurio::with_transport(fake.clone());
m.add("json://localhost/hook")?;
let report = m.notify(&Message::new("hi"));
assert_eq!(report.status(), Status::Failure);
assert_eq!(fake.requests().len(), 1);
Ok::<(), mercurio::Error>(())
}

Cargo features

Every service is compiled by default (all-services). Each one also has its own feature, service-<id>, so a build can carry only the services it uses:

For a slim build, disable default features and pick services: mercurio = { version = "0.1", default-features = false, features = ["service-telegram", "service-ntfy"] }. Add bundle-timezones to keep ?tz= zones working on hosts without a system time zone database.

Services

159 services. Each page lists the URL formats, every query parameter with its default, known differences with Apprise and examples.

Every service is compiled by default (all-services). Each has its own Cargo feature (the Feature column): with default-features = false, turn on only the ones you use. Matrix end-to-end encryption is service-matrix-e2ee.

46elks

URL formats

{schema}://{user}:{password}@{from_phone}
{schema}://{user}:{password}@{from_phone}/{targets}

{schema} is one of 46elks://, elks://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

elks://user:pass@+15551234123/
46elks://user:pass@+15551234556
46elks://user:pass@Acme/15551234512/%2B15551234513
46elks://user:pass@+15551234567/+46701234534?from=Acme
https://user1:pass@api.46elks.com/a1/sms/?to=15551234511
https://user1:pass@api.46elks.com/a1/sms?to=+15551234511&from=Acme
46elks://user:pass@Acme?to=15551234511,+15551234512

Rejected URLs:

46elks://
46elks://user@/
46elks://:pass@/

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'elks://user:pass@+15551234123/'

Notes

46elks (46elks://, elks://): SMS through the 46elks API.

800.com

URL formats

{schema}://{token}@{from_phone}
{schema}://{token}@{from_phone}/{targets}

{schema} is one of eight00com://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

eight00com://token@15551232000
eight00com://token@15551232000/15551232001
eight00com://token@15551232000/15551232001/15551232002
eight00com://user@15551232000?token=tok
eight00com://token@15551232001/15551232002?from=15551232000
eight00com://15551232000?token=tok&to=15551232001

Rejected URLs:

eight00com://
eight00com://15551232000
eight00com://token@abcd

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'eight00com://token@15551232000'

Notes

800.com (eight00com://): SMS through the 800.com messaging API.

Africas Talking

URL formats

{schema}://{appuser}@{apikey}/{targets}

{schema} is one of atalk://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

atalk://user@apikey/11111111111/
atalk://user@apikey/+254711000111
atalk://user@apikey/123/33333333333/abcd/+44444444444
atalk://user@apikey/+44444444444?mode=s
atalk://user@apikey/+44444444444/55555555555?batch=y
atalk://11111111111?apikey=key&user=user&from=FROMUSER
atalk://_?user=user&to=11111111111,22222222222&key=bbbbbbbbbb&from=5555555555555

Rejected URLs:

atalk://
atalk://:@/
atalk://user@^/
atalk://user@apikey/+44444444444?mode=invalid

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'atalk://user@apikey/11111111111/'

Notes

Africa’s Talking (atalk://): SMS through the Africa’s Talking messaging API.

Apprise API

URL formats

{schema}://{host}/{token}
{schema}://{host}:{port}/{token}
{schema}://:{password}@{host}/{token}
{schema}://:{password}@{host}:{port}/{token}
{schema}://{user}@{host}/{token}
{schema}://{user}@{host}:{port}/{token}
{schema}://{user}:{password}@{host}/{token}
{schema}://{user}:{password}@{host}:{port}/{token}

{schema} is one of apprise://, apprises://.

URL tokens

Query parameters

Prefixed parameters:

• +name=value: HTTP Header

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

apprise://localhost/mytoken0/
apprise://user@localhost/mytoken1/
apprise://localhost/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
apprises://localhost/cccccccccccccccccccccccccccccccc
http://example.com/notify/dddddddddddddddddddddddddddddddd
https://example.com/path/notify/dddddddddddddddddddddddddddddddd
apprise://localhost/mytoken1/?v=1
apprise://localhost/tok/?tags=a,b

Rejected URLs:

apprise://
apprise://:@/
apprise://localhost
apprise://localhost/!

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'apprise://localhost/mytoken0/'

Notes

Apprise API relay (apprise://, apprises://): hands the notification to an Apprise API server, which delivers it to its configured services.

Aprs

URL formats

{schema}://{user}:{password}@{targets}

{schema} is one of aprs://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

aprs://DF1JSL-15:12345@DF1ABC
aprs://DF1JSL-15:12345@DF1ABC/DF1DEF
aprs://DF1JSL-15:12345@DF1ABC-1/DF1ABC/DF1ABC-15
aprs://DF1JSL-15:12345@DF1ABC?locale=EURO
aprs://DF1JSL-15:12345@?to=DF1ABC,DF1DEF
aprs://DF1JSL-15:12345@DF1ABC?locale=noam&delay=0.1

Rejected URLs:

aprs://
aprs://:@/
aprs://DF1JSL-15:12345
aprs://DF1JSL-15@DF1ABC

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'aprs://DF1JSL-15:12345@DF1ABC'

Notes

APRS (aprs://): text messages to amateur radio call signs through APRS-IS.

One TCP connection to the regional APRS-IS server (port 10152): the user ... pass ... vers ... login, the server’s # logresp check, then one message packet per call sign: FROMCALL>APPRIS::TOCALL :text (text cleaned and cut to 67 chars).

Differences with Apprise

• The login names the software mercurio <version> (Apprise: apprise <version>).
• When the first read holds only the server banner, mercurio reads once more for the # logresp line (Apprise fails).
• The 0.8 s (+ delay) wait applies between the message packets of one notification, not between login and the first packet.

AWS Simple Email Service (SES)

URL formats

{schema}://{from_email}/{access_key_id}/{secret_access_key}/{region}/{targets}
{schema}://{from_email}/{access_key_id}/{secret_access_key}/{region}

{schema} is one of ses://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

ses://user@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2
ses://user:SESSIONTOKEN@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-east-1/
ses://user@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2/user2@example.com/Bob%20Smith%20%3Cbob@example.org%3E
ses://user@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2?format=text
ses://user@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2?token=TOK%2Bx%3D
ses://user@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2/a@example.com/b@example.com?cc=b@example.com
ses://user@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2/user2@example.com?reply=Rep%20Ly%20%3Crep@example.com%3E
ses://user@example.com/?key=T1JJ3T3L2&secret=A1BRTD4JD/TIiajkdnlazkcevi7FQ&region=US-WEST-2&from=other@example.net

Rejected URLs:

ses://
ses://:@/
ses://user@example.com/T1JJ3T3L2
ses://user@example.com/T1JJ3TD4JD/TIiajkdnlazk7FQ/

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'ses://user@example.com/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2'

Notes

AWS Simple Email Service (ses://): SendRawEmail with a MIME message built by the shared mail module, signed with AWS SigV4.

Cc/Bcc recipients are sent in sorted order.

AWS Simple Notification Service (SNS)

URL formats

{schema}://{token}@{access_key_id}/{secret_access_key}/{region}/{targets}
{schema}://{access_key_id}/{secret_access_key}/{region}/{targets}

{schema} is one of sns://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

sns://T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2/12223334444
sns://T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-east-1/MyTopic/12223334444
sns://SESSIONTOKEN@T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-east-1/12223334444
sns://T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-east-1/MyTopic/12223334444?mode=t
sns://T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-east-1/MyTopic?mode=sms
sns://OTHER@T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-east-1/12223334444?token=TOK%2Bx%3D
sns://?key=T1JJ3T3L2&secret=A1BRTD4JD/TIiajkdnlazkcevi7FQ&region=US-WEST-2&to=12223334444
sns://?access=T1JJ3T3L2&secret=A1BRTD4JD/TIiajkdnlazkcevi7FQ&region=us-west-2&to=12223334444

Rejected URLs:

sns://
sns://T1JJ3T3L2
sns://T1JJ3TD4JD/TIiajkdnlazk7FQ/
sns://T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-east-1/12223334444?region=useast

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'sns://T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcevi7FQ/us-west-2/12223334444'

Notes

AWS Simple Notification Service (sns://): SMS and topic messages through AWS SNS.

Requests are signed with AWS Signature Version 4 when they are sent.

Bark

URL formats

{schema}://{host}/{targets}
{schema}://{host}:{port}/{targets}
{schema}://{user}:{password}@{host}/{targets}
{schema}://{user}:{password}@{host}:{port}/{targets}

{schema} is one of bark://, barks://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

barks://192.168.0.7/device_key/
bark://192.168.0.6:8081/device_key
bark://user@192.168.0.6:8081/device_key
bark://192.168.0.6:8081/device_key/?image=no
bark://192.168.0.6:8081/device_key/?volume=-1
bark://192.168.0.6:8081/device_key/?sound=invalid
bark://192.168.0.6:8081/device_key/?level=invalid
barks://192.168.0.6:8081/device_key/?badge=invalid

Rejected URLs:

bark://
bark://:@/
bark://192.168.0.6:8081/device_key/?key=short
bark://192.168.0.6:8081/device_key/?key=%C3%A90123456789abcd

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'barks://192.168.0.7/device_key/'

Notes

Bark (bark://, barks://): push notifications to the Bark iOS app through a Bark server.

With ?key= every payload is encrypted with AES-GCM (16, 24 or 32 byte ASCII key, fresh 12 character IV per request) the way the Bark app expects.

Bird (MessageBird)

URL formats

{schema}://{apikey}/{source}
{schema}://{apikey}/{source}/{targets}

{schema} is one of msgbird://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

msgbird://bk_eu1_bbbbbbbbbbbbbbbbbbbbbbbb/15551232000
msgbird://bk_us1_aaaaaaaaaaaaaaaaaaaaaaaaaaaa/15551232000/15551232001/15551232002
msgbird://bk_us1_aaaaaaaaaaaaaaaaaaaaaaaaaaaa/15551232000/15551232001?from=15551233000
msgbird://bk_us1_aaaaaaaaaaaaaaaaaaaaaaaaaaaa/15551232000?category=Marketing
msgbird://bk_us1_aaaaaaaaaaaaaaaaaaaaaaaaaaaa/?from=15551233000&to=15551232000

Rejected URLs:

msgbird://
msgbird://bk_us1_aaaaaaaaaaaaaaaaaaaaaaaaaaaa/abcd
msgbird://bk_us1_aaaaaaaaaaaaaaaaaaaaaaaaaaaa/123
msgbird://bk_us1_aaaaaaaaaaaaaaaaaaaaaaaaaaaa

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'msgbird://bk_eu1_bbbbbbbbbbbbbbbbbbbbbbbb/15551232000'

Notes

Bird, formerly MessageBird, SMS (msgbird://).

POST https://{region}.platform.bird.com/v1/sms/messages with a Bird API key (bk_{region}_...) as a Bearer token, one request per target. Classic MessageBird keys (25 characters, rest.messagebird.com) stop working on 2026-12-31 and are rejected.

Differences with Apprise

• Apprise posts to the classic rest.messagebird.com/messages API with a 25-character key, while mercurio uses Bird’s SMS API ({region}.platform.bird.com/v1/sms/messages, bk_... key as Bearer, JSON from/to/text/category, new ?category=); classic keys, which stop working on 2026-12-31, are rejected.

blink(1)

URL formats

{schema}://
{schema}://{serial}/

{schema} is one of blink1://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

blink1://
blink1://_/
blink1://?ledn=1
blink1://?fade=10000
blink1://?duration=300000
blink1://?fade=15&duration=5
blink1://ABCD1234/?fade=100&duration=50
blink1://?fade=200&duration=100&ledn=2

Rejected URLs:

blink1://?fade=10001
blink1://?fade=-1
blink1://?fade=abc
blink1://?duration=300001

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'blink1://'

Notes

blink(1) (blink1://, blink1://<serial>/): lights a blink(1) USB LED in the notification type’s colour.

Sequence: fade to the colour over fade ms, wait fade + duration ms, then switch the LED off instantly. Mercurio has no HID dependency and drives the sequence through ThingM’s blink1-tool, which must be installed and on PATH:

blink1-tool [--id <serial>] --led <n> -m <fade> --rgb <r>,<g>,<b>
(sleep fade + duration)
blink1-tool [--id <serial>] --led <n> -m 0 --rgb 0,0,0

The fade is passed rounded down to 10 ms, the device’s resolution.

BlueSky

URL formats

{schema}://{user}@{password}

{schema} is one of bsky://, bluesky://.

URL tokens

Query parameters

No service-specific parameters.

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

bsky://user@app-pw
bluesky://user@app-pw

Rejected URLs:

bluesky://
bluesky://:@/
bluesky://app-pw

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'bsky://user@app-pw'

Notes

BlueSky (bsky://, bluesky://): posts to a BlueSky account through the AT Protocol API.

Flow per message: resolve the handle to a DID, fetch the DID document to find the PDS endpoint, create a session, upload image blobs, then create one record per blob (or a single text record).

The persistent store keeps the DID and PDS endpoint of each handle (did.<handle>, endpoint.<handle>) and the session (access_token, refresh_token for an hour less 10 s, endpoint), so later sends skip the lookups and the login.

Brevo

URL formats

{schema}://{apikey}:{from_email}
{schema}://{apikey}:{from_email}/{targets}

{schema} is one of brevo://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

brevo://abcd:user@example.com
brevo://abcd:user@example.com/newuser@example.com
brevo://abcd:user@example.com?format=text
brevo://abcd:user@example.com/newuser@example.com?cc=l2g@nuxref.com
brevo://abcd:user@example.com/newuser@example.com?to=l2g@nuxref.com
brevo://abcd:user@example.com/newuser@example.com?bcc=l2g@nuxref.com
brevo://abcd:user@example.com/newuser@example.com?reply=Bob%20<bob@example.com>
brevo://abcd:user@example.com/newuser@example.com?cc=l2g@nuxref.com&bcc=l2g@nuxref.com

Rejected URLs:

brevo://
brevo://:@/
brevo://abcd
brevo://abcd@host

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'brevo://abcd:user@example.com'

Notes

Brevo (brevo://): transactional e-mail through the Brevo API.

brevo://{apikey}:{from_user}@{from_domain}[/{to_email}...][?cc=..&bcc=..&reply=..&to=..]

Both an HTML and a plain-text part are sent; the one not given is converted from the other. Without targets the message goes to the sender.

BulkSMS

URL formats

{schema}://{token_id}:{token_secret}@{targets}

{schema} is one of bulksms://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

bulksms://aaaaaaaaaa:bbbbbbbbbb@55555555555
bulksms://aaaaa:bbbbbbbbbb@123/33333333333/abcd/
bulksms://aaaaaaaaaa:bbbbbbbbbb@123456/44444444444
bulksms://bbbbb:cccccccccc@44444444444/55555555555/@grp?batch=y
bulksms://aaaaaaaaaa:bbbbbbbbbb@admin?route=premium
bulksms://aaaaaaaaaa:bbbbbbbbbb@55555555555?unicode=maybe
bulksms://bbbbb:cccccccccc@44444444444?batch=y&unicode=n
bulksms://_?user=aaaaaaaaaa&password=bbbbbbbbbb&from=55555555555

Rejected URLs:

bulksms://aaaaaaaaaa:bbbbbbbbbb@admin?route=invalid
bulksms://_?user=aaaaaaaaaa&password=bbbbbbbbbb&from=555

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'bulksms://aaaaaaaaaa:bbbbbbbbbb@55555555555'

Notes

BulkSMS (bulksms://): SMS through the BulkSMS API.

BulkVS

URL formats

{schema}://{user}:{password}@{from_phone}/{targets}
{schema}://{user}:{password}@{from_phone}

{schema} is one of bulkvs://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

bulkvs://uuuuuuuuuu:pppppppppp@2222222222
bulkvs://aaaaa:bbbbbbbbbb@9876543210/33333333333/abcd/
bulkvs://bbbbb:cccccccccc@44444444444?batch=y
bulkvs://bbbbb:cccccccccc@44444444444/55555555555/66666666666?batch=y
bulkvs://aaaaaaaaaa:bbbbbbbbbb@66666666666/77777777777?from=55555555555
bulkvs://?user=zzzzzzzzzz&password=yyyyyyyyyy&from=55555555555
bulkvs://?user=aaaaaaaaaa&password=bbbbbbbbbb&from=55555555555&to=7777777777777

Rejected URLs:

bulkvs://
bulkvs://:@/
bulkvs://aaaaaaaaaa@9876543210/
bulkvs://uuuuuuuuuu:pppppppppp@33333

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'bulkvs://uuuuuuuuuu:pppppppppp@2222222222'

Notes

BulkVS (bulkvs://): SMS through the BulkVS messaging API.

Burst SMS

URL formats

{schema}://{apikey}:{secret}@{sender_id}/{targets}

{schema} is one of burstsms://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

burstsms://aaaaaaaa:bbbbbbbbbbbbbbbb@Sender/66666666666/77777777777
burstsms://_?key=aaaaaaaa&secret=bbbbbbbbbbbbbbbb&from=55555555555&to=66666666666
burstsms://_?key=aaaaaaaa&secret=bbbbbbbbbbbbbbbb&source=55555555555&to=66666666666&country=gb
burstsms://_?key=aaaaaaaa&secret=bbbbbbbbbbbbbbbb&source=55555555555&to=66666666666&validity=10
burstsms://_?key=aaaaaaaa&secret=bbbbbbbbbbbbbbbb&from=55555555555&to=66666666666,77777777777&batch=y

Rejected URLs:

burstsms://
burstsms://:@/
burstsms://aaaaaaaa@12345678
burstsms://dddddddd:eeeeeeeeeeeeeeee@%20

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'burstsms://aaaaaaaa:bbbbbbbbbbbbbbbb@Sender/66666666666/77777777777'

Notes

Burst SMS (burstsms://): SMS through the Burst SMS API.

Chanify

URL formats

{schema}://{token}

{schema} is one of chanify://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

chanify://abc123
chanify://?token=abc123
chanify://other/?token=abc.1_2-3

Rejected URLs:

chanify://
chanify://:@/
chanify://%badtoken%

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'chanify://abc123'

Notes

Chanify (chanify://): push notifications to the Chanify app.

Cisco Webex Teams

URL formats

{schema}://{token}
{schema}://{access_token}/{targets}

{schema} is one of wxteams://, webex://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

wxteams://BotToken1234567890/Y2lzY29zcGFyazovL3VzL1JPT00vabc
wxteams://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
https://api.ciscospark.com/v1/webhooks/incoming/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
webex://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
wxteams://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Y2lzY29zcGFyazovL3VzL1JPT00vabc?mode=b
wxteams://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?format=text
https://webexapis.com/v1/webhooks/incoming/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?format=text
wxteams://BotToken1234567890?to=Y2lzY29zcGFyazovL3VzL1JPT00vabc&mode=bot

Rejected URLs:

wxteams://
wxteams://:@/
wxteams://shorttoken?mode=webhook
wxteams://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?mode=invalid

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'wxteams://BotToken1234567890/Y2lzY29zcGFyazovL3VzL1JPT00vabc'

Notes

Cisco Webex Teams (wxteams://, webex://): messages through Webex incoming webhooks.

Clickatell

URL formats

{schema}://{apikey}/{targets}
{schema}://{source}@{apikey}/{targets}

{schema} is one of clickatell://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

clickatell://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/1111111111
clickatell://1111111111@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/1111111111
clickatell://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/+1%20555%20123%204567/tel:15551234568
clickatell://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?from=1111111111&to=1111111111,2222222222

Rejected URLs:

clickatell://
clickatell:///
clickatell://@/
clickatell://1111111111@/

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'clickatell://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/1111111111'

Notes

Clickatell (clickatell://): SMS through the Clickatell API.

ClickSend

URL formats

{schema}://{user}:{apikey}@{targets}

{schema} is one of clicksend://.

URL tokens

Query parameters

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

clicksend://user:pass@33333333333/44444444444/55555555555
clicksend://user:pass@33333333333333?batch=yes
clicksend://user:pass@33333333333/44444444444/55555555555?batch=yes
clicksend://user@33333333333333?key=a%252Bb
clicksend://user@33333333333333?batch=no&key=abc123
clicksend://user:pass@33333333333333?batch=yes&to=66666666666666

Rejected URLs:

clicksend://
clicksend://:@/
clicksend://user@33333333333333

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'clicksend://user:pass@33333333333/44444444444/55555555555'

Notes

ClickSend (clicksend://): SMS through the ClickSend API.

Courier

URL formats

courier://{auth_token}/{targets}

URL tokens