All Products
Search

This Product

    Simple Message Queue (formerly MNS):Subscribe

    Document Center

    Simple Message Queue (formerly MNS):Subscribe

    Last Updated:Jun 30, 2026

    Calls the Subscribe operation to create a subscription for a topic.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    mns:Subscribe

    update

    *Subscription

    acs:mns:{#regionId}:{#accountId}:/topics/{#TopicName}/subscriptions/{#SubscriptionName}
    • mns:PushType
    		 None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    TopicName

    string

    Yes

    The name of the topic.

    topic****1
    SubscriptionName

    string

    Yes

    The name of the subscription.

    testSubscription

    PushType

    string

    Yes

    Push type of the subscription

    Valid values:

    • http: HTTP/HTTPS push. Pushes messages to a specified HTTP or HTTPS callback URL.

    • queue: Queue push. Pushes messages to a specified SMQ queue.

    • dm: Email push. Sends notifications through DirectMail. You must also set the DmAttributes and StsRoleArn parameters.

    • dysms: SMS push. Sends notifications through Alibaba Cloud Short Message Service. You must also set the DysmsAttributes parameter.

    • fc: Function Compute push. Pushes messages to Alibaba Cloud Function Compute (FC).

    • eventbus: EventBridge push. Pushes messages to an EventBridge event bus.

    Note: The following values are deprecated and are only used for compatibility with legacy subscriptions:

    • mpush: Mobile push.

    • alisms: Legacy SMS.

    • email: Legacy email. Use dm instead.

    • kafka: Kafka push type is deprecated.

    queue
    Endpoint

    string

    Yes

    Endpoint address for receiving messages

    The format varies depending on the value of PushType:

    • PushType=http: An HTTP/HTTPS callback URL, such as http://example.com/callback or https://example.com/callback.

    • PushType=queue: The ARN of the destination queue, in the format acs:mns:{RegionId}:{Alibaba Cloud account ID}:queues/{QueueName}.

    • PushType=dm: The email push endpoint, in the fixed format smq-ep:dm:{Alibaba Cloud account ID}:__dynamic. Replace {Alibaba Cloud account ID} with your Alibaba Cloud account ID.

    • PushType=dysms: The SMS push endpoint, in the format smq-ep:dysms:{Alibaba Cloud account ID}:{PhoneNumber}.

    • PushType=kafka: The Kafka push endpoint. The Kafka push type is deprecated.

    • PushType=fc: The Function Compute endpoint, in the format acs:fc:{RegionId}:{Alibaba Cloud account ID}:services/{ServiceName}/functions/{FunctionName}.

    • PushType=eventbus: The EventBridge endpoint, in the format acs:eventbridge:{RegionId}:{Alibaba Cloud account ID}:eventbus/{EventBusName}.

    http://*****.com/uri1/xxx
    NotifyStrategy

    string

    No

    The retry strategy when an error occurs while pushing messages to the endpoint. Valid values:

    • BACKOFF_RETRY: backoff retry.

    • EXPONENTIAL_DECAY_RETRY: exponential decay retry.

    BACKOFF_RETRY
    NotifyContentFormat

    string

    No

    Format of the pushed message content

    Valid values:

    • XML: The message body is pushed in XML format. This is the default value.

    • JSON: The message body is pushed in JSON format.

    • SIMPLIFIED: Only the raw message body content is pushed, without SMQ metadata wrapping.

    XML
    MessageTag

    string

    No

    The tag used for message filtering in this subscription. Only messages with a matching tag are pushed. The value is a string of up to 16 characters.

    By default, no message filtering is applied.

    important
    DlqPolicy

    object

    No

    The dead-letter queue policy.

    Enabled

    boolean

    No

    Specifies whether to enable dead-letter message delivery.

    true
    DeadLetterTargetQueue

    string

    No

    The destination queue for dead-letter message delivery.

    deadLetterTargetQueue
    TenantRateLimitPolicy

    object

    No

    The throttling policy.

    Enabled

    boolean

    No

    Specifies whether to enable the throttling policy. Valid values: true and false.

    MaxReceivesPerSecond

    integer

    No

    The maximum number of pushes or consumptions per second.

    50
    StsRoleArn

    string

    No

    The ARN of the RAM role assumed by the service. The format is acs:ram::{Alibaba Cloud account ID}:role/{RoleName}. Replace {Alibaba Cloud account ID} with the Alibaba Cloud account ID that calls the API operation.

    acs:ram::1234567890:role/AliyunMNSNotificationRole
    DmAttributes

    object

    No

    The email push attributes. This parameter is required when PushType is set to dm. The value is in JSON format and contains the following fields:

    • AccountName: The sender address configured in DirectMail (such as notify@example.com).

    • Subject: The email subject.

    AccountName

    string

    No

    The sender address.

    notify@example.com
    Subject

    string

    No

    The email subject.

    notify
    DysmsAttributes

    object

    No

    The SMS push attributes. This parameter is required when PushType is set to alisms. The value is in JSON format and contains the following fields:

    • TemplateCode: The SMS template code, which can be obtained from the Short Message Service console.

    • SignName: The SMS signature name.

    TemplateCode

    string

    No

    The SMS template code.

    123456
    SignName

    string

    No

    The SMS signature name.

    阿里云短信测试专用
    KafkaAttributes

    object

    No

    The Kafka push type is deprecated.

    BusinessMode

    string

    No

    The Kafka push type is deprecated.

    Default empty string

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    The request ID.

    06273500-249F-5863-121D-74D51123****
    Code

    integer

    The response code.

    200
    Status

    string

    The response status.

    Success
    Message

    string

    The response message.

    operation success
    Success

    boolean

    Indicates whether the request was successful.

    true
    Data

    string

    The response data.

    {'Code': 200, 'Success': True}

    Examples

    Success response

    JSON format

    {
  "RequestId": "06273500-249F-5863-121D-74D51123****",
  "Code": 200,
  "Status": "Success",
  "Message": "operation success",
  "Success": true,
  "Data": "{'Code': 200, 'Success': True}"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.