MQTT Notification


Schemes	`mqtt://`, `mqtts://`
Cargo feature	`service-mqtt`
Service	https://mqtt.org/
Body formats	`text` (first is the default)
Attachments	no
Title length	no title (merged into the body)
Body length	268,435,455 characters
Body lines	unlimited
Request throttle	500 ms between requests
Vendor URLs accepted	no

URL formats

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

{schema} is one of mqtt://, mqtts://.

URL tokens

Token	Meaning	Type	Required	Notes
`{host}`	Hostname	string	yes
`{password}`	Password	string	yes	secret
`{port}`	Port	int, 1 to 65535	no
`{targets}`	Targets	list	no	any of `topic`; separated by `/`
`{topic}`	Target Queue	string	yes
`{user}`	User Name	string	yes

Query parameters

Parameter	Meaning	Type	Default	Notes
`client_id`	Client ID	string
`qos`	QOS	int, 0 to 2	`0`
`retain`	Retain Messages	bool	`no`
`session`	Use Session	bool	`no`
`to`	Targets	list		sets `{targets}`
`version`	Version	choice	`v3.1.1`	one of `v3.1.1`, `v3.1`, `v5.0`

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):

mqtt://user@localhost/t
mqtt://localhost/b%20a;c
mqtts://localhost:8884/t
mqtt://localhost/my/topic
mqtts://user:pass@localhost/my/topic
mqtt://localhost/my/topic,my/other/topic
mqtt://user:pass@localhost/a/b?qos=2
mqtt://user@localhost/my/topic?retain=yes

Rejected URLs:

mqtt://
mqtt://localhost?qos=123
mqtt://localhost/t?qos=-1
mqtt://localhost?qos=invalid

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'mqtt://user@localhost/t'

Notes

MQTT (mqtt://, mqtts://): publishes the message to an MQTT broker.

The client is built in: MQTT 3.1 / 3.1.1 / 5, with CONNECT (client id, clean session, credentials, keepalive 30) answered by CONNACK, then one PUBLISH per topic (QoS 1 waits for PUBACK, QoS 2 runs PUBREC/PUBREL/PUBCOMP), then DISCONNECT.

Differences with Apprise

MQTT 5 works (Apprise passes clean_session to paho for every version, which paho rejects for v5).
TLS uses the bundled Mozilla roots or the SSL_CERT_FILE bundle (Apprise refuses verified mqtts:// without a CA bundle on disk).
Topics of one notification are not throttled against each other (Apprise waits 0.5 s between publishes).
CONNACK is awaited before publishing (paho publishes asynchronously).

Keyboard shortcuts