Updated on 2022-12-19 GMT+08:00

Delivering Scheduled Messages

In DMS for RocketMQ, you can schedule messages to be delivered at any time, with a maximum delay of one year.

After being sent from producers to DMS for RocketMQ, scheduled messages are delivered to consumers only after a specified point in time.

Before delivering scheduled messages, collect RocketMQ connection information by referring to Collecting Connection Information.

This function is supported only for instances created on or after March 30, 2022.

Application Scenarios

Scheduled messages can be used in the following scenarios:

  • The service logic requires a time window. For example, an e-commerce order is closed if it is not paid within a period of time. When an order is created, a scheduled message is sent and will be delivered to the consumer five minutes later. After receiving the message, the consumer checks whether the order is paid. If the order is not paid, it is closed. If the order is paid, the message is ignored.
  • A scheduled task is triggered by a message. For example, a reminder is sent to a user at a specific time.


  • The delivery time can be scheduled to up to one year later. If the delay time exceeds one year, the message cannot be delivered.
  • If the delivery time is scheduled to a time point earlier than the current timestamp, the message is immediately sent to the consumer.
  • Ideally, the difference between the scheduled delivery time and the actual delivery time is smaller than 0.1s. However, if the pressure of scheduled message delivery is too high, flow control will be triggered, and the precision will deteriorate.
  • The message delivery order is not ensured for precision of 0.1s. That is, if the difference between the scheduled delivery time of two messages is smaller than 0.1s, they may not be delivered in the order that they were sent.
  • Exactly-once delivery is not guaranteed. A scheduled message may be delivered repeatedly.
  • The scheduled time is the time when the server starts to deliver a message to a consumer. If messages are stacked on the consumer, the scheduled message is delivered after the stacked messages, and cannot be delivered exactly at the configured time.
  • Due to a potential time difference between the client and server, the actual delivery time may be different from the delivery time set by the client. The server time is used.
  • Messages are retained for two days after the scheduled delivery time. For example, if a scheduled message is not retrieved in five days as scheduled, it is deleted on the seventh day.
  • Scheduled messages occupy about three times the storage space of normal messages. If you use a large number of scheduled messages, pay attention to the storage space usage.

Preparing the Environment

  1. Run the following command to check whether Go has been installed:
    go version

    If the following information is displayed, Go has been installed:

    go version go1.16.5 linux/amd64

    If Go is not installed, download and install it.

  2. Add the following code to go.mod to add the dependency:
    module rocketmq-example-go
    go 1.13
    require (
    	github.com/apache/rocketmq-client-go/v2 v2.1.1

Delivering Scheduled Messages

The following code is an example. Replace the information in bold with the actual values.

package main

import (

func main() {
	p, _ := rocketmq.NewProducer(
	err := p.Start()
	if err != nil {
		fmt.Printf("start producer error: %s", err.Error())
	msg := primitive.NewMessage("test", []byte("Hello RocketMQ Go Client!"))
	msg.WithProperty("__STARTDELIVERTIME", strconv.FormatInt(time.Now().UnixMilli()+3000, 10))
	res, err := p.SendSync(context.Background(), msg)

	if err != nil {
		fmt.Printf("send message error: %s\n", err)
	} else {
		fmt.Printf("send message success: result=%s\n", res.String())
	err = p.Shutdown()
	if err != nil {
		fmt.Printf("shutdown producer error: %s", err.Error())

The parameters in the example code are described as follows. For details about how to obtain the parameter values, see Collecting Connection Information.

  • instance metadata address and port.
  • test: topic name.