Creates a subscription.


You can call this operation to create a subscription. A subscription name can be up to 255 characters in length and contain letters, digits, and hyphens (-). It must start with a letter or digit.

You must specify an endpoint when you create a subscription. Otherwise, the subscription is invalid.


A request consists of the following parts:

  • Request line

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

  • Operation-specific request headers

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

  • Request Body

    The request body is in the XML format. The request body includes the following parameters.

    Parameter Required Description Value
    Endpoint Yes The endpoint that is used to receive messages.

    You can specify the following types of endpoints:

    • HttpEndpoint. An HTTP endpoint must start with http://.
    • QueueEndpoint. Syntax: acs:mns:{REGION}:{AccountID}:queues/{QueueName}.
    • MailEndpoint. Syntax: mail:directmail:{MailAddress}.
    • SmsEndpoint. Syntax: sms:directsms:anonymous or sms:directsms:{Phone}.
    FilterTag No The tag that is used to filter messages. Only the messages that have the same tag can be pushed. A tag can be a maximum of 16 characters in length. By default, no tag is specified to filter messages.
    NotifyStrategy No The retry policy that is applied if an error occurs during message delivery to the endpoint. Valid values: BACKOFF_RETRY and EXPONENTIAL_DECAY_RETRY. Default value: BACKOFF_RETRY. For more information, see NotifyStrategy.
    NotifyContentFormat No The format of the message that is pushed to the endpoint. Valid values: XML, JSON, and SIMPLIFIED. Default value: XML. For more information, see NotifyContentFormat.


A response consists of the following parts:

  • HTTP Status Code

    HTTP/1.1 201

    In a topic, each subscription name must be unique. If you create a subscription that already exists, errors may occur. For example, if the parameters of two subscriptions are the same, the HTTP status code 204 is returned. If the parameters of the two subscriptions are different, the HTTP status code 409 is returned.

  • Operation-specific response headers
    Parameter Description
    Location The URL of the subscription that is created. Syntax: http://$$TopicName/subscriptions/$SubscriptionName.

    For information about common request headers, see Common parameters.

  • Response Body



Sample requests

PUT /topics/$TopicName/subscriptions/$SubscriptionName HTTP/1.1
Host: $
Date: Tue, 08 Dec 2015 06:06:46 GMT
Authorization:MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+****AMPLE=
x-mns-version: 2015-06-06

<?xml version="1.0" encoding="utf-8"?>
<Subscription xmlns="">

Sample success responses

HTTP/1.1 201
x-mns-version: 2015-06-06
Location: http://$$TopicName/subscriptions/$SubscriptionName

Special Error

Error code Error message HTTP status code
SubscriptionNameLengthError Subscription name length is out of range, should be between 1 and 255. 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