---
title: "Node-RED MQTT Out node"
description: "The MQTT Out node connects to an MQTT broker and publishes messages to one or more topics.
It is typically used to send sensor data, commands, or event notifications from Node-RED to external systems or devices that subscribe to MQTT topics."
canonical_url: "https://flowfuse.com/docs/node-red/core-nodes/network/mqtt-out/"
---

> Index of every page on this site: [llms.txt](https://flowfuse.com/llms.txt)

# MQTT Out

The MQTT Out node connects to an MQTT broker and publishes messages to one or more topics.<br />


It is typically used to send sensor data, commands, or event notifications from Node-RED to external systems or devices that subscribe to MQTT topics.

## How it works

When a message arrives at the node input, it publishes the content of `msg.payload` to the specified topic on the broker.<br />


If no topic is set in the node, it must be provided in `msg.topic`.

If `msg.payload` is not set, no message will be sent.<br />


To send an empty message, set `msg.payload` to an empty string (`""`).

## Configuration

The MQTT Out node requires a connection to an MQTT broker.<br />


This can be configured by clicking the pencil icon next to the **Server** field.<br />


Multiple MQTT nodes (in or out) can share the same broker configuration.

### Server

Defines the broker connection details:

- Broker address (for example, `test.mosquitto.org`)
- Port (default 1883 for non-TLS, 8883 for TLS)
- Optional username and password
- MQTT version (v3.1, v3.1.1, or v5)
- Enable TLS for encrypted connections
- Client ID and session options

### Topic

Specifies the MQTT topic to publish to.<br />


You can enter a fixed topic or leave it blank to use `msg.topic` dynamically.

### QoS

Defines the message delivery quality level:

- 0 – fire and forget
- 1 – at least once
- 2 – once and once only (default)

The QoS can be overridden at runtime using `msg.qos`.

### Retain

If set to true, the broker will retain the last message sent to the topic and deliver it to new subscribers immediately.<br />


You can override this in the flow using `msg.retain`.

To clear a retained topic, send a blank message (`msg.payload = ""`) with `msg.retain = true`.

## Input properties

The MQTT Out node accepts the following properties in incoming messages:

- `msg.payload` (string | buffer) – the message payload to publish.<br />


If it contains an object, it is automatically converted to a JSON string.<br />


If it contains a buffer, it is sent as-is.
- `msg.topic` (string) – the topic to publish to. Required if not defined in the node.
- `msg.qos` (number) – overrides the configured QoS (0, 1, or 2).
- `msg.retain` (boolean) – overrides the retain flag.

### MQTT v5 properties

If the broker and node are using MQTT version 5, the following properties can also be set:

- `msg.responseTopic` (string) – the MQTT response topic for the message
- `msg.correlationData` (buffer) – correlation data for the message
- `msg.contentType` (string) – the content type of the payload
- `msg.userProperties` (object) – any user-defined properties
- `msg.messageExpiryInterval` (number) – expiry time, in seconds
- `msg.topicAlias` (number) – topic alias to use

## Dynamic control

The MQTT Out node can also respond to special control messages to manage the connection dynamically.<br />


If one of these control messages is received, the node will perform the action but will not publish the payload.

### `msg.action`

Defines the action to perform. Supported actions:

- `connect` – establish a connection to the broker
- `disconnect` – close the current connection

### `msg.broker`

For the **connect** action, this property can override broker configuration options dynamically, including:

- `broker`
- `port`
- `url` (overrides both broker and port)
- `username`
- `password`

If the node is already connected and new settings are provided, it will log an error unless the property `force` is set to true.<br />


In that case, it will disconnect, apply the new configuration, and reconnect.

## Example: Simple Publish

This example shows how to publish a timestamp to an MQTT topic on the public Mosquitto test broker.

<render-flow>

```json
[{"id":"c1b20f45c3c3e77e","type":"tab","label":"MQTT Publish Example","disabled":false,"info":"","env":[]},{"id":"e5b31919a35d7f51","type":"inject","z":"c1b20f45c3c3e77e","name":"Inject Timestamp","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"example/time","payload":"","payloadType":"date","x":180,"y":120,"wires":[["6cd12cecb82889e2"]]},{"id":"6cd12cecb82889e2","type":"mqtt out","z":"c1b20f45c3c3e77e","name":"MQTT Out","topic":"","qos":"1","retain":"false","broker":"da4d8b90.3a89d8","x":430,"y":120,"wires":[]},{"id":"da4d8b90.3a89d8","type":"mqtt-broker","name":"Public Mosquitto Broker","broker":"test.mosquitto.org","port":"1883","clientid":"","autoConnect":true,"usetls":false,"protocolVersion":"4","keepalive":"60","cleansession":true}]
```

</render-flow>

## Notes

- The node automatically converts objects to JSON strings when publishing.
- For large payloads or binary data, use buffers to avoid unnecessary conversion.
- Multiple MQTT Out nodes can share the same broker connection.
- MQTT v5 users can take advantage of additional properties for richer message metadata.

<node-red-help category="network" file="10-mqtt" name="MQTT Out" node="mqtt out">



</node-red-help>

## Sitemap

See the full [sitemap](https://flowfuse.com/sitemap.md) for all pages.
