Simple Notification Service (SNS)

Simple Notification Service (SNS) is a serverless messaging service that can distribute a massive number of messages to multiple subscribers and can be used to send messages to mobile devices, email addresses, and HTTP(s) endpoints. SNS employs the Publish/Subscribe, an asynchronous messaging pattern that decouples services that produce events from services that process events.

LocalStack supports SNS via the Community offering, allowing you to use the SNS APIs in your local environment to coordinate the delivery of messages to subscribing endpoints or clients. The supported APIs are available on our API coverage page, which provides information on the extent of SNS’s integration with LocalStack.

Getting started

This guide is intended for users who wish to get more acquainted with SNS over LocalStack. It assumes you have basic knowledge of the AWS CLI (and our awslocal wrapper script).

Start your LocalStack container using your preferred method. We will demonstrate how to create an SNS topic, publish messages, and subscribe to the topic.

Create an SNS topic

To create an SNS topic, use the CreateTopic API. Run the following command to create a topic named localstack-topic:

$ awslocal sns create-topic --name localstack-topic

You can set the SNS topic attribute using the SNS topic you created previously by using the SetTopicAttributes API. Run the following command to set the DisplayName attribute for the topic:

$ awslocal sns set-topic-attributes \
   --topic-arn arn:aws:sns:us-east-1:000000000000:localstack-topic \
   --attribute-name DisplayName \
   --attribute-value MyTopicDisplayName

You can list all the SNS topics using the ListTopics API. Run the following command to list all the SNS topics:

$ awslocal sns list-topics

Get attributes and publish messages to SNS topic

You can get attributes for a single SNS topic using the GetTopicAttributes API. Run the following command to get the attributes for the SNS topic:

$ awslocal sns get-topic-attributes \
   --topic-arn arn:aws:sns:us-east-1:000000000000:localstack-topic

You can change the topic-arn to the ARN of the SNS topic you created previously.

To publish messages to the SNS topic, create a new file named messages.txt in your current directory and add some content. Run the following command to publish messages to the SNS topic using the Publish API:

$ awslocal sns publish \
   --topic-arn "arn:aws:sns:us-east-1:000000000000:localstack-topic" \
   --message file://message.txt

Subscribing to SNS topic and setting subscription attributes

You can subscribe to the SNS topic using the Subscribe API. Run the following command to subscribe to the SNS topic:

$ awslocal sns subscribe \
   --topic-arn arn:aws:sns:us-east-1:000000000000:localstack-topic \
   --protocol email \
   --notification-endpoint test@gmail.com

You can configure the SNS Subscription attributes, using the SubscriptionArn from the previous step. Run the following command to set the RawMessageDelivery attribute for the subscription:

$ awslocal sns set-subscription-attributes \
   --subscription-arn arn:aws:sns:us-east-1:000000000000:test-topic:b6f5e924-dbb3-41c9-aa3b-589dbae0cfff \
   --attribute-name RawMessageDelivery --attribute-value true

You can list all the SNS subscriptions using the ListSubscriptions API. Run the following command to list all the SNS subscriptions:

$ awslocal sns list-subscriptions

Accessing published Platform Messages

For testing purposes, LocalStack retains all messages published to a platform endpoint in memory, making it easy to retrieve them. To learn more about SNS mobile push notifications, refer to the AWS documentation on SNS mobile push notifications.

You can access these messages in JSON format through the GET /_aws/sns/platform-endpoint-messages. To retrieve specific messages, you can use query parameters to filter by accountId, region, and endpointArn.

Query parameters

Response format and attributes

In this example, we will create a platform endpoint in SNS and publish a message to it. Run the following commands to create a platform endpoint:

$ awslocal sns create-platform-application --name app-test --platform APNS --attributes {}
{
    "PlatformApplicationArn": "arn:aws:sns:us-east-1:000000000000:app/APNS/app-test"
}

$ awslocal sns create-platform-endpoint --platform-application-arn "arn:aws:sns:us-east-1:000000000000:app/APNS/app-test" --token my-fake-token
{
    "EndpointArn": "arn:aws:sns:us-east-1:000000000000:endpoint/APNS/app-test/c25f353e-856b-4b02-a725-6bde35e6e944"
}

Publish a message to the platform endpoint:

$ awslocal sns publish --target-arn "arn:aws:sns:us-east-1:000000000000:endpoint/APNS/app-test/c25f353e-856b-4b02-a725-6bde35e6e944" --message '{"APNS_PLATFORM": "{\"aps\": {\"content-available\": 1}}"}' --message-structure json
{
    "MessageId": "ed501a7a-caab-45aa-a941-2fcc64b5c227"
}

Retrieve the messages published to the platform endpoint using cURL:

$ curl "http://localhost:4566/_aws/sns/platform-endpoint-messages" | jq .
{
  "platform_endpoint_messages": {
    "arn:aws:sns:us-east-1:000000000000:endpoint/APNS/app-test/c25f353e-856b-4b02-a725-6bde35e6e944": [
      {
        "TargetArn": "arn:aws:sns:us-east-1:000000000000:endpoint/APNS/app-test/c25f353e-856b-4b02-a725-6bde35e6e944",
        "Message": "{\"APNS_PLATFORM\": \"{\\\"aps\\\": {\\\"content-available\\\": 1}}\"}",
        "MessageAttributes": null,
        "MessageStructure": "json",
        "Subject": null
      }
    ]
  },
  "region": "us-east-1"
}

With those same filters, you can reset the saved messages at DELETE /_aws/sns/platform-endpoint-messages. Run the following command to reset the saved messages:

$ curl -X "DELETE" "http://localhost:4566/_aws/sns/platform-endpoint-messages"
$ curl "http://localhost:4566/_aws/sns/platform-endpoint-messages" | jq .
{
  "platform_endpoint_messages": {},
  "region": "us-east-1"
}

Resource Browser

The LocalStack Web Application provides a Resource Browser for managing SNS topics. You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the Resources section, and then clicking on SNS under the App Integration section.

The Resource Browser allows you to perform the following actions:

• Create Topic: Create a new SNS topic by specifying a topic name, attributes, and tags.
• View Details and Subscription: View details and subscription of an SNS topic by selecting the topic name and navigating to the Details and Subscriptions tabs.
• Create Subscription: Create a new subscription for an SNS topic by selecting the topic name, navigating to the Subscriptions tab, and clicking the Create Subscription button. Fill in the required details such as protocol, endpoint, and attributes, delivery policy, return subscription ARN, and click Create.
• Delete Topic: Delete an SNS topic by selecting the topic name and clicking the Action button, followed by Delete Selected.

Examples

The following code snippets and sample applications provide practical examples of how to use SNS in LocalStack for various use cases:

• Full-Stack application with AWS Lambda, DynamoDB & S3 for shipment validation
• Event-driven architecture with Amazon SNS FIFO, DynamoDB, Lambda, and S3
• Loan Broker application with AWS Step Functions, DynamoDB, Lambda, SQS, and SNS
• Serverless Image Resizer with AWS Lambda, S3, SNS, and SES