All Products
Search

This Product

    Simple Message Queue (formerly MNS):ReceiveMessage

    Document Center

    Simple Message Queue (formerly MNS):ReceiveMessage

    Last Updated:Mar 11, 2026

    Receives a message from a queue and sets it to the Inactive state for the duration of the queue's VisibilityTimeout period. Call DeleteMessage before this period expires to permanently remove the message. If not deleted in time, the message returns to the Active state and becomes available for consumption again.

    Authorization information

    By default, only an Alibaba Cloud account can call this operation. To call it as a Resource Access Management (RAM) user, grant the required permissions to the RAM user. For more information, see Permission policies and examples.

    ItemValue
    API operationReceiveMessage
    Actionmns:ReceiveMessage
    Resourceacs:mns:$region:$accountid:/queues/$queueName/messages

    Request syntax

    GET /queues/$queueName/messages?waitseconds=10 HTTP/1.1

    This operation has no operation-specific request headers or request body.

    URI parameters

    ParameterTypeRequiredExampleDescription
    waitsecondsIntegerNo0Maximum wait time in seconds when no message is available. If omitted, the queue's PollingWaitSeconds value applies. For more information, see CreateQueue.

    Long polling behavior

    When waitseconds is set (or the queue's default PollingWaitSeconds applies), the server holds the connection until a message arrives or the wait period expires. Any message written to the queue during this period is delivered immediately.

    We recommend that you reduce the number of concurrent long polling requests and specify an appropriate waiting period. For more information, see Short polling and long polling.

    Note

    Simple Message Queue (SMQ, formerly MNS) limits concurrent long polling requests based on the total number of requests, wait periods, and source IP addresses. When this limit is exceeded, SMQ returns a 404 MessageNotExist error immediately without holding the request, and standard request charges apply. To raise this limit, submit a ticket.

    Response

    HTTP status code

    HTTP/1.1 200 OK

    This operation has no operation-specific response headers.

    Response body

    The response body is in XML format and contains:

    • The message body and its MD5 hash

    • A unique message ID

    • A receipt handle for deleting or modifying the message while it is Inactive

    • Timestamps: enqueue time, first dequeue time, and next visible time

    • A dequeue count

    ParameterTypeExampleDescription
    MessageIdString5F290C926D472878-2-14D9529A8FA-20000\*\*\*\*Unique identifier of the message within the queue.
    ReceiptHandleString1-ODU4OTkzNDU5My0xNDMyNzI3ODI3LTItOA==Handle for deleting or modifying the message while it is Inactive. Use this value when you call DeleteMessage or ChangeMessageVisibility. Valid until NextVisibleTime.
    MessageBodyStringThis is a test messageContent of the message.
    MessageBodyMD5StringC5DD56A39F5F7BB8B3337C6D11B6\*\*\*\*MD5 hash of the message body.
    EnqueueTimeLong1250700979248Time when the message was sent to the queue. UNIX timestamp in milliseconds since January 1, 1970, 00:00:00 UTC.
    NextVisibleTimeLong1250700799348Time when the message becomes visible again if not deleted. UNIX timestamp in milliseconds since January 1, 1970, 00:00:00 UTC.
    FirstDequeueTimeLong1250700779318Time when the message was first consumed. UNIX timestamp in milliseconds since January 1, 1970, 00:00:00 UTC.
    DequeueCountInteger1Number of times the message has been consumed.

    Examples

    Sample request

    GET /queues/$queueName/messages 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
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>5F290C926D472878-2-14D9529A8FA-20000****</MessageId>
    <ReceiptHandle>1-ODU4OTkzNDU5My0xNDMyNzI3ODI3LTItOA==</ReceiptHandle>
    <MessageBodyMD5>C5DD56A39F5F7BB8B3337C6D11B6****</MessageBodyMD5>
    <MessageBody>This is a test message</MessageBody>
    <EnqueueTime>1250700979248</EnqueueTime>
    <NextVisibleTime>1250700799348</NextVisibleTime>
    <FirstDequeueTime>1250700779318</FirstDequeueTime>
    <DequeueCount>1</DequeueCount>
    <Priority>8</Priority>
</Message>

    Error codes

    Error codeError messageHTTP status codeDescription
    QueueNotExistThe queue name you provided is not exist.404The specified queue does not exist. Create a queue before calling this operation.
    MessageNotExistMessage not exist.404No visible message exists in the queue.

    What's next