Skip to content

MQTT

MQTT is a lightweight messaging protocol for small sensors and mobile devices, ideal for IoT and low-bandwidth environments. Upstream docs: https://mqtt.org/

Features

  • QoS Levels: Support for Quality of Service levels 0 (at most once), 1 (at least once), and 2 (exactly once)
  • Retained Messages: Messages can be retained by the broker for new subscribers
  • TLS/SSL Support: Secure connections via the mqtts:// scheme
  • Authentication: Username/password authentication
  • Clean Session: Control whether the broker maintains session state
  • Managed Connection: The first send connects to the broker, later sends reuse the connection, and an idle connection is closed after 60 seconds

Getting Started

MQTT is widely used in IoT, home automation, and real-time messaging applications. The protocol is supported by many popular brokers:

  • Mosquitto: A popular open-source MQTT broker
  • Home Assistant: Built-in MQTT support for smart home automation
  • EMQX: Enterprise-grade MQTT broker
  • HiveMQ: Scalable MQTT platform

To send notifications via MQTT, you need a running MQTT broker and a topic to publish to. Topics use a hierarchical naming scheme with forward slashes (e.g., home/alerts, sensors/temperature).

URL Formats

The MQTT service supports two URL schemes for connection security:

  • mqtt://: Standard unencrypted connection (port 1883 by default)

mqtt://[username[:password]@]host[:port]/topic

  • mqtts://: TLS-encrypted connection (port 8883 by default)

mqtts://[username[:password]@]host[:port]/topic

URL Fields

  • Username - Auth username Default: empty
    URL part: mqtt://username:password@host:port/topic/
  • Password - Auth password Default: empty
    URL part: mqtt://username:password@host:port/topic/
  • Host - MQTT broker hostname Default: localhost
    URL part: mqtt://username:password@host:port/topic/
  • Port - MQTT broker port Default: 1883
    URL part: mqtt://username:password@host:port/topic/
  • Topic - Target topic name (Required)
    URL part: mqtt://username:password@host:port/topic/

Query/Param Props

Props can be either supplied using the params argument or through the URL using ?key=value&key=value etc.

  • cleansession - Start with a clean session Default: ✔ yes

  • clientid - MQTT client identifier Default: shoutrrr

  • disabletls - Disable TLS encryption Default: ❌ no

  • disabletlsverification - Disable TLS certificate verification Default: ❌ no

  • qos - Quality of Service level (0, 1, or 2) Default: 0 Possible values: AtMostOnce, AtLeastOnce, ExactlyOnce

  • retained - Retain message on broker Default: ❌ no

TLS Configuration Options

The following options control TLS behavior:

  • disabletls: When set to yes, forces an unencrypted connection even if the mqtts:// scheme is used. This overrides the scheme's implicit TLS requirement.

  • disabletlsverification: When set to yes, disables TLS certificate verification while still using encryption. This is useful for self-signed certificates.

Security Warning: Silent TLS Downgrade

Setting disabletls=yes with mqtts:// will force an unencrypted connection despite the secure scheme. This is likely unexpected behavior and can cause silent downgrades where you believe traffic is encrypted but it is not.

Recommendation: If you intentionally want an unencrypted connection, use mqtt:// (non-TLS scheme) instead of combining mqtts:// with disabletls=yes.

When to Use disabletls=yes

This option is intended for specific edge cases, such as:

  • TLS-terminating proxy: When connecting through a proxy that handles TLS termination, where the connection from client-to-proxy uses TLS but proxy-to-broker is plain MQTT. For example, a reverse proxy like Traefik or nginx that terminates TLS and forwards to an internal MQTT broker.
  • Testing environments: Local development where encryption is not required.

Connection Lifecycle

The service connects to the broker lazily and keeps the connection open between sends.

How It Works

  1. Initialize() parses the URL and stores the configuration. It does not connect to the broker.
  2. The first Send() opens the connection, and later sends reuse it.
  3. A connection that has not been used for 60 seconds is closed. The next Send() opens a new one, so short-lived programs do not leave connections behind.
  4. Close() disconnects from the broker. A later Send() reconnects.

A connection manager set with SetConnectionManager() belongs to the caller. The service never closes it for being idle, and Close() disconnects it.

Error Behavior

If opening the connection fails, the error is returned to the caller and the next Send() tries again, so temporary network issues or broker unavailability do not require a new call to Initialize(). If the connection ends, for example because it was disconnected, the next Send() opens a new one.

Send Params

Params apply to a single send and do not change the service configuration. The qos and retained params affect every send that uses them. The connection params (clientid, cleansession, disabletls, and disabletlsverification) apply when that send opens the connection, and are ignored while an existing connection is reused.

Example Send Params
// Publish this message as retained with QoS 1, without changing later sends
params := types.Params{
    "qos":      "1",
    "retained": "yes",
}
service.Send(message, &params)

Examples

Basic Notification

mqtt://broker.example.com/notifications

With Authentication

mqtt://user:[email protected]:1883/home/alerts

Secure Connection

mqtts://user:[email protected]:8883/home/alerts

With QoS and Retained Message

mqtt://broker.example.com/alerts?qos=1&retained=yes

Home Assistant

mqtt://homeassistant.local:1883/homeassistant/notification

Mosquitto broker with custom client ID

mqtt://mosquitto.example.com:1883/sensors/alerts?clientid=shoutrrr-alerts&qos=2

Self-signed Certificate

mqtts://broker.local:8883/secure/alerts?disabletlsverification=yes

Full Configuration

mqtts://admin:[email protected]:8883/production/alerts?clientid=prod-shoutrrr&qos=1&retained=yes&cleansession=no