Message Expiry Interval is an MQTT 5.0 property that controls how long a broker retains an undelivered message. When the specified interval elapses, the broker deletes the message instead of delivering outdated data to subscribers.
How it works
When a publisher sends a PUBLISH packet, it sets the Message Expiry Interval property to a value in seconds. The broker tracks the elapsed time from the moment it receives the message:
Message delivered before expiry: The broker forwards the message to the subscriber normally.
Message not delivered before expiry: The broker discards the message. No subscriber receives it.
Limitations
| Condition | Behavior |
|---|---|
| No Message Expiry Interval set | Messages do not expire. The broker retains them indefinitely. |
| Value below 1 minute (60 seconds) | Automatically adjusted to 60 seconds. |
| Value above 3 days (259,200 seconds) | Automatically adjusted to 259,200 seconds. |
The valid range is 60 to 259,200 seconds (1 minute to 3 days). Values outside this range are clamped to the nearest boundary.
Use cases
| Scenario | Why expiry matters |
|---|---|
| IoT telemetry | Sensor readings become irrelevant within minutes. Expired readings mislead dashboards and monitoring systems. |
| Time-sensitive promotions | Flash sales and discount offers lose their value after a deadline. Delivering an expired offer creates a poor user experience. |
| Alerts and security notifications | Emergency messages that arrive late may cause operators to act on conditions that have already been resolved, or miss the response window entirely. |
| Order and transaction processing | Financial transactions and order confirmations require action within strict time windows. A stale order message can trigger duplicate processing or missed deadlines. |
Examples
All examples use the MQTT 5.0 PUBLISH packet with the Message Expiry Interval property set in seconds.
Factory equipment status reporting
An IoT device monitors a machine on a factory floor and reports its running status. A 5-minute expiry makes sure subscribers only act on the most recent status:
PUBLISH
Topic: factory/machine1/status
Payload: RUNNING
QoS: 1
Message Expiry Interval: 300 // 5 minutesIf no subscriber receives this message within 300 seconds, the broker removes it. A subscriber that comes online after this window does not receive the outdated status.
Time-limited discount notification
An e-commerce platform sends a 30-minute flash sale notification. Matching the expiry to the promotion window prevents subscribers from seeing an offer that has already ended:
PUBLISH
Topic: store/promotions
Payload: 50off-for-next-30-minutes
QoS: 1
Message Expiry Interval: 1800 // 30 minutesIf no subscriber receives this message within 1,800 seconds, the broker deletes it automatically.
Usage notes
Default behavior: If you do not set a Message Expiry Interval, messages persist in the broker with no expiration. For time-sensitive data, always set an explicit interval.
Unit: The Message Expiry Interval value is specified in seconds at the MQTT protocol level. ApsaraMQ for MQTT enforces a minimum of 60 seconds and a maximum of 259,200 seconds (3 days).
Clamping, not rejection: Out-of-range values are silently adjusted. If your application logic depends on a precise expiry, verify that the intended value falls within the 60-second to 259,200-second range.