All Products
Document Center


Last Updated: Oct 08, 2019



This API is used to create a subscription to a topic.

A subscription name is a string of no more than 256 characters, including letters, numbers, and hyphens (-). It must start with a letter or number.

An endpoint must be specified for the created subscription; otherwise, the subscription is invalid.


A request includes the following parts:

  • Request line

    PUT /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1 .

  • Special request header

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

  • Request Body

    The request body is in XML format and contains the created subscription attributes.

Parameter name Description Parameter value Required/Optional
Endpoint Terminal address of the message recipient for the created subscription Currently, four types of endpoints are supported: 1. HttpEndpoint, which must be prefixed with “http://“; 2. QueueEndpoint, in the format of acs:mns:{REGION}:{AccountID}:queues/{QueueName}; 3. MailEndpoint, in the format of mail:directmail:{MailAddress}; 4. SmsEndpoint, in the format of sms:directsms:anonymous or sms:directsms:{Phone}. Required
FilterTag Message filter tag in the created subscription (Only messages with consistent tags are pushed.) The value is a string of no more than 16 characters. The default value is no message filter. Optional
NotifyStrategy Retry policy that will be applied when an error occurs during message push to the endpoint BACKOFF_RETRY or EXPONENTIAL_DECAY_RETRY; default value:BACKOFF_RETRY. For details about retry policies, refer to Basic Concepts/NotifyStrategy. Optional
NotifyContentFormat Format of the message content pushed to the endpoint XML, JSON, or SIMPLIFIED; default value: XML. For details about message formats, refer to Basic Concepts/NotifyContentFormat. Optional


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

  • HTTP Status Code

    HTTP/1.1 201

    Duplicate subscription names are not allowed for the same subscriber of the same topic. If the created subscription has the same name and attributes as an existing subscription, Status Code 204 (No Content) is returned; if only the names are the same but the attributes are different, Status Code 409 (Conflict) is returned.

  • Special response header

Parameter name Description
Location Returned URL of the successfully created subscription, in the following format: http://$$TopicName/subscriptions/$SubscriptionName

For the other response headers, refer to Call Method/Public Parameters.

  • Response Body


Special Error

Error code Error message Status code
SubscriptionNameLengthError Subscription name length is out of range, should be between 1 and 256. 400
SubscriptionNameInvalid The subscription you provided is invalid. SubscriptionName should start with alpha or digit, and contain only alpha, digit or -. 400
SubscriptionAlreadyExist The subscription you want to create already exists. 409
EndpointInvalid The endpoint you provided is invalid. 400
InvalidArgument The length of filter tag should be between 1 and 16. 400

Request example:

  1. PUT /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1
  2. Host: $
  3. Date: Tue, 08 Dec 2015 06:06:46 GMT
  4. Authorization:MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
  5. x-mns-version: 2015-06-06
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Subscription xmlns="">
  8. <Endpoint></Endpoint>
  9. <NotifyStrategy>BACKOFF_RETRY</NotifyStrategy>
  10. <NotifyContentFormat>SIMPLIFIED</NotifyContentFormat>
  11. <FilterTag>important</FilterTag>
  12. </Subscription>

Response example:

  1. HTTP/1.1 201
  2. x-mns-request-id:56667376B2B71C9C16000025
  3. x-mns-version: 2015-06-06
  4. Location: http://$$TopicName/subscriptions/$SubscriptionName