AWS SDK for JavaScript
Developer Guide for SDK v2

Managing Subscriptions in Amazon SNS

JavaScript code example that applies to Node.js execution

This Node.js code example shows:

  • How to list all subscriptions to an Amazon SNS topic.

  • How to subscribe an email address, an application endpoint, or an AWS Lambda function to an Amazon SNS topic.

  • How to unsubscribe from Amazon SNS topics.

The Scenario

In this example, you use a series of Node.js modules to publish notification messages to Amazon SNS topics. The Node.js modules use the SDK for JavaScript to manage topics using these methods of the AWS.SNS client class:

Prerequisite Tasks

To set up and run this example, you must first complete these tasks:

Listing Subscriptions to a Topic

In this example, use a Node.js module to list all subscriptions to an Amazon SNS topic. Create a Node.js module with the file name sns_listsubscriptions.js. Configure the SDK as previously shown.

Create an object containing the TopicArn parameter for the topic whose subscriptions you want to list. Pass the parameters to the listSubscriptionsByTopic method of the AWS.SNS client class. To call the listSubscriptionsByTopic method, create a promise for invoking an Amazon SNS service object, passing the parameters object. Then handle the response in the promise callback.

/// Load the AWS SDK for Node.js var AWS = require('aws-sdk'); // Set region AWS.config.update({region: 'REGION'}); // Create promise and SNS service object var subslistPromise = new AWS.SNS({apiVersion: '2010-03-31'}).listSubscriptionsByTopic({TopicArn : TOPIC_ARN}).promise(); // Handle promise's fulfilled/rejected states subslistPromise.then( function(data) { console.log(data); }).catch( function(err) { console.error(err, err.stack); } );

To run the example, type the following at the command line.

node sns_listsubscriptions.js

This sample code can be found here on GitHub.

Subscribing an Email Address to a Topic

In this example, use a Node.js module to subscribe an email address so that it receives SMTP email messages from an Amazon SNS topic. Create a Node.js module with the file name sns_subscribeemail.js. Configure the SDK as previously shown.

Create an object containing the Protocol parameter to specify the email protocol, the TopicArn for the topic to subscribe to, and an email address as the message Endpoint. Pass the parameters to the subscribe method of the AWS.SNS client class. You can use the subscribe method to subscribe several different endpoints to an Amazon SNS topic, depending on the values used for parameters passed, as other examples in this topic will show.

To call the subscribe method, create a promise for invoking an Amazon SNS service object, passing the parameters object. Then handle the response in the promise callback.

// Load the AWS SDK for Node.js var AWS = require('aws-sdk'); // Set region AWS.config.update({region: 'REGION'}); // Create subscribe/email parameters var params = { Protocol: 'EMAIL', /* required */ TopicArn: 'TOPIC_ARN', /* required */ Endpoint: 'EMAIL_ADDRESS' }; // Create promise and SNS service object var subscribePromise = new AWS.SNS({apiVersion: '2010-03-31'}).subscribe(params).promise(); // Handle promise's fulfilled/rejected states subscribePromise.then( function(data) { console.log("Subscription ARN is " + data.SubscriptionArn); }).catch( function(err) { console.error(err, err.stack); });

To run the example, type the following at the command line.

node sns_subscribeemail.js

This sample code can be found here on GitHub.

Subscribing an Application Endpoint to a Topic

In this example, use a Node.js module to subscribe a mobile application endpoint so it receives notifications from an Amazon SNS topic. Create a Node.js module with the file name sns_subscribeapp.js. Configure the SDK as previously shown.

Create an object containing the Protocol parameter to specify the application protocol, the TopicArn for the topic to subscribe to, and the ARN of a mobile application endpoint for the Endpoint parameter. Pass the parameters to the subscribe method of the AWS.SNS client class.

To call the subscribe method, create a promise for invoking an Amazon SNS service object, passing the parameters object. Then handle the response in the promise callback.

// Load the AWS SDK for Node.js var AWS = require('aws-sdk'); // Set region AWS.config.update({region: 'REGION'}); // Create subscribe/email parameters var params = { Protocol: 'application', /* required */ TopicArn: 'TOPIC_ARN', /* required */ Endpoint: 'MOBILE_ENDPOINT_ARN' }; // Create promise and SNS service object var subscribePromise = new AWS.SNS({apiVersion: '2010-03-31'}).subscribe(params).promise(); // Handle promise's fulfilled/rejected states subscribePromise.then( function(data) { console.log("Subscription ARN is " + data.SubscriptionArn); }).catch( function(err) { console.error(err, err.stack); });

To run the example, type the following at the command line.

node sns_subscribeapp.js

This sample code can be found here on GitHub.

Subscribing a Lambda Function to a Topic

In this example, use a Node.js module to subscribe an AWS Lambda function so it receives notifications from an Amazon SNS topic. Create a Node.js module with the file name sns_subscribelambda.js. Configure the SDK as previously shown.

Create an object containing the Protocol parameter, specifying the lambda protocol, the TopicArn for the topic to subscribe to, and the ARN of an AWS Lambda function as the Endpoint parameter. Pass the parameters to the subscribe method of the AWS.SNS client class.

To call the subscribe method, create a promise for invoking an Amazon SNS service object, passing the parameters object. Then handle the response in the promise callback.

// Load the AWS SDK for Node.js var AWS = require('aws-sdk'); // Set region AWS.config.update({region: 'REGION'}); // Create subscribe/email parameters var params = { Protocol: 'lambda', /* required */ TopicArn: 'TOPIC_ARN', /* required */ Endpoint: 'LAMBDA_FUNCTION_ARN' }; // Create promise and SNS service object var subscribePromise = new AWS.SNS({apiVersion: '2010-03-31'}).subscribe(params).promise(); // Handle promise's fulfilled/rejected states subscribePromise.then( function(data) { console.log("Subscription ARN is " + data.SubscriptionArn); }).catch( function(err) { console.error(err, err.stack); });

To run the example, type the following at the command line.

node sns_subscribelambda.js

This sample code can be found here on GitHub.

Unsubscribing from a Topic

In this example, use a Node.js module to unsubscribe an Amazon SNS topic subscription. Create a Node.js module with the file name sns_unsubscribe.js. Configure the SDK as previously shown.

Create an object containing the SubscriptionArn parameter, specifying the ARN of the subscription to unsubscribe. Pass the parameters to the unsubscribe method of the AWS.SNS client class.

To call the unsubscribe method, create a promise for invoking an Amazon SNS service object, passing the parameters object. Then handle the response in the promise callback.

// Load the AWS SDK for Node.js var AWS = require('aws-sdk'); // Set region AWS.config.update({region: 'REGION'}); // Create promise and SNS service object var subscribePromise = new AWS.SNS({apiVersion: '2010-03-31'}).subscribe({SubscriptionArn : TOPIC_SUBSCRIPTION_ARN}).promise(); // Handle promise's fulfilled/rejected states subscribePromise.then( function(data) { console.log(data); }).catch( function(err) { console.error(err, err.stack); });

To run the example, type the following at the command line.

node sns_unsubscribe.js

This sample code can be found here on GitHub.