Simple Notification Service (SNS)
5 minute read
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
Parameter | Required | Description |
---|---|---|
accountId | No | The AWS Account ID from which the messages have been published. If not specified, it will use the default 000000000000 |
region | No | The AWS region from which the messages have been published. If not specified, it will use the default us-east-1 |
endpointArn | No | The target EndpointArn to which the messages have been published. If specified, the response will contain only messages sent to this target. Otherwise, it will return all endpoints with their messages. |
Response format and attributes
Attribute | Description |
---|---|
platform_endpoint_messages | Contains endpoints ARN as field names. Each endpoint will have its messages in an Array. |
region | The region of the endpoints and messages. |
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