All Products
Search

This Product

    Simple Message Queue (formerly MNS):Simple Message Queue (formerly MNS): PeekMessage

    Document Center

    Simple Message Queue (formerly MNS):Simple Message Queue (formerly MNS): PeekMessage

    Last Updated:Mar 11, 2026

    Views a message in a queue without changing its state.

    Description

    PeekMessage retrieves a message from the specified queue for inspection only. Unlike ReceiveMessage, this operation does not change the message state -- the message remains in the Active state and is still available to other consumers.

    For each message returned, the response includes:

    • The message body and its MD5 hash

    • The message ID, unique within the queue

    • The message priority

    • The enqueue timestamp

    • The first dequeue timestamp and total dequeue count

    PeekMessage does not return a ReceiptHandle. Without a receipt handle, you cannot delete the message or change its visibility timeout. To consume and remove a message from the queue, use ReceiveMessage instead.

    PeekMessage vs. ReceiveMessage

    BehaviorPeekMessageReceiveMessage
    Message state after callRemains ActiveChanges to Inactive
    Visibility to other consumersStill visibleHidden for the VisibilityTimeout period
    ReceiptHandle in responseNoYes
    Can delete message after callNoYes (with ReceiptHandle)

    Authorization

    By default, only Alibaba Cloud accounts can call this operation. RAM users must be granted the required permissions. For more information, see Permission policies and examples.

    ItemValue
    API operationPeekMessage
    Actionmns:PeekMessage
    Resourceacs:mns:$region:$accountid:/queues/$queueName/messages

    Request syntax

    GET /queues/$queueName/messages?peekonly=true HTTP/1.1

    URI parameters

    ParameterRequiredDescription
    peekonlyYesMust be true. Views the message without changing its state.

    Request headers

    No operation-specific headers. Only common request headers are required.

    Request body

    None.

    Response

    HTTP status code

    A successful request returns HTTP/1.1 200 OK.

    Response headers

    No operation-specific headers. Only common response headers are returned.

    Response body

    The response body is in XML format and contains the following elements:

    ParameterTypeExampleDescription
    MessageIdStringD6D5F7C9C12D14A4-1-14D953EFC72-20000****The unique message ID within the queue.
    MessageBodyStringThis is a test message.The message body.
    MessageBodyMD5StringF9360F391579E71CA77BC5D50242****The MD5 hash of the message body.
    EnqueueTimeLong1250700979248The time when the message was sent to the queue. UNIX timestamp in milliseconds since January 1, 1970, 00:00:00 UTC.
    FirstDequeueTimeLong1250700979348The time when the message was first dequeued. UNIX timestamp in milliseconds since January 1, 1970, 00:00:00 UTC. If DequeueCount is 0, this value equals EnqueueTime.
    DequeueCountInteger5The total number of times the message has been dequeued.
    PriorityInteger8The message priority.
    Unlike ReceiveMessage, the PeekMessage response does not include a ReceiptHandle element.

    Examples

    Sample request

    GET /queues/$queueName/messages?peekonly=true HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 28 May 2012 22:32:00 GMT
x-mns-version: 2015-06-06
Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXA****

    Sample response

    HTTP/1.1 200 OK
Connection: close
Content-Type: text/xml;charset=utf-8
Content-Length: 500
x-mns-request-id: 512B2A634403E52B1956****
x-mns-version: 2015-06-06
    <?xml version="1.0" encoding="UTF-8"?>
<Message xmlns="http://mns.aliyuncs.com/doc/v1/">
    <MessageId>D6D5F7C9C12D14A4-1-14D953EFC72-20000****</MessageId>
    <MessageBodyMD5>F9360F391579E71CA77BC5D50242****</MessageBodyMD5>
    <MessageBody>This is a test message.</MessageBody>
    <EnqueueTime>1250700979248</EnqueueTime>
    <FirstDequeueTime>1250700979348</FirstDequeueTime>
    <DequeueCount>5</DequeueCount>
    <Priority>8</Priority>
</Message>

    Error codes

    The following table lists the error codes specific to this operation. For common error codes, see Error responses.

    Error codeHTTP status codeError messageDescription
    QueueNotExist404The queue name you provided is not exist.The specified queue does not exist. Verify the queue name and region, or create the queue first.
    MessageNotExist404Message not exist.No messages are available to peek. The queue is empty, or all messages are in the Inactive state (consumed but not yet deleted).