Sends a message to a queue.

Authorization information

By default, you can use only an Alibaba Cloud account to call this operation. You can use a RAM user to call this operation only after you grant the required permissions to the RAM user. The following table describes the authorization information of this operation. For more information, see Permission policies and examples.

Name Value
API SendMessage
Action mns:SendMessage
Resource acs:mns:$region:$accountid:/queues/$queueName/messages

Usage notes

  • You can call this operation to send a message to a queue. A standard message is immediately consumed after the message is sent to the queue. If you do not want the message to be immediately consumed, you can specify the DelaySeconds parameter when you send the message. If you set the DelaySeconds parameter to a value that is greater than 0, the initial status of the message is Delayed after the message is sent to a queue. The message cannot be consumed until the period specified by the DelaySeconds parameter ends and the status of the message changes toActive.
  • If the value of the DelaySeconds parameter for the message is different from the value of the DelaySeconds parameter for the queue, the value of the DelaySeconds parameter for the message takes effect.
  • Before you call this API operation to send a message, encode the message body by using Base64. This prevents unexpected errors due to special characters.

Request

A request consists of the following parts:

  • Request line

    POST /queues/$queueName/messages HTTP/1.1

  • Operation-specific request headers

    None.

  • Request Body

    The request body is in the XML format and contains the parameters of the message.

    Parameter Type Required Example Description
    MessageBody String Yes This is a test message The body of the message.
    DelaySeconds Integer No 60 The delay period after which the message sent to the queue can be consumed.

    Valid values: 0 to 604800. Unit: seconds.

    Default value: 0.

    Priority Integer No 1 The priority of the message. A message with a higher priority is consumed earlier.

    Valid values: 1 to 16. A smaller value indicates a higher priority.

    Default value: 8.

Response

A response consists of the following parts:

  • HTTP Status Code

    HTTP/1.1 201 Created

  • Operation-specific response headers

    None.

  • Response Body

    The response body is in the XML format. The MessageId and MessageBodyMD5 parameters of the message are returned.

    Parameter Type Example Description
    MessageId String 5F290C926D472878-2-14D9529A8FA-20000**** The ID of the message. The message ID is unique in the queue.
    MessageBodyMD5 String C5DD56A39F5F7BB8B3337C6D11B6**** The MD5 hash of the message body.
    ReceiptHandle String 1-ODU4OTkzNDU5My0xNDM1MTk3NjAwLTItNg== The receipt handle that was returned after the delayed message was received.

Examples

Sample requests

POST /queues/$queueName/messages HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 18 Mar 2012 12:00:00 GMT
Content-Length:500
Content-Type:text/xml;charset=utf-8
x-mns-version: 2015-06-06
Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEX****

<?xml version="1.0" encoding="UTF-8"?>
<Message xmlns="http://mns.aliyuncs.com/doc/v1/">
    <MessageBody>This is a test message</MessageBody>
    <DelaySeconds>60</DelaySeconds>
    <Priority>1</Priority>
</Message>            

Sample responses

HTTP/1.1 201 Created
Content-Length:120
Content-Type:text/xml;charset=utf-8
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-14D9529****-200000001</MessageId>
<MessageBodyMD5>C5DD56A39F5F7BB8B3337C6D11B6****</MessageBodyMD5>
<ReceiptHandle>1-ODU4OTkzNDU5My0xNDM1MTk3NjAwLTItNg==</ReceiptHandle>
</Message>           

Error codes

Error code Error message The HTTP status code Description
QueueNotExist The queue name you provided is not exist. 404 The error message returned because the specified queue does not exist. Create a queue.
MalformedXML The XML you provided was not well-formed. 400 The error message returned because the format of the XML file is invalid.
InvalidArgument The value of Element should between Low and High seconds/bytes. 400 The error message returned because the value of the parameter is invalid. You must specify a valid value as prompted.