edit-icon download-icon

Message APIs

Last Updated: Apr 01, 2017

PublishMessage

Description

This API is used to publish a message to a specified topic. After published successfully, the message is pushed to endpoints for consumption.

Request

A request includes the following parts:

  • Request line

    POST /topics/$TopicName/messages HTTP/1.1

  • Special request header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    The request body is in XML format.

Parameter name Description Parameter value Required/Optional
MessageBody Message body Character set Required
MessageTag Message tag (used for message filter) The value is a string of no more than 16 characters. (By default, no message tag is set.) Optional
MessageAttributes Message attributes. This parameter must be set when email or SMS push is required. Character set Optional

The DirectMail attribute must be included in MessageAttributes if the push destination is MailEndpoint.

The text content of DirectMail is in JSON format and has the following fields:

  • AccountName (required, sender’s account, string).

  • Subject (required, email subject, string).

  • AddressType (required, 0 or 1).

  • IsHtml (required, whether the email content is processed in HTML format, 0 or 1).

  • ReplyToAddress (required, 0 or 1).

The DirectSMS attribute must be included in MessageAttributes if the push destination is SmsEndpoint.

The text content of DirectSMS is in JSON format and has the following fields:

  • FreeSignName (required, SMS signature).

  • TemplateCode (required, SMS template ID).

  • Type (required, singleContent or multiContent, which indicates sending a single SMS or sending SMSs in batches. If the value is multiContent, SMSs are processed only by the subscriptions with the endpoint sms:directsms:anonymous).

  1. Receiver (If Type is singleContent and the subscription endpoint is SMS:directsms:anonymous, this field takes effect and indicates the mobile number of the SMS recipient).

  2. SmsParams (required, JSON format. This field includes specific parameters. If Type is singleContent, the field format is {“parameter 1”: “Value1”, “parameter 2”: “Value2”}. If Type is multiContent, the field format is {“mobile number 1”: {“parameter 1”: “Value1”, “parameter 2”: “Value2”}, “mobile 2”: {“parameter 1”: “Value3”, “parameter 2”: “Value4”}}.)

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 201 Created

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    The returned results are in XML format and contain the MessageId and MessageBodyMD5 parameters.

Parameter name Description
MessageId message ID, which is unique within a topic
MessageBodyMD5 MD5 value of the message body

Special Error

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

Request example:

  1. POST /topics/$TopicName/messages HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 06:13:40 GMT
  4. Content-Length:500
  5. Content-Type:text/xml;charset=utf-8
  6. Authorization: MNS 15B4D3461F177624206A:aibzWu1iDEx9LwO56+kHgA3eqmI=
  7. x-mns-version: 2015-06-06
  8. <?xml version="1.0" encoding="utf-8"?>
  9. <Message xmlns="http://mns.aliyuncs.com/doc/v1/">
  10. <MessageBody>Base64 Encoded Result</MessageBody>
  11. <MessageTag>important</MessageTag>
  12. <MessageAttributes>
  13. <DirectMail>{"Subject":"TestMailSubject","AccountName":"direct_mail_account_name@aliyun-inc.com","ReplyToAddress":0,"AddressType":0,"IsHtml":0}</DirectMail>
  14. </MessageAttributes>
  15. </Message>

Response example:

  1. HTTP/1.1 201 Created
  2. Content-Length:120
  3. Content-Type:text/xml;charset=utf-8
  4. x-mns-request-id:56667514B2B71C9C1600002B
  5. x-mns-version:2015-06-06
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Message xmlns="http://mns.aliyuncs.com/doc/v1/">
  8. <MessageId>D273CD6A89564E54-1-15180395A19-200000001</MessageId>
  9. <MessageBodyMD5>3AC6DD36D2D6B7283F2F490A09751BFE</MessageBodyMD5>
  10. </Message>
Thank you! We've received your feedback.