Publishes a message to a specified topic. After the message is published to the topic, MNS pushes the message to the specified endpoints.

Request

Each request consists of the following parts:

  • Request line

    POST /topics/$TopicName/messages HTTP/1.1

  • Operation-specific request headers

    None. For more information about common request headers, see Common parameters. For more information about signatures, see Sign requests.

  • Request Body

    The request body is in the XML format.

To push a message to an email address or a phone number, you must configure the attributes of the message.

  • If you want to push a message to an email address, the DirectMail attribute must be included in the request.

    The DirectMail attribute must contain the following parameters and must be in the JSON format.

    Parameter Required Type Description
    AccountName Yes String The email address of the sender.
    Subject Yes String The subject of the email.
    AddressType Yes Number Valid values: 0 and 1.
    IsHtml Yes Number Specifies whether to use the HTML format to process the email. Valid values: 0 and 1.
    ReplyToAddress Yes Boolean Valid values: 0 and 1.
  • If you want to push a message to a phone number, the DirectSMS attribute must be included in the request.

    The DirectSMS attribute must include the following parameters and must be in the JSON format.

    Parameter Required Description
    FreeSignName Yes The signature of the SMS message.
    TemplateCode Yes The ID of the SMS message template.
    Type Yes Specifies whether to send a message or send multiple messages. Valid values: singleContent and multiContent. If you set this parameter to multiContent, messages are pushed only to the sms:directsms:anonymous subscriber endpoint.
    Receiver No This parameter is required if you set the Type parameter to singContent and set the subscriber endpoint to sms:directsms:anonymous. You must specify one or more mobile numbers to receive messages. If you specify multiple mobile numbers as the receivers, separate the mobile numbers with commas (,).
    SmsParams Yes The parameters of the message. The content of the parameters is in the JSON format. If you set the Type parameter to singContent, the syntax of the SmsParams parameter value is {"Parameter 1":"Value 1","Parameter 2":"Value 2"}. If you specify multiContent for the Type parameter, the syntax is {"Phone Number 1":{"Parameter 1":"Value 1","Parameter 2":"Value 2"},"Phone Number 2":{"Parameter 1":"Value 3","Parameter 2":"Value 4"}}.

Response

Each response consists of the following parts:

  • HTTP Status Code

    HTTP/1.1 201 Created

  • Operation-specific response headers

    None. For more information about common response headers, see Common parameters.

  • Response Body

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

    Parameter Description
    MessageId The ID of the message. In a topic, each message ID must be unique.
    MessageBodyMD5 The MD5 hash of the message body.

Examples

Sample requests when you publish a message to an email address

POST /topics/$TopicName/messages HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Tue, 08 Dec 2015 06:13:40 GMT
Content-Length:500
Content-Type:text/xml;charset=utf-8
Authorization: MNS 15B4D3461F177624206A:aibzWu1iDEx9LwO56+kHgA3eqmI=
x-mns-version: 2015-06-06

<? xml version="1.0" encoding="utf-8"? >
<Message xmlns="http://mns.aliyuncs.com/doc/v1/">
    <MessageBody>Base64 Encoded Result</MessageBody>
    <MessageTag>important</MessageTag>
    <MessageAttributes>
        <DirectMail>{"Subject":"TestMailSubject","AccountName":"direct_mail_account_name@aliyun-inc.com","ReplyToAddress":0,"AddressType":0,"IsHtml":0}</DirectMail>
    </MessageAttributes>
</Message>            

Sample requests when you publish multiple messages to phone numbers

POST /topics/$TopicName/messages HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Tue, 08 Dec 2015 06:13:40 GMT
Content-Length:500
Content-Type:text/xml;charset=utf-8
Authorization: MNS 15B4D3461F177624206A:aibzWu1iDEx9LwO56+kHgA3eqmI=
x-mns-version: 2015-06-06

<? xml version="1.0" encoding="utf-8"? >
<Message xmlns="http://mns.aliyuncs.com/doc/v1/">
    <MessageBody>content</MessageBody>
    <MessageAttributes>
        <DirectSMS>
        {
            "FreeSignName":"$value",
            "TemplateCode":"$value",
            "Type":"multiContent",
            "Receiver":"$num1,$num2",
            "SmsParams":"{\"$num1\":{\"$key1\":\"$value1\", \"$key2\":\"$value2\"},\"$num2\":{\"$key1\":\"$value1\",\"$key2\":\"$value2\"}}"
        }
        </DirectSMS>
    </MessageAttributes>
</Message>            

Sample success responses

HTTP/1.1 201 Created
Content-Length:120
Content-Type:text/xml;charset=utf-8
x-mns-request-id:56667514B2B71C9C1600002B
x-mns-version:2015-06-06

<? xml version="1.0" encoding="utf-8"? >
<Message xmlns="http://mns.aliyuncs.com/doc/v1/">
    <MessageId>D273CD6A89564E54-1-15180395A19-200000001</MessageId>
    <MessageBodyMD5>3AC6DD36D2D6B7283F2F490A09751BFE</MessageBodyMD5>
</Message>          

Special error

Error code Error message HTTP status code
TopicNotExist The topic you provided does not exist. 404