64:T430c,## Introduction AWS ships a range of official MCP servers. The [`awslabs/mcp`](https://github.com/awslabs/mcp) repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run `sam deploy` or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong `delete` could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. ## Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the `awslabs` namespace, each run with [`uvx`](https://docs.astral.sh/uv/). We used three: - **[aws-serverless](https://github.com/awslabs/mcp/tree/main/src/aws-serverless-mcp-server)** wraps the SAM CLI. It exposes `sam_init`, `sam_build`, `sam_deploy`, and `sam_logs`, so an agent can run the full serverless lifecycle without shelling out. - **[aws-iac](https://github.com/awslabs/mcp/tree/main/src/aws-iac-mcp-server)** validates infrastructure code. `validate_cloudformation_template` runs `cfn-lint` for syntax and schema, and `check_cloudformation_template_compliance` runs `cfn-guard` against AWS security rules. Both run locally, before anything deploys. - **[lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server)** exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. ## How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with `AWS_ENDPOINT_URL`, or with an `endpoint_url` line in a named profile in `~/.aws/config`. LocalStack listens on `http://localhost.localstack.cloud:4566` and answers the same API calls, so pointing a profile there is all it takes. Create a `localstack` profile: ```ini # ~/.aws/config [profile localstack] region = us-east-1 endpoint_url = http://localhost.localstack.cloud:4566 ``` ```ini # ~/.aws/credentials [localstack] aws_access_key_id = test aws_secret_access_key = test ``` LocalStack does not check AWS credentials, so `test` / `test` is the convention. The `endpoint_url` line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting `AWS_PROFILE=localstack` in the environment is the whole trick: ```json { "mcpServers": { "aws-serverless": { "command": "uvx", "args": ["awslabs.aws-serverless-mcp-server@latest", "--allow-write"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1" } }, "aws-iac": { "command": "uvx", "args": ["awslabs.aws-iac-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1" } } } } ``` There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.65:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.67:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.69:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.6b:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.6d:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.6f:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.71:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.73:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.75:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.77:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.79:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.7b:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.7d:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.7f:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.81:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.83:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.85:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.87:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there. ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) and the [`lstk` CLI](https://docs.localstack.cloud/getting-started/installation/) with a valid [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) (a [free account](https://app.localstack.cloud/sign-up) is enough) - [`uv`](https://docs.astral.sh/uv/getting-started/installation/), which provides the `uvx` launcher for the servers - The [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) and [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [Claude Code](https://www.claude.com/product/claude-code), or any other MCP client ## Step 1: Start LocalStack and register the servers Start LocalStack with the `lstk` CLI: ```bash lstk start ``` Save the JSON config from the previous section as `.mcp.json` in your project, then launch your agent pointed at it. In Claude Code: ```bash claude --mcp-config .mcp.json --strict-mcp-config ``` `--strict-mcp-config` tells the client to load only the servers in that file and ignore any global config, so the session sees exactly the two AWS servers and nothing else. The tools appear under names like `sam_init` and `validate_cloudformation_template`. For the run below we used Claude Code with `claude-opus-5`, as our coding agent. ## Step 2: Ask the agent to build the service We described a service rather than dictating files. The target was **hookline**, a webhook receiver: API Gateway takes a `POST /webhook`, an ingest Lambda verifies an HMAC-SHA256 signature, accepted deliveries go onto an SQS queue, and a worker Lambda records each one in DynamoDB. The one rule that mattered later: processing must be idempotent, because SQS delivers at least once and a redelivery must not create a second record. ```text Build hookline, a webhook ingestion service, on LocalStack. - POST /webhook (API Gateway + Lambda), verify an HMAC-SHA256 signature in the X-Hookline-Signature header over the raw body. Reject bad signatures. Do not hardcode the secret. - Accepted deliveries go to SQS, answer 202. A worker Lambda records each delivery in DynamoDB, idempotent per delivery id. - Scaffold with sam_init, then extend it yourself. Runtime python3.11. - Validate and compliance-check the template before the first deploy. - Deploy only through the MCP tools. Never shell out to sam. ``` The agent started with the scaffold: ```bash ● aws-serverless (sam_init: hookline, runtime python3.11) ⎿ Successfully initialized SAM project 'hookline' ``` `sam_init` creates a basic hello-world project. The agent then replaced it with the real template and two handlers. The ingest handler calculates the expected signature and compares it with `hmac.compare_digest`. It verifies the signature before parsing the request body, so unauthenticated input never reaches the JSON parser. The secret was stored in Secrets Manager and passed through a parameter marked `NoEcho`. The handler reads it during a cold start, so the secret is never written in the code. To prevent duplicate records, the worker uses a conditional DynamoDB write instead of reading before writing: ```python dynamodb.put_item( TableName=TABLE_NAME, Item=item, ConditionExpression="attribute_not_exists(delivery_id)", ) ``` The conditional write prevents duplicates. If the ID already exists, the write fails, so a retried message cannot create another record. It also avoids a race between separate read and write operations. This behavior passed both the initial test and the later stress tests. The bug was elsewhere. ## Step 3: Gate the template before it deploys Before deploying, the agent ran the template through the aws-iac server. `validate_cloudformation_template` came back with two errors: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: false, error_count: 2 E3033: '...' is longer than 256 (line 149) E3033: '...' is longer than 256 (line 188) ``` Both errors came from the functions' `Description` fields. The agent had described what each function does and which event format it expects, as requested. However, Lambda limits descriptions to 256 characters, and both were too long. The validation step caught this simple error before deployment. Without it, `CreateFunction` could have failed partway through the deployment and triggered a stack rollback. The agent shortened both descriptions and ran the checks again: ```bash ● aws-iac (validate_cloudformation_template) ⎿ is_valid: true ● aws-iac (check_cloudformation_template_compliance) ⎿ overall_status: COMPLIANT, violations: 0 ``` The compliance check uses `cfn-guard` to verify AWS security rules, such as encryption at rest and avoiding wildcard IAM permissions. It passed because the queue and table used a customer-managed KMS key, and each policy was limited to one resource. The check confirmed these protections instead of leaving them as assumptions. ## Step 4: Deploy to LocalStack and smoke test With a clean template, the deploy went through the aws-serverless server: ```bash ● aws-serverless (sam_build) ⎿ Build Succeeded ● aws-serverless (sam_deploy) ⎿ Successfully created/updated stack - hookline ``` `sam_deploy` packages the code, uploads it to S3, and creates a CloudFormation stack just as it does on AWS. LocalStack created all 17 resources, including the REST API, two functions, queues, DynamoDB table, KMS key, and IAM roles. The agent used the same deployment process for the local environment. The agent then tested the API at `http://.execute-api.localhost.localstack.cloud:4566//webhook`. A correctly signed delivery returned `202` and appeared in DynamoDB. A modified request body returned `401`. Sending the same delivery four times created only one record, confirming that the conditional write prevented duplicates. The normal cases worked, so the agent moved on to unexpected inputs where bugs are more likely to appear. ## Step 5: Turn the deployed functions into agent tools The third server works differently. The [lambda-tool](https://github.com/awslabs/mcp/tree/main/src/lambda-tool-mcp-server) server finds Lambda functions and exposes each one as an MCP tool. When connected to LocalStack with a name filter, it turns the agent's newly deployed functions into tools the agent can call directly. Add it to `.mcp.json`: ```json "lambda-tool": { "command": "uvx", "args": ["awslabs.lambda-tool-mcp-server@latest"], "env": { "AWS_PROFILE": "localstack", "AWS_REGION": "us-east-1", "FUNCTION_PREFIX": "hookline-" } } ``` The server registers its tools at startup, so the agent needed a new session. After restarting, two tools appeared: `ingest` and `worker`. The `FUNCTION_PREFIX` filter included only the two `hookline-` functions instead of every function in the account. The agent uses each function's `Description` field from the template as the tool documentation. These are the same descriptions that exceeded the 256-character limit in Step 3. What you write in the template directly tells the next agent how to use each function. The service became part of the agent's toolset. The agent could now invoke its functions directly with any event structure it wanted to test. ## Step 6: Let the agent attack its own service We gave the agent a second task: ```text Write an adversarial probe table, predict the correct behavior for each case, then run every probe through the ingest and worker tools and record where reality diverged. ``` Defining the expected result before each test creates a clear pass or fail. A crash or incorrect status code then becomes a confirmed problem instead of something to explain away later. The agent created 30 tests. They covered missing or forged signatures, signatures for different request bodies, replays, duplicates, invalid JSON, oversized payloads, and batches containing invalid or duplicate records. Nine tests produced unexpected results, revealing seven bugs. Most were minor. A non-ASCII character in the signature header crashed the function instead of returning `401`. Invalid base64 caused a crash before authentication, and the payload had no size limit. One bug was more serious. ## Step 7: The bug that dropped data, and the fix Probe P29 sent the worker a batch of two SQS records: one poison record whose body was the JSON text `123`, and one valid delivery, `dlv-2129`. ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned with error: Unhandled ``` The whole invocation crashed. The agent pulled the logs through `sam_logs` and found the cause: ```bash [ERROR] TypeError: 'int' object is not subscriptable File "app.py", line 56, in lambda_handler delivery_id = delivery["id"] ``` The worker parsed each message like this: ```python try: delivery = json.loads(record["body"]) delivery_id = delivery["id"] except (ValueError, KeyError) as exc: print(f"discarding malformed message {message_id}: {exc}") continue ``` `json.loads("123")` does not fail because `123` is valid JSON. It returns an integer, but the code then tries to read `delivery["id"]` from it. This raises a `TypeError`, which the `except` block does not catch. The error therefore caused the entire Lambda batch to fail. When a Lambda processing SQS messages fails, SQS retries the entire batch. After repeated failures, the batch moves to the dead-letter queue. The invalid message could never succeed, so the valid `dlv-2129` message was retried and moved to the DLQ with it. That valid delivery was never processed, and no error reported the problem. The agent confirmed this when `get-item` returned no result for `dlv-2129`. The fix has two parts. First, check the structure of each message before using it. If the structure is invalid, discard the message instead of retrying it: ```python delivery = json.loads(body) if not isinstance(delivery, dict): return None, f"body is {type(delivery).__name__}, expected a JSON object" ``` Second, handle each record separately. The handler already returned `batchItemFailures`, which tells SQS which messages to retry, but it included the wrong messages. A message that cannot be parsed should be discarded because retrying it will always fail. Only temporary failures, such as a throttled `PutItem`, should be added to `batchItemFailures`. This prevents one bad record from blocking the valid records in the same batch. The agent redeployed with `sam_build` and `sam_deploy`. It then repeated every test, not only the ones that had failed: ```bash ● worker (Records: [ body "123", body {"id":"dlv-2129", ...} ]) ⎿ Function hookline-worker returned: { "batchItemFailures": [] } ``` The invalid message was discarded, while `dlv-2129` was processed successfully. No failure was reported because no message needed to be retried. All 30 tests produced the expected results. The agent also checked DynamoDB manually and confirmed that every accepted delivery was present and every rejected delivery was absent. ## What the whole run cost Two sessions, because adding the lambda-tool server needed a restart. Combined: | | | |---|---| | Turns | 152 | | Time (agent working) | ~26 minutes | | MCP tool calls | 74 | | Cost (Opus) | $13.26 | The same work against a real account would have created and torn down seventeen resources per deploy across several deploys, plus every probe invocation, for the price of finding one data-loss bug. Locally it was the cost of a container that you can start and stop as needed. ## Summary AWS's MCP servers are built for AWS, but they resolve endpoints like any SDK client, so a single profile redirects them to LocalStack. That one line turns a toolchain that mutates a real account into one an agent can run freely: build with SAM, gate with `cfn-lint` and `cfn-guard`, deploy, and then, through the lambda-tool server, invoke the deployed functions and attack them. If you want the agent to manage LocalStack itself, starting and stopping the container, injecting faults, or reading logs, the [LocalStack MCP server](https://github.com/localstack/localstack-mcp-server) sits alongside the AWS ones and adds those tools. The AWS servers build and operate the application; the LocalStack server runs the environment underneath it.89:T2dc7,Introduction AWS ships a range of official MCP servers. The repository holds more than fifty of them, covering SAM, CloudFormation, Lambda, DynamoDB, and most of the console. If you use an AI coding agent, you have probably already installed one or two. They all talk to a real AWS account. That is the point, and also the problem. An agent that can run or invoke a Lambda function is useful, but every call it makes is billable and, worse, real. For instance, a wrong could be a huge problem. These servers read AWS configuration the same way any SDK client does. So you can point them somewhere else. Set one environment variable and the same tools operate against LocalStack, where a deploy costs nothing and recovering from a mistake is a container restart. We wanted to see how far that goes, so we gave an agent the AWS MCP servers and nothing else, with LocalStack as its cloud. Its job: build a small webhook service, get it past a compliance gate, deploy it, then attack it and fix what broke. It found a bug that silently dropped valid data, and fixed it. Here is how the setup works and what the session looked like. Introduction to AWS MCP Servers AWS publishes its servers as Python packages under the namespace, each run with . We used three: aws-serverless wraps the SAM CLI. It exposes , , , and , so an agent can run the full serverless lifecycle without shelling out. aws-iac validates infrastructure code. runs for syntax and schema, and runs against AWS security rules. Both run locally, before anything deploys. lambda-tool exposes deployed Lambda functions as callable tools. This is the interesting one, and we come back to it in Step 5. Each server does one job and does it through a proper API rather than a shell script the agent has to remember. The agent picks the tool; the server handles the mechanics. How to set up the AWS MCP Servers with LocalStack Every AWS SDK resolves an endpoint before it makes a call. Normally that endpoint is the real AWS one for the region. You can override it with , or with an line in a named profile in . LocalStack listens on and answers the same API calls, so pointing a profile there is all it takes. Create a profile: LocalStack does not check AWS credentials, so / is the convention. The line is what does the work. Now hand that profile to each MCP server. An MCP client reads a JSON config that lists the servers, the command to launch each one, and its environment. Setting in the environment is the whole trick: There is no LocalStack-specific flag anywhere in that file. The servers do not know they are talking to an emulator. They resolve the profile, see the endpoint, and send their calls there.

=> { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)8b:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)48:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muywp7dfys24",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muywp5he4s24"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muywp5he4s24","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$8a","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$8b","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muywp7dfys24","sort_date":"2026-03-03T00:00:00+00:00"}}] 8c:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)8d:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)49:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mte6b7wbi224",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mte6b5fy5c24"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mte6b5fy5c24","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$8c","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$8d","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mte6b7wbi224","sort_date":"2026-03-03T00:00:00+00:00"}}] 8e:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)8f:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)4a:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mteqwiwag22e",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mteqwe52322e"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mteqwe52322e","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$8e","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$8f","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mteqwiwag22e","sort_date":"2026-03-03T00:00:00+00:00"}}] 90:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)91:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)4b:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mttxrhjpic2y",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mttxreldxc2y"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mttxreldxc2y","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$90","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$91","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mttxrhjpic2y","sort_date":"2026-03-03T00:00:00+00:00"}}] 92:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)93:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)4c:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu26cohhc2c",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu265sxuk2c"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu265sxuk2c","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$92","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$93","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu26cohhc2c","sort_date":"2026-03-03T00:00:00+00:00"}}] 94:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)95:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)4d:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu2pxljbk2y",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu2puwx7s2y"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu2puwx7s2y","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$94","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$95","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu2pxljbk2y","sort_date":"2026-03-03T00:00:00+00:00"}}] 96:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)97:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)4e:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu46d7ugs2l",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu46aeyac2l"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu46aeyac2l","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$96","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$97","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu46d7ugs2l","sort_date":"2026-03-03T00:00:00+00:00"}}] 98:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)99:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)4f:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu5fnxsh22v",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu5flmn6c2v"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu5flmn6c2v","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$98","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$99","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu5fnxsh22v","sort_date":"2026-03-03T00:00:00+00:00"}}] 9a:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)9b:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)50:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtwctnulys2c",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtwcthuqe22c"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtwcthuqe22c","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$9a","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$9b","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtwctnulys2c","sort_date":"2026-03-03T00:00:00+00:00"}}] 9c:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)9d:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)51:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtwdezflbs2u",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtwdesao3k2u"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtwdesao3k2u","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$9c","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$9d","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtwdezflbs2u","sort_date":"2026-03-03T00:00:00+00:00"}}] 9e:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)9f:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)52:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtymguohdc2g",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtymgro3ds2g"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtymgro3ds2g","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$9e","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$9f","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtymguohdc2g","sort_date":"2026-03-03T00:00:00+00:00"}}] a0:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)a1:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)53:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtynlxap6k23",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtynluy3ws23"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtynluy3ws23","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$a0","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$a1","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtynlxap6k23","sort_date":"2026-03-03T00:00:00+00:00"}}] a2:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)a3:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)54:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mu2m4z435k2p",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mu2m4upacs2p"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mu2m4upacs2p","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$a2","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$a3","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mu2m4z435k2p","sort_date":"2026-03-03T00:00:00+00:00"}}] a4:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)a5:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)55:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mu2mdh46g225",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mu2mdcnlw225"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mu2mdcnlw225","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$a4","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$a5","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mu2mdh46g225","sort_date":"2026-03-03T00:00:00+00:00"}}] a6:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)a7:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)56:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muhgnjfezs2q",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muhgnhdat22q"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muhgnhdat22q","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$a6","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$a7","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muhgnjfezs2q","sort_date":"2026-03-03T00:00:00+00:00"}}] a8:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)a9:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)57:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muk6eg24rs2m",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muk6eddu222m"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muk6eddu222m","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$a8","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$a9","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muk6eg24rs2m","sort_date":"2026-03-03T00:00:00+00:00"}}] aa:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)ab:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)58:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mumjrrw3kk22",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mumjrpdlvs22"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mumjrpdlvs22","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$aa","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$ab","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mumjrrw3kk22","sort_date":"2026-03-03T00:00:00+00:00"}}] ac:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)ad:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)59:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muna3kygds2r",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muna3iguxs2r"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muna3iguxs2r","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$ac","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$ad","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muna3kygds2r","sort_date":"2026-03-03T00:00:00+00:00"}}] ae:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)af:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)5a:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muyy4tehak2d",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muyy4rav522d"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muyy4rav522d","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$ae","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$af","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muyy4tehak2d","sort_date":"2026-03-03T00:00:00+00:00"}}] b0:T4ee8,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like [SQS, which we covered previously](https://blog.localstack.cloud/aws-deep-dives-sqs/), it helps you to follow a well-architected serverless application architecture that follows the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) with services that are [loosely coupled](https://en.wikipedia.org/wiki/Loose_coupling). But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. ## Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. 1. **Event Fan-Out Communication Between Internal Services**: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. 2. **External Notifications to Users or Systems**: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. 3. **Operational Alerts**: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. 4. **Event Routing**: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. ### Example Repository The example code shown here is from a sample application available [on GitHub](https://github.com/localstack-samples/aws-deep-dives/tree/main/sns) that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. ## SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. ### Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. ```typescript const orderEventsTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events', displayName: 'Events from e-commerce orders', }); ``` If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in `.fifo`, and SNS also provides [deduplication options](https://docs.aws.amazon.com/sns/latest/dg/fifo-message-dedup.html) if needed. ```typescript const myFifoTopic = new sns.Topic(this, 'OrderEventsTopic', { topicName: 'order-events.fifo', // Name MUST end in .fifo fifo: true, }); ``` It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. ### Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. ```typescript // 1. Order API Lambda (Publisher) const orderApiLambda = new NodejsFunction(this, 'OrderApiLambda', { ...lambdaDefaults, functionName: 'order-api', entry: 'lambda/order-api.ts', handler: 'handler', environment: { SNS_TOPIC_ARN: orderEventsTopic.topicArn, }, }); // Grant the Order API Lambda permission to publish to the topic orderEventsTopic.grantPublish(orderApiLambda); ``` At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use `PublishCommand`, which is exported from the AWS SDK's SNS client (`@aws-sdk/client-sns`). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The `message` field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an `eventType` which, in the case of our sample app, can be `OrderPlaced`, `OrderShipped`, `OrderDelayed`, and `OrderCancelled` that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. ```typescript // Publish to SNS with message attributes for filtering const publishCommand = new PublishCommand({ TopicArn: SNS_TOPIC_ARN, Message: JSON.stringify(messagePayload), MessageAttributes: { eventType: { DataType: 'String', StringValue: orderEvent.eventType, }, priority: { DataType: 'String', StringValue: orderEvent.priority || 'medium', }, }, }); const result = await snsClient.send(publishCommand); ``` So let's see how we would subscribe to and respond to messages published to the topic. ### Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. ```typescript orderEventsTopic.addSubscription( new snsSubscriptions.LambdaSubscription(customerNotificationsLambda, { filterPolicy: { eventType: sns.SubscriptionFilter.stringFilter({ allowlist: ['OrderPlaced', 'OrderShipped', 'OrderCancelled'], }), }, }), ); ``` #### Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the `eventType` of `OrderDelayed` (as that is the only supported `eventType` that isn't listed in the `allowList`). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the [filtering section of the SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) or [this blog post](https://oneuptime.com/blog/post/2026-01-30-aws-sns-message-filtering/view)), but let's briefly touch on a couple of important notes: 1. You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the `FilterPolicyScope`. We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. 2. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The `allowList` shown above is essentially OR logic, wherein any of the values for `eventType` will pass through. This could potentially have been achieved via an [anything-but](https://docs.aws.amazon.com/sns/latest/dg/numeric-value-matching.html#numeric-anything-but-matching) filter, where we would have allowed any value except `OrderDelayed`. You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. #### Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed `eventTypes` from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the `eventType` message attribute, passing the parsed message body data along to the function. ```typescript export const handler = async (event: SNSEvent): Promise => { console.log( 'Customer Notifications Lambda received event:', JSON.stringify(event, null, 2), ); for (const record of event.Records) { const message: OrderEvent = JSON.parse(record.Sns.Message); console.log('Processing customer notification:', { eventType: message.eventType, orderId: message.orderId, userId: message.userId, }); // Send SMS notifications based on event type switch (message.eventType) { case 'OrderPlaced': await sendOrderConfirmation(message); break; case 'OrderShipped': await sendShippingNotification(message); break; case 'OrderCancelled': await sendCancellationNotification(message); break; default: console.log( `Unhandled event type for customer notifications: ${message.eventType}`, ); } } }; ``` Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. ### Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like [AWS End User Messaging](https://aws.amazon.com/end-user-messaging/) or [SES](https://aws.amazon.com/ses/). SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a [sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html) with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to [move out of the sandbox](https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html), which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. #### Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical `grantPublish` as we aren't just pushing messages onto the topic. We need to enable `sns:Publish` on `*` because phone numbers are not ARNs and can’t be scoped in the policy. ```typescript // Grant permission to send SMS via SNS customerNotificationsLambda.addToRolePolicy( new iam.PolicyStatement({ effect: iam.Effect.ALLOW, actions: ['sns:Publish'], resources: ['*'], // Required for SMS publishing to phone numbers }), ); ``` From within the Lambda itself, sending the message isn't complicated. We'll just use the `PublishCommand` from the AWS SDK's SNS client. ```typescript async function sendSMS(phoneNumber: string, message: string): Promise { if (!phoneNumber) { console.warn('No phone number provided, skipping SMS'); return; } try { const command = new PublishCommand({ PhoneNumber: phoneNumber, Message: message, }); const result = await snsClient.send(command); console.log(`SMS sent successfully. MessageId: ${result.MessageId}`); } catch (error) { console.error(`Failed to send SMS to ${phoneNumber}:`, error); throw error; } } ``` It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the [best practices guide](https://docs.aws.amazon.com/sns/latest/dg/channels-sms-best-practices.html) before proceeding. #### Sending Emails We've [previously discussed SES](https://blog.localstack.cloud/aws-deep-dives-ses/) as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. ```typescript // Create SNS Topic for Ops Alerts (email notifications) const opsAlertsTopic = new sns.Topic(this, 'OpsAlertsTopic', { topicName: 'ops-alerts', displayName: 'Operations Team Alerts', }); // Add email subscription for ops team opsAlertsTopic.addSubscription( new snsSubscriptions.EmailSubscription('ops@foo.com'), ); ``` From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. ```typescript const command = new PublishCommand({ TopicArn: OPS_ALERTS_TOPIC_ARN, Subject: emailSubject, Message: emailBody, }); const result = await snsClient.send(command); ``` It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. ## SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. ## LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the [AWS APIs for SNS are covered](https://docs.localstack.cloud/aws/services/sns/#api-coverage), with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided [developer endpoints](https://docs.localstack.cloud/aws/services/sns/#developer-endpoints) to [confirm messages have been sent](https://docs.localstack.cloud/aws/services/sns/#sms-messages). Or, in the case of email, you can also use the [Mailhog extension](https://docs.localstack.cloud/aws/tooling/extensions/mailhog/) to view sent emails. ## Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. - [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (AWS documentation) - [Simple Notification Service (SNS)](https://docs.localstack.cloud/aws/services/sns/) (LocalStack docs) - [AWS SNS: The Complete Guide to Real-Time Notifications](https://www.datacamp.com/tutorial/aws-sns) (DataCamp blog) - [AWS SNS vs. SQS - What Are the Main Differences?](https://awsfundamentals.com/blog/aws-sns-vs-sqs-what-are-the-main-differences) (AWS Fundamentals blog)b1:T38a5,When you start exploring the long list of AWS services, you realize that many things are simple. I don't mean that they are necessarily easy. What I mean is that they literally have the word "simple" in their name, as does every service we've covered in this series thus far (SES, SQS, and now SNS). Amazon SNS stands for "Simple Notification Service," and it is a publish-subscribe (aka pub/sub) notification service. On the one hand, like SQS, which we covered previously, it helps you to follow a well-architected serverless application architecture that follows the single responsibility principle with services that are loosely coupled. But, on the other hand, SNS supports endpoints like HTTP(S), email, mobile push notifications, text messages, and more that allow notifications to be broadcast outside your serverless application. Let's take a deeper look. Why Do You Need a Push Notification Service? The tricky part about SNS isn't so much understanding why you need it, but trying to grasp all the potential use cases. That's because the pub/sub model is incredibly flexible and serves both internal (i.e. application-to-application) and external (i.e., application-to-person) use cases. Let's look at some key ones. Event Fan-Out Communication Between Internal Services: This is where SNS helps support a decoupled architecture, similar to SQS. However, whereas messages on SQS queues are typically consumed once by a single service, SNS allows a service to publish an event once, and multiple internal or even external systems (via HTTP endpoints) will react to that event independently (i.e., why it's called "fan-out"). For example, a single purchase event on an e-commerce system might trigger an inventory update, a billing notification, and a shipping workflow. In fact, SNS and SQS often work together, with SQS queues subscribing to an SNS topic while also ensuring things like retries and buffering for each individual workflow triggered by the SNS event. External Notifications to Users or Systems: SNS has the ability to reach out to external systems (via HTTP endpoints such as APIs or webhooks) and external users (via email, mobile push notifications, or text messaging). For example, imagine our shipping workflow actually utilizes an external, 3rd party provider; the same SNS event could both trigger the HTTP endpoint to start the shipping process while also notifying the end-user via text message that their shipment is being prepared. Retry policies and dead-letter queues can help ensure critical notifications aren't missed. Operational Alerts: Because of SNS's ability to communicate with both internal AWS services as well as external services, it can be ideal for operational alerts that need to reach both people and tools (ex. PagerDuty, Slack) at the same time. When also combined with the ability to filter message subscriptions, it can ensure that each endpoint only receives relevant messages. Event Routing: While not as robust as EventBridge, SNS's fan-out and filtering capabilities make it an option as a lightweight event router, where consumers self-select relevant events via filtering. That's a lot of places where SNS may fit into your application, and this is far from an exhaustive list of use cases. Example Repository The example code shown here is from a sample application available on GitHub that aims to demonstrate a number of SNS use cases in a simple e-commerce order management backend. The example application can be deployed to LocalStack or AWS using the AWS CDK and demonstrates SNS message topics, subscriptions, application-to-application messaging, and application-to-person messaging. SNS Basics There are two core aspects to a pub/sub service like SNS, and, yeah, they are probably pretty obvious: publishing messages to a topic and subscribing to a topic. But, within those basics, there are a lot of options. I can't cover everything here, but I'll try to cover some of the key items. As with the prior articles in this series, the example code will use the AWS CDK. Creating an SNS Topic When it comes to creating a topic, SNS lives up to the "simple" in its name. There are literally no required properties when constructing a topic via CDK/CloudFormation. Technically, a topic name is required; if you don't provide one, CloudFormation generates a unique physical ID for the name. If you need to ensure that SNS maintains a strict message order, you'll want to create a FIFO (first in, first out) topic. This ensures that the messages are delivered in the order they are received. Just as with SQS, the name of a FIFO topic must end in , and SNS also provides deduplication options if needed. It's worth noting that if you combine FIFO deduplication with filtering, which we'll discuss in more detail later, SNS cannot guarantee exactly-once message delivery because it's possible that an individual message is filtered out and never received. Publishing to Topics There are two steps to publishing to a topic. First, we need to grant the publisher permission to publish to the topic. In the example below, we're using CDK to create a Lambda, providing that Lambda with the SNS topic ARN as an environment variable and, finally, granting the Lambda permission to publish to the appropriate topic. At this point, our Lambda has permission to publish, but nothing has been published yet. Let's look at how to publish to the SNS topic from within the Lambda. To do this, we'll use , which is exported from the AWS SDK's SNS client ( ). We'll provide the topic ARN that we supplied as an environment variable via the CDK above. The field will provide the JSON payload. Message attributes are arbitrary structured metadata that we can add to our message. As we'll see in further examples, these are useful for providing details that can be used to decide how to handle a message without processing the message body. For example, we are providing an which, in the case of our sample app, can be , , , and that we'll use to determine how to route a message within the business logic of a Lambda subscribed to this topic. Finally, we'll use the SDK's SNS client to send the message to the topic, which will trigger any resources subscribed to that topic. So let's see how we would subscribe to and respond to messages published to the topic. Subscriptions Adding a subscription can be relatively simple as well. For instance, the CDK example below from our sample app adds a topic subscription to a Lambda. The most complicated aspect of this is the filter policy, but it isn't a required element. If we didn't provide one, the Lambda would, as you might have guessed, get all the messages from that topic. Filtering As you can see from above, filtering allows us to constrain the messages that will be passed to a resource. In the case of this example, we are using one of the arbitrary message attributes that we created earlier and simply filtering messages with the of (as that is the only supported that isn't listed in the ). This example is very simple, but filtering can get much more complex if needed, and a full overview of writing filter policies is beyond the scope of this blog post (you can reference the filtering section of the SNS documentation or this blog post), but let's briefly touch on a couple of important notes: You can filter on both the message attributes (i.e., the arbitrary metadata) or the message body by setting the . We have not set the scope above because message attributes are the default scope. Using message attributes for filtering is considered best practice when possible, but there are circumstances where you cannot modify the SNS message, such as native AWS Service events (e.g., S3, CloudWatch, CloudFront), for example, where payload filtering may be necessary. Performance is cited as one reason to use message attributes since SNS doesn't need to parse the message body (though I can't seem to easily find data that clearly backs this up), but the more important reason is that message body filtering is not free, costing $0.09 per GB of scanned payload data if using US-East-1, for instance. Filter policies can include a decent amount of logic by utilizing the supported filter operators. For instance, a policy can include AND/OR logic. The shown above is essentially OR logic, wherein any of the values for will pass through. This could potentially have been achieved via an anything-but filter, where we would have allowed any value except . You can do exact matches, matches on prefixes or suffixes, IP address matching, numeric value range matching, and more. The point here is that the logic in your filter policy can probably get as complex as you need it to. Handling an SNS event in a Lambda Let's briefly look at how you might handle an SNS message event within code in a Lambda. In the example below, the Lambda is receiving the messages of all the allowed from the prior example. We'll parse the message body of the event within our handler and then call different methods within the Lambda function based upon the message attribute, passing the parsed message body data along to the function. Sending messages to Lambda is one example of application-to-application messaging within SNS. Other types of application-to-application subscribers include SQS and HTTP endpoints. Application to Person Messaging In addition to application-to-application messaging, SNS is capable of application-to-person messaging via SMS text messages, mobile push notifications, or email. SNS is not as full-featured for application to person messaging as something like AWS End User Messaging or SES. SNS is most useful for quick and easy system/application alerts or notifications that fan out to many subscribers (note: ultimately, SMS messages sent through SNS are delivered via AWS End User Messaging SMS). As you might expect, there are also verification steps required for sending messages to individuals. For SMS text messages, SNS provides a sandbox with a limited number of manually verified numbers, but you'll eventually need to go through a verification process to move out of the sandbox, which could take some time (a minimum of 24 hours). Email subscribers will need to confirm their subscription to the topic. Sending SMS Text Messages Before we can send text messages within our Lambda, we need to grant permission for our Lambda to send SMS messages. In our case, we are sending messages to individual phone numbers for notifications rather than to a list of numbers subscribed to a topic. This cannot use the typical as we aren't just pushing messages onto the topic. We need to enable on because phone numbers are not ARNs and can’t be scoped in the policy. From within the Lambda itself, sending the message isn't complicated. We'll just use the from the AWS SDK's SNS client. It's critical to keep in mind that there are a significant number of laws that regulate text messaging individuals, so it is worth reviewing the best practices guide before proceeding. Sending Emails We've previously discussed SES as a full-featured service for sending emails that is typically used for transactional and/or marketing emails. However, if your application needs to send a simple, text-only email notification, such as a system alert or some other form of internal notification, SNS can get the job done simply (and less expensively than SES). In our example, we're manually adding an email subscription to the topic via the CDK since the email is for an ops alert when an issue occurs. From within the Lambda, we need to publish to the topic, and all the subscribed emails (which is only one email address in our simple example) will receive the update. It's worth pointing out that the email body cannot be personalized. Everyone subscribed gets the same message, which reemphasizes that this is more useful for alerts than marketing emails. SNS Costs So what's this all going to cost you? As usual, when speaking about AWS services, the answer is, "It depends on a lot of factors." Let's dig into the pricing based on using US-EAST-1 as the baseline. You typically pay for SNS based upon API requests (publishes, subscription operations, etc.). The good news is that, for standard topic requests, the first million SNS requests per month are free, and after that, it’s $0.50 per additional 1 million requests. A caveat to this is that each 64KB chunk of published data is billed as one request and, since a request can have a payload up to 256KB, that would be billed as four requests. The pricing can also be different based on how you are delivering the messages. You can deliver to services like Lambda and SQS for no additional charge (I mean, other than what you are paying for those services downstream) but delivering to mobile push notifications (1 million free and $0.50 per million thereafter), email (1,000 free and $2.00 per 100,000 thereafter) and HTTP/S (100,000 free and $0.60 per million thereafter) will cost you extra. SMS (text message) pricing is tougher to predict because it depends on the destination country and any carrier fees. FIFO topics will also cost you extra, and do not have a free tier. The cost is $0.30 per million plus $0.017 per GB of payload data. In addition, there are no free deliveries on FIFO topics, which cost $0.01 per 1 million and $0.001 per GB of payload data. Additional features like message filtering, archiving/replay, and data protection can also introduce additional charges. LocalStack Support The good news is that SNS has excellent coverage in LocalStack, and that coverage is available within our free account. Almost all the AWS APIs for SNS are covered, with the only exceptions being the APIs around managing SMS sandboxes. If you are working with application-to-person messaging, you can fully test this on LocalStack, but be aware that the messages will not be sent. However, you can use LocalStack's provided developer endpoints to confirm messages have been sent. Or, in the case of email, you can also use the Mailhog extension to view sent emails. Additional Resources I hope you found this introductory deep dive helpful. If you are looking to learn more about SNS, here are the official documentation resources and other blog posts that you may find useful. What is Amazon SNS? (AWS documentation) Simple Notification Service (SNS) (LocalStack docs) AWS SNS: The Complete Guide to Real-Time Notifications (DataCamp blog) AWS SNS vs. SQS - What Are the Main Differences? (AWS Fundamentals blog)5b:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muz2ytnz5s2s",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muz2yrnxe22s"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/aws-deep-dives-sns/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muz2yrnxe22s","tags":["Serverless","AWS","SNS"],"$type":"site.standard.document","title":"AWS Deep Dives - Amazon SNS (Simple Notification Service)","content":{"text":"$b0","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-03-03T00:00:00.000Z","description":"Amazon SNS (Simple Notification Service) is a fully managed publish-subscribe (pub/sub) messaging service that enables fan-out communication between applications and directly to end users.","publishedAt":"2026-03-03T00:00:00.000Z","textContent":"$b1","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muz2ytnz5s2s","sort_date":"2026-03-03T00:00:00+00:00"}}] 5c:["$","$L31","at://did:plc:c7ernpvkghpxzizlq3thzwc3/site.standard.document/3mctz3fpja22p",{"publication":{"href":"https://developr.leaflet.pub","pubRecord":{"url":"https://developr.leaflet.pub","name":"developer footnotes","$type":"site.standard.publication","description":"Building my exit strategy of my corporate 9-5 whilst working as a senior software engineer.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":true,"showInDiscover":true},"theme":"$undefined"},"uri":"at://did:plc:c7ernpvkghpxzizlq3thzwc3/site.standard.publication/3mcty32tjcs2z"},"ownerDid":"@fullystacked-dvlpr.bsky.social","contributors":[{"did":"did:plc:c7ernpvkghpxzizlq3thzwc3","handle":"fullystacked-dvlpr.bsky.social","displayName":""}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/3mctz3fpja22p","site":"at://did:plc:c7ernpvkghpxzizlq3thzwc3/site.standard.publication/3mcty32tjcs2z","tags":["serverless","software development","typescript","nodejs","aws","cloud"],"$type":"site.standard.document","title":"Day 0.0.0 - Hello, World!","content":{"$type":"pub.leaflet.content","pages":[{"id":"019bdb02-9f4f-7bba-bbb6-8c2d71730b7a","$type":"pub.leaflet.pages.linearDocument","blocks":[{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":""}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.header","level":2,"plaintext":"Format"}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.code","language":"shellscript","plaintext":"0.0.0\n| | |\n| | |_ Day\n| |_ Month\n|_ Year"}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"Trialing Something different. Daily developer notes, with a semver title, not sure if I’m subconsciously bringing that out from someone else doing it, or if it’s an original idea. Either way, it seems fun. Obviously it’s zero indexed, I.e year 1 is actually 0. Let’s see how far we get."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":""}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.header","level":2,"plaintext":"Setting the Scene"}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"I’ve been a developer, for over a decade, with about 8 years as a FullStack Developer. Focusing primarily with Nodejs, JavaScript, Typescript. Picking up Python, Dart, SQL (if it counts as a language - No shade), Perl to what I’d consider to a level of fluency along the way. Dabbling with another handful of languages like Go, and C#, Java, Ruby for various tasks or projects I’ve been involved with."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"November 2025, my wife and I welcomed our first child into the world, and after 7 weeks of trial by fire I found out how desperate I am to be around at home as much as possible."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.header","level":1,"plaintext":"The Idea"}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"Every developer gets stuck in the endless cycle of side projects, side projects that’ll make it big! Build it, with the perfect stack all the best practices and full featured only to drop the development a short while in - I’m no exception, countless side projects that I’m going to monetise only to get bored and move on to the next shiny thing, or rip out huge features nobody asked for to rewrite it with a sick new framework or library. This time I need it to be different though, it has to stick and I have to ship it. I actually have something to lose if I don’t."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"The idea I have is quite niche from what I can tell, and unfortunately for anyone actually reading this, I won’t fully diverge the full idea until it’s more developed, for now I’ll just say it’s in the telecommunications industry. Competition exists and I am looking to see how to compete with the established brands, considering I don’t want to “disrupt” the space or even dominate - just have my fair share of the market. But the overall delivery of my idea is via Mobile application which I’m in the process of building out."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"The secret-ness of my idea at the moment doesn’t stop me from discussing my tech stack, backend processes and so on so there is still much that can be shared. So try to stick around, and see what else I have in store."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.header","level":1,"plaintext":"Typical Tech Stack"}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"So I’m basically always developing for serverless first. I hate configuring servers, managing docker compose files, docker swarm. Kubernetes This whole, \"A VPS for $5 a month\" culture irks me because they don't actually talk about the time (therefore cost) of managing that $5 hunk of (virtual) metal. At any stage of a developers journey if you're releasing code or products your time is worth more than the time spent trying to get that $5 VPS production ready, and maintained throughout it's lifetime."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","facets":[{"index":{"byteEnd":145,"byteStart":142},"features":[{"uri":"https://sst.dev","$type":"pub.leaflet.richtext.facet#link"}]},{"index":{"byteEnd":203,"byteStart":195},"features":[{"uri":"https://opencode.ai/","$type":"pub.leaflet.richtext.facet#link"}]}],"plaintext":"Anyway rant over - Serverless first mindset, I usually deploy to AWS, and to be honest I barely log into the AWS console. I develop using the SST Framework the same guys who created the fabulous OpenCode. Regrettably SST has taken a bit of a back seat in terms of support from the team, but it is mature enough and so far continues to suit my needs completely."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","facets":[{"index":{"byteEnd":60,"byteStart":55},"features":[{"uri":"https://astro.build/","$type":"pub.leaflet.richtext.facet#link"}]},{"index":{"byteEnd":173,"byteStart":166},"features":[{"uri":"https://flutter.dev","$type":"pub.leaflet.richtext.facet#link"}]},{"index":{"byteEnd":350,"byteStart":345},"features":[{"$type":"pub.leaflet.richtext.facet#underline"}]}],"plaintext":"On the Front-end for the web I'll use whatever, I LOVE Astro, and try to use it whenever I can. With a bit of React sprinkled in. For the mobile side, I'm a bit of a Flutter fanboy. I've worked professionally with React Native, and hobby projects with Flutter, I still choose Flutter every time over React Native. The resulting application just feels so much more polished."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","facets":[{"index":{"byteEnd":171,"byteStart":163},"features":[{"uri":"https://opennext.js.org/","$type":"pub.leaflet.richtext.facet#link"}]}],"plaintext":"Personally I try to avoid anything Vercel branded, so I do loathe NextJS but sometimes I do just have to bite the bullet - At the very least, will host it through OpenNext on AWS."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","facets":[{"index":{"byteEnd":117,"byteStart":110},"features":[{"uri":"https://github.com/modiimedia/arri","$type":"pub.leaflet.richtext.facet#link"}]}],"plaintext":"A rogue entry to the tech stack, recently I've been implementing a new library I stumbled upon a while back - ArriRPC, which is a code first remote procedure call framework."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.blockquote","plaintext":"Arri RPC is a code-first RPC framework. Type-safe clients get generated directly from your server code meaning you never need to manually write another client again."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"This means, since my backends are always in Typescript, I can host an ArriRPC server in a lambda on AWS, and build out my API's which in turn get a fully featured Dart client generated for me. This cross language development flow has been thoroughly enjoyable, and I think ArriRPC is a very unknown and underrated library."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.header","level":3,"plaintext":"Closing Thoughts"}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"I never really know how to end these things, and I think I just waffled about some semi related points for a few minutes (Took a couple hours to actually write), either way. Lets catch the next post, and see what I put down onto a page, and what I achieve between now and whenever the post lands."}},{"$type":"pub.leaflet.pages.linearDocument#block","block":{"$type":"pub.leaflet.blocks.text","plaintext":"Thanks."}}]}]},"description":"Day 0.0.0 of building my exit strategy of my corporate 9-5 whilst working as a senior software engineer.","publishedAt":"2026-01-20T11:03:42.182Z","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:c7ernpvkghpxzizlq3thzwc3/site.standard.document/3mctz3fpja22p","sort_date":"2026-01-20T11:03:42.182+00:00"}}] b2:T2394,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. ## Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. ### Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, [install Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) first and come back here once it’s running. ### Install the LocalStack CLI The easiest way to work with LocalStack is through the `lstk` CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out [this link.](https://docs.localstack.cloud/aws/getting-started/installation/) ```bash # macOS or Linux (Homebrew) brew install localstack/tap/lstk # Or via npm npm install -g @localstack/lstk ``` Once installed, verify it worked: ```bash lstk --version ``` If you see a version number, you are good to go. ### Start LocalStack Start LocalStack: ```bash lstk start ``` The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! ## Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. ### What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: - Developer auth tokens for local development - CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly [here.](https://app.localstack.cloud/settings/auth-tokens) Once you have the token, you’re ready to set it locally. One **important rule:** treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. ### Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. **Option 1: Use the LocalStack CLI** ```bash lstk login lstk start ``` **Option 2: Use an Environment Variable** If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: ```bash export LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` On Windows PowerShell: ```powershell $env:LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: ![LocalStack logs showing successful authentication"](../../assets/images/blog/first-local-aws-app-in-4-steps/ls-authenticated.png) ### Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: ```bash docker run -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} localstack/localstack ``` With Docker Compose: ```yaml environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` ## Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. **What This App Does** This sample is a shipment management application with: - A Spring Boot backend - A React frontend - Terraform-managed AWS infrastructure - Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. ![An architecture diagram of the shipment app"](../../assets/images/blog/first-local-aws-app-in-4-steps/architecture.png) ### Clone the Sample Application Start by cloning the repo: ```bash git clone https://github.com/localstack-samples/sample-terraform-fullstack-serverless-shipment-app.git cd sample-terraform-fullstack-serverless-shipment-app ``` ### Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: ```bash lstk start ``` If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. ### Install Project Dependencies Next, install everything the project needs: ```bash make install ``` This command handles a few things for you: - Builds the Lambda validator JAR ((Java ARchive)) - Installs frontend dependencies with npm - Prepares the project for deployment - You only need to run this once. ### Deploy the Infrastructure with Terraform This project uses [`lstk terraform`](https://docs.localstack.cloud/aws/integrations/infrastructure-as-code/terraform/) to run Terraform against LocalStack without any extra configuration. `lstk terraform` is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: ```bash make deploy ``` In the Makefile, the `deploy` target runs `lstk terraform init`, `lstk terraform plan`, and `lstk terraform apply`, which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: - S3 buckets for shipment images and Lambda code - A DynamoDB table pre-populated with sample shipments - A Lambda function for image validation and watermarking - SNS topics and SQS queues for messaging - All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. ### Start the Frontend In a new terminal, start the React frontend: ```bash cd shipment-list-frontend npm start ``` The frontend will be available at http://localhost:3000 ### Start the Backend In another terminal, start the Spring Boot backend: ```bash mvn spring-boot:run -Dspring-boot.run.profiles=dev ``` The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. ## Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 - See a list of shipments - Upload an image to a shipment - Watch that image get processed by a Lambda function - See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. ### Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: ```bash make test ``` This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: ```bash lstk stop ``` ## Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: 1. Installed LocalStack 2. Set up authentication 3. Deployed a real serverless app 4. Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.b3:T1cc5,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, install Docker Desktop first and come back here once it’s running. Install the LocalStack CLI The easiest way to work with LocalStack is through the CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out this link. Once installed, verify it worked: If you see a version number, you are good to go. Start LocalStack Start LocalStack: The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: Developer auth tokens for local development CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly here. Once you have the token, you’re ready to set it locally. One important rule: treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. Option 1: Use the LocalStack CLI Option 2: Use an Environment Variable If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: On Windows PowerShell: Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: With Docker Compose: Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. What This App Does This sample is a shipment management application with: A Spring Boot backend A React frontend Terraform-managed AWS infrastructure Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. Clone the Sample Application Start by cloning the repo: Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. Install Project Dependencies Next, install everything the project needs: This command handles a few things for you: Builds the Lambda validator JAR ((Java ARchive)) Installs frontend dependencies with npm Prepares the project for deployment You only need to run this once. Deploy the Infrastructure with Terraform This project uses to run Terraform against LocalStack without any extra configuration. is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: In the Makefile, the target runs , , and , which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: S3 buckets for shipment images and Lambda code A DynamoDB table pre-populated with sample shipments A Lambda function for image validation and watermarking SNS topics and SQS queues for messaging All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. Start the Frontend In a new terminal, start the React frontend: The frontend will be available at http://localhost:3000 Start the Backend In another terminal, start the Spring Boot backend: The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 See a list of shipments Upload an image to a shipment Watch that image get processed by a Lambda function See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: Installed LocalStack Set up authentication Deployed a real serverless app Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.5d:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu2pybbks2y",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu2puwx7s2y"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/first-local-aws-app-in-4-steps/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtu2puwx7s2y","tags":["AWS","Serverless","LocalDevelopment","DevEx","CloudEngineering"],"$type":"site.standard.document","title":"Run Your First AWS App Locally in 4 Simple Steps with LocalStack","content":{"text":"$b2","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-01-20T00:00:00.000Z","description":"Learn how to build and run your first AWS-style application entirely on your local machine. This step-by-step guide walks through installing LocalStack, configuring authentication, and deploying a real serverless app without deploying to AWS.","publishedAt":"2026-01-20T00:00:00.000Z","textContent":"$b3","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtu2pybbks2y","sort_date":"2026-01-20T00:00:00+00:00"}}] b4:T2394,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. ## Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. ### Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, [install Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) first and come back here once it’s running. ### Install the LocalStack CLI The easiest way to work with LocalStack is through the `lstk` CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out [this link.](https://docs.localstack.cloud/aws/getting-started/installation/) ```bash # macOS or Linux (Homebrew) brew install localstack/tap/lstk # Or via npm npm install -g @localstack/lstk ``` Once installed, verify it worked: ```bash lstk --version ``` If you see a version number, you are good to go. ### Start LocalStack Start LocalStack: ```bash lstk start ``` The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! ## Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. ### What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: - Developer auth tokens for local development - CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly [here.](https://app.localstack.cloud/settings/auth-tokens) Once you have the token, you’re ready to set it locally. One **important rule:** treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. ### Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. **Option 1: Use the LocalStack CLI** ```bash lstk login lstk start ``` **Option 2: Use an Environment Variable** If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: ```bash export LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` On Windows PowerShell: ```powershell $env:LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: ![LocalStack logs showing successful authentication"](../../assets/images/blog/first-local-aws-app-in-4-steps/ls-authenticated.png) ### Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: ```bash docker run -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} localstack/localstack ``` With Docker Compose: ```yaml environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` ## Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. **What This App Does** This sample is a shipment management application with: - A Spring Boot backend - A React frontend - Terraform-managed AWS infrastructure - Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. ![An architecture diagram of the shipment app"](../../assets/images/blog/first-local-aws-app-in-4-steps/architecture.png) ### Clone the Sample Application Start by cloning the repo: ```bash git clone https://github.com/localstack-samples/sample-terraform-fullstack-serverless-shipment-app.git cd sample-terraform-fullstack-serverless-shipment-app ``` ### Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: ```bash lstk start ``` If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. ### Install Project Dependencies Next, install everything the project needs: ```bash make install ``` This command handles a few things for you: - Builds the Lambda validator JAR ((Java ARchive)) - Installs frontend dependencies with npm - Prepares the project for deployment - You only need to run this once. ### Deploy the Infrastructure with Terraform This project uses [`lstk terraform`](https://docs.localstack.cloud/aws/integrations/infrastructure-as-code/terraform/) to run Terraform against LocalStack without any extra configuration. `lstk terraform` is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: ```bash make deploy ``` In the Makefile, the `deploy` target runs `lstk terraform init`, `lstk terraform plan`, and `lstk terraform apply`, which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: - S3 buckets for shipment images and Lambda code - A DynamoDB table pre-populated with sample shipments - A Lambda function for image validation and watermarking - SNS topics and SQS queues for messaging - All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. ### Start the Frontend In a new terminal, start the React frontend: ```bash cd shipment-list-frontend npm start ``` The frontend will be available at http://localhost:3000 ### Start the Backend In another terminal, start the Spring Boot backend: ```bash mvn spring-boot:run -Dspring-boot.run.profiles=dev ``` The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. ## Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 - See a list of shipments - Upload an image to a shipment - Watch that image get processed by a Lambda function - See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. ### Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: ```bash make test ``` This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: ```bash lstk stop ``` ## Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: 1. Installed LocalStack 2. Set up authentication 3. Deployed a real serverless app 4. Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.b5:T1cc5,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, install Docker Desktop first and come back here once it’s running. Install the LocalStack CLI The easiest way to work with LocalStack is through the CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out this link. Once installed, verify it worked: If you see a version number, you are good to go. Start LocalStack Start LocalStack: The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: Developer auth tokens for local development CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly here. Once you have the token, you’re ready to set it locally. One important rule: treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. Option 1: Use the LocalStack CLI Option 2: Use an Environment Variable If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: On Windows PowerShell: Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: With Docker Compose: Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. What This App Does This sample is a shipment management application with: A Spring Boot backend A React frontend Terraform-managed AWS infrastructure Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. Clone the Sample Application Start by cloning the repo: Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. Install Project Dependencies Next, install everything the project needs: This command handles a few things for you: Builds the Lambda validator JAR ((Java ARchive)) Installs frontend dependencies with npm Prepares the project for deployment You only need to run this once. Deploy the Infrastructure with Terraform This project uses to run Terraform against LocalStack without any extra configuration. is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: In the Makefile, the target runs , , and , which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: S3 buckets for shipment images and Lambda code A DynamoDB table pre-populated with sample shipments A Lambda function for image validation and watermarking SNS topics and SQS queues for messaging All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. Start the Frontend In a new terminal, start the React frontend: The frontend will be available at http://localhost:3000 Start the Backend In another terminal, start the Spring Boot backend: The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 See a list of shipments Upload an image to a shipment Watch that image get processed by a Lambda function See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: Installed LocalStack Set up authentication Deployed a real serverless app Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.5e:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mttxrig4o22y",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mttxreldxc2y"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/first-local-aws-app-in-4-steps/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mttxreldxc2y","tags":["AWS","Serverless","LocalDevelopment","DevEx","CloudEngineering"],"$type":"site.standard.document","title":"Run Your First AWS App Locally in 4 Simple Steps with LocalStack","content":{"text":"$b4","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-01-20T00:00:00.000Z","description":"Learn how to build and run your first AWS-style application entirely on your local machine. This step-by-step guide walks through installing LocalStack, configuring authentication, and deploying a real serverless app without deploying to AWS.","publishedAt":"2026-01-20T00:00:00.000Z","textContent":"$b5","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mttxrig4o22y","sort_date":"2026-01-20T00:00:00+00:00"}}] b6:T2394,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. ## Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. ### Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, [install Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) first and come back here once it’s running. ### Install the LocalStack CLI The easiest way to work with LocalStack is through the `lstk` CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out [this link.](https://docs.localstack.cloud/aws/getting-started/installation/) ```bash # macOS or Linux (Homebrew) brew install localstack/tap/lstk # Or via npm npm install -g @localstack/lstk ``` Once installed, verify it worked: ```bash lstk --version ``` If you see a version number, you are good to go. ### Start LocalStack Start LocalStack: ```bash lstk start ``` The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! ## Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. ### What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: - Developer auth tokens for local development - CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly [here.](https://app.localstack.cloud/settings/auth-tokens) Once you have the token, you’re ready to set it locally. One **important rule:** treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. ### Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. **Option 1: Use the LocalStack CLI** ```bash lstk login lstk start ``` **Option 2: Use an Environment Variable** If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: ```bash export LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` On Windows PowerShell: ```powershell $env:LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: ![LocalStack logs showing successful authentication"](../../assets/images/blog/first-local-aws-app-in-4-steps/ls-authenticated.png) ### Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: ```bash docker run -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} localstack/localstack ``` With Docker Compose: ```yaml environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` ## Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. **What This App Does** This sample is a shipment management application with: - A Spring Boot backend - A React frontend - Terraform-managed AWS infrastructure - Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. ![An architecture diagram of the shipment app"](../../assets/images/blog/first-local-aws-app-in-4-steps/architecture.png) ### Clone the Sample Application Start by cloning the repo: ```bash git clone https://github.com/localstack-samples/sample-terraform-fullstack-serverless-shipment-app.git cd sample-terraform-fullstack-serverless-shipment-app ``` ### Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: ```bash lstk start ``` If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. ### Install Project Dependencies Next, install everything the project needs: ```bash make install ``` This command handles a few things for you: - Builds the Lambda validator JAR ((Java ARchive)) - Installs frontend dependencies with npm - Prepares the project for deployment - You only need to run this once. ### Deploy the Infrastructure with Terraform This project uses [`lstk terraform`](https://docs.localstack.cloud/aws/integrations/infrastructure-as-code/terraform/) to run Terraform against LocalStack without any extra configuration. `lstk terraform` is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: ```bash make deploy ``` In the Makefile, the `deploy` target runs `lstk terraform init`, `lstk terraform plan`, and `lstk terraform apply`, which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: - S3 buckets for shipment images and Lambda code - A DynamoDB table pre-populated with sample shipments - A Lambda function for image validation and watermarking - SNS topics and SQS queues for messaging - All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. ### Start the Frontend In a new terminal, start the React frontend: ```bash cd shipment-list-frontend npm start ``` The frontend will be available at http://localhost:3000 ### Start the Backend In another terminal, start the Spring Boot backend: ```bash mvn spring-boot:run -Dspring-boot.run.profiles=dev ``` The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. ## Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 - See a list of shipments - Upload an image to a shipment - Watch that image get processed by a Lambda function - See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. ### Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: ```bash make test ``` This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: ```bash lstk stop ``` ## Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: 1. Installed LocalStack 2. Set up authentication 3. Deployed a real serverless app 4. Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.b7:T1cc5,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, install Docker Desktop first and come back here once it’s running. Install the LocalStack CLI The easiest way to work with LocalStack is through the CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out this link. Once installed, verify it worked: If you see a version number, you are good to go. Start LocalStack Start LocalStack: The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: Developer auth tokens for local development CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly here. Once you have the token, you’re ready to set it locally. One important rule: treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. Option 1: Use the LocalStack CLI Option 2: Use an Environment Variable If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: On Windows PowerShell: Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: With Docker Compose: Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. What This App Does This sample is a shipment management application with: A Spring Boot backend A React frontend Terraform-managed AWS infrastructure Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. Clone the Sample Application Start by cloning the repo: Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. Install Project Dependencies Next, install everything the project needs: This command handles a few things for you: Builds the Lambda validator JAR ((Java ARchive)) Installs frontend dependencies with npm Prepares the project for deployment You only need to run this once. Deploy the Infrastructure with Terraform This project uses to run Terraform against LocalStack without any extra configuration. is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: In the Makefile, the target runs , , and , which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: S3 buckets for shipment images and Lambda code A DynamoDB table pre-populated with sample shipments A Lambda function for image validation and watermarking SNS topics and SQS queues for messaging All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. Start the Frontend In a new terminal, start the React frontend: The frontend will be available at http://localhost:3000 Start the Backend In another terminal, start the Spring Boot backend: The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 See a list of shipments Upload an image to a shipment Watch that image get processed by a Lambda function See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: Installed LocalStack Set up authentication Deployed a real serverless app Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.5f:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mu2m52invs2p",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mu2m4upacs2p"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/first-local-aws-app-in-4-steps/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mu2m4upacs2p","tags":["AWS","Serverless","LocalDevelopment","DevEx","CloudEngineering"],"$type":"site.standard.document","title":"Run Your First AWS App Locally in 4 Simple Steps with LocalStack","content":{"text":"$b6","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-01-20T00:00:00.000Z","description":"Learn how to build and run your first AWS-style application entirely on your local machine. This step-by-step guide walks through installing LocalStack, configuring authentication, and deploying a real serverless app without deploying to AWS.","publishedAt":"2026-01-20T00:00:00.000Z","textContent":"$b7","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mu2m52invs2p","sort_date":"2026-01-20T00:00:00+00:00"}}] b8:T2394,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. ## Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. ### Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, [install Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) first and come back here once it’s running. ### Install the LocalStack CLI The easiest way to work with LocalStack is through the `lstk` CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out [this link.](https://docs.localstack.cloud/aws/getting-started/installation/) ```bash # macOS or Linux (Homebrew) brew install localstack/tap/lstk # Or via npm npm install -g @localstack/lstk ``` Once installed, verify it worked: ```bash lstk --version ``` If you see a version number, you are good to go. ### Start LocalStack Start LocalStack: ```bash lstk start ``` The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! ## Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. ### What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: - Developer auth tokens for local development - CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly [here.](https://app.localstack.cloud/settings/auth-tokens) Once you have the token, you’re ready to set it locally. One **important rule:** treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. ### Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. **Option 1: Use the LocalStack CLI** ```bash lstk login lstk start ``` **Option 2: Use an Environment Variable** If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: ```bash export LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` On Windows PowerShell: ```powershell $env:LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: ![LocalStack logs showing successful authentication"](../../assets/images/blog/first-local-aws-app-in-4-steps/ls-authenticated.png) ### Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: ```bash docker run -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} localstack/localstack ``` With Docker Compose: ```yaml environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` ## Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. **What This App Does** This sample is a shipment management application with: - A Spring Boot backend - A React frontend - Terraform-managed AWS infrastructure - Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. ![An architecture diagram of the shipment app"](../../assets/images/blog/first-local-aws-app-in-4-steps/architecture.png) ### Clone the Sample Application Start by cloning the repo: ```bash git clone https://github.com/localstack-samples/sample-terraform-fullstack-serverless-shipment-app.git cd sample-terraform-fullstack-serverless-shipment-app ``` ### Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: ```bash lstk start ``` If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. ### Install Project Dependencies Next, install everything the project needs: ```bash make install ``` This command handles a few things for you: - Builds the Lambda validator JAR ((Java ARchive)) - Installs frontend dependencies with npm - Prepares the project for deployment - You only need to run this once. ### Deploy the Infrastructure with Terraform This project uses [`lstk terraform`](https://docs.localstack.cloud/aws/integrations/infrastructure-as-code/terraform/) to run Terraform against LocalStack without any extra configuration. `lstk terraform` is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: ```bash make deploy ``` In the Makefile, the `deploy` target runs `lstk terraform init`, `lstk terraform plan`, and `lstk terraform apply`, which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: - S3 buckets for shipment images and Lambda code - A DynamoDB table pre-populated with sample shipments - A Lambda function for image validation and watermarking - SNS topics and SQS queues for messaging - All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. ### Start the Frontend In a new terminal, start the React frontend: ```bash cd shipment-list-frontend npm start ``` The frontend will be available at http://localhost:3000 ### Start the Backend In another terminal, start the Spring Boot backend: ```bash mvn spring-boot:run -Dspring-boot.run.profiles=dev ``` The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. ## Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 - See a list of shipments - Upload an image to a shipment - Watch that image get processed by a Lambda function - See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. ### Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: ```bash make test ``` This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: ```bash lstk stop ``` ## Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: 1. Installed LocalStack 2. Set up authentication 3. Deployed a real serverless app 4. Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.b9:T1cc5,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, install Docker Desktop first and come back here once it’s running. Install the LocalStack CLI The easiest way to work with LocalStack is through the CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out this link. Once installed, verify it worked: If you see a version number, you are good to go. Start LocalStack Start LocalStack: The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: Developer auth tokens for local development CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly here. Once you have the token, you’re ready to set it locally. One important rule: treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. Option 1: Use the LocalStack CLI Option 2: Use an Environment Variable If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: On Windows PowerShell: Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: With Docker Compose: Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. What This App Does This sample is a shipment management application with: A Spring Boot backend A React frontend Terraform-managed AWS infrastructure Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. Clone the Sample Application Start by cloning the repo: Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. Install Project Dependencies Next, install everything the project needs: This command handles a few things for you: Builds the Lambda validator JAR ((Java ARchive)) Installs frontend dependencies with npm Prepares the project for deployment You only need to run this once. Deploy the Infrastructure with Terraform This project uses to run Terraform against LocalStack without any extra configuration. is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: In the Makefile, the target runs , , and , which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: S3 buckets for shipment images and Lambda code A DynamoDB table pre-populated with sample shipments A Lambda function for image validation and watermarking SNS topics and SQS queues for messaging All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. Start the Frontend In a new terminal, start the React frontend: The frontend will be available at http://localhost:3000 Start the Backend In another terminal, start the Spring Boot backend: The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 See a list of shipments Upload an image to a shipment Watch that image get processed by a Lambda function See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: Installed LocalStack Set up authentication Deployed a real serverless app Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.60:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtynlxxojs23",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtynluy3ws23"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/first-local-aws-app-in-4-steps/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtynluy3ws23","tags":["AWS","Serverless","LocalDevelopment","DevEx","CloudEngineering"],"$type":"site.standard.document","title":"Run Your First AWS App Locally in 4 Simple Steps with LocalStack","content":{"text":"$b8","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-01-20T00:00:00.000Z","description":"Learn how to build and run your first AWS-style application entirely on your local machine. This step-by-step guide walks through installing LocalStack, configuring authentication, and deploying a real serverless app without deploying to AWS.","publishedAt":"2026-01-20T00:00:00.000Z","textContent":"$b9","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtynlxxojs23","sort_date":"2026-01-20T00:00:00+00:00"}}] ba:T2394,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. ## Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. ### Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, [install Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) first and come back here once it’s running. ### Install the LocalStack CLI The easiest way to work with LocalStack is through the `lstk` CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out [this link.](https://docs.localstack.cloud/aws/getting-started/installation/) ```bash # macOS or Linux (Homebrew) brew install localstack/tap/lstk # Or via npm npm install -g @localstack/lstk ``` Once installed, verify it worked: ```bash lstk --version ``` If you see a version number, you are good to go. ### Start LocalStack Start LocalStack: ```bash lstk start ``` The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! ## Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. ### What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: - Developer auth tokens for local development - CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly [here.](https://app.localstack.cloud/settings/auth-tokens) Once you have the token, you’re ready to set it locally. One **important rule:** treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. ### Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. **Option 1: Use the LocalStack CLI** ```bash lstk login lstk start ``` **Option 2: Use an Environment Variable** If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: ```bash export LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` On Windows PowerShell: ```powershell $env:LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: ![LocalStack logs showing successful authentication"](../../assets/images/blog/first-local-aws-app-in-4-steps/ls-authenticated.png) ### Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: ```bash docker run -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} localstack/localstack ``` With Docker Compose: ```yaml environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` ## Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. **What This App Does** This sample is a shipment management application with: - A Spring Boot backend - A React frontend - Terraform-managed AWS infrastructure - Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. ![An architecture diagram of the shipment app"](../../assets/images/blog/first-local-aws-app-in-4-steps/architecture.png) ### Clone the Sample Application Start by cloning the repo: ```bash git clone https://github.com/localstack-samples/sample-terraform-fullstack-serverless-shipment-app.git cd sample-terraform-fullstack-serverless-shipment-app ``` ### Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: ```bash lstk start ``` If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. ### Install Project Dependencies Next, install everything the project needs: ```bash make install ``` This command handles a few things for you: - Builds the Lambda validator JAR ((Java ARchive)) - Installs frontend dependencies with npm - Prepares the project for deployment - You only need to run this once. ### Deploy the Infrastructure with Terraform This project uses [`lstk terraform`](https://docs.localstack.cloud/aws/integrations/infrastructure-as-code/terraform/) to run Terraform against LocalStack without any extra configuration. `lstk terraform` is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: ```bash make deploy ``` In the Makefile, the `deploy` target runs `lstk terraform init`, `lstk terraform plan`, and `lstk terraform apply`, which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: - S3 buckets for shipment images and Lambda code - A DynamoDB table pre-populated with sample shipments - A Lambda function for image validation and watermarking - SNS topics and SQS queues for messaging - All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. ### Start the Frontend In a new terminal, start the React frontend: ```bash cd shipment-list-frontend npm start ``` The frontend will be available at http://localhost:3000 ### Start the Backend In another terminal, start the Spring Boot backend: ```bash mvn spring-boot:run -Dspring-boot.run.profiles=dev ``` The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. ## Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 - See a list of shipments - Upload an image to a shipment - Watch that image get processed by a Lambda function - See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. ### Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: ```bash make test ``` This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: ```bash lstk stop ``` ## Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: 1. Installed LocalStack 2. Set up authentication 3. Deployed a real serverless app 4. Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.bb:T1cc5,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, install Docker Desktop first and come back here once it’s running. Install the LocalStack CLI The easiest way to work with LocalStack is through the CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out this link. Once installed, verify it worked: If you see a version number, you are good to go. Start LocalStack Start LocalStack: The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: Developer auth tokens for local development CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly here. Once you have the token, you’re ready to set it locally. One important rule: treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. Option 1: Use the LocalStack CLI Option 2: Use an Environment Variable If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: On Windows PowerShell: Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: With Docker Compose: Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. What This App Does This sample is a shipment management application with: A Spring Boot backend A React frontend Terraform-managed AWS infrastructure Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. Clone the Sample Application Start by cloning the repo: Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. Install Project Dependencies Next, install everything the project needs: This command handles a few things for you: Builds the Lambda validator JAR ((Java ARchive)) Installs frontend dependencies with npm Prepares the project for deployment You only need to run this once. Deploy the Infrastructure with Terraform This project uses to run Terraform against LocalStack without any extra configuration. is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: In the Makefile, the target runs , , and , which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: S3 buckets for shipment images and Lambda code A DynamoDB table pre-populated with sample shipments A Lambda function for image validation and watermarking SNS topics and SQS queues for messaging All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. Start the Frontend In a new terminal, start the React frontend: The frontend will be available at http://localhost:3000 Start the Backend In another terminal, start the Spring Boot backend: The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 See a list of shipments Upload an image to a shipment Watch that image get processed by a Lambda function See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: Installed LocalStack Set up authentication Deployed a real serverless app Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.61:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muyy4tzwqk2d",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muyy4rav522d"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/first-local-aws-app-in-4-steps/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3muyy4rav522d","tags":["AWS","Serverless","LocalDevelopment","DevEx","CloudEngineering"],"$type":"site.standard.document","title":"Run Your First AWS App Locally in 4 Simple Steps with LocalStack","content":{"text":"$ba","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-01-20T00:00:00.000Z","description":"Learn how to build and run your first AWS-style application entirely on your local machine. This step-by-step guide walks through installing LocalStack, configuring authentication, and deploying a real serverless app without deploying to AWS.","publishedAt":"2026-01-20T00:00:00.000Z","textContent":"$bb","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3muyy4tzwqk2d","sort_date":"2026-01-20T00:00:00+00:00"}}] bc:T2394,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. ## Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. ### Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, [install Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) first and come back here once it’s running. ### Install the LocalStack CLI The easiest way to work with LocalStack is through the `lstk` CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out [this link.](https://docs.localstack.cloud/aws/getting-started/installation/) ```bash # macOS or Linux (Homebrew) brew install localstack/tap/lstk # Or via npm npm install -g @localstack/lstk ``` Once installed, verify it worked: ```bash lstk --version ``` If you see a version number, you are good to go. ### Start LocalStack Start LocalStack: ```bash lstk start ``` The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! ## Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. ### What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: - Developer auth tokens for local development - CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly [here.](https://app.localstack.cloud/settings/auth-tokens) Once you have the token, you’re ready to set it locally. One **important rule:** treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. ### Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. **Option 1: Use the LocalStack CLI** ```bash lstk login lstk start ``` **Option 2: Use an Environment Variable** If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: ```bash export LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` On Windows PowerShell: ```powershell $env:LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: ![LocalStack logs showing successful authentication"](../../assets/images/blog/first-local-aws-app-in-4-steps/ls-authenticated.png) ### Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: ```bash docker run -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} localstack/localstack ``` With Docker Compose: ```yaml environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` ## Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. **What This App Does** This sample is a shipment management application with: - A Spring Boot backend - A React frontend - Terraform-managed AWS infrastructure - Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. ![An architecture diagram of the shipment app"](../../assets/images/blog/first-local-aws-app-in-4-steps/architecture.png) ### Clone the Sample Application Start by cloning the repo: ```bash git clone https://github.com/localstack-samples/sample-terraform-fullstack-serverless-shipment-app.git cd sample-terraform-fullstack-serverless-shipment-app ``` ### Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: ```bash lstk start ``` If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. ### Install Project Dependencies Next, install everything the project needs: ```bash make install ``` This command handles a few things for you: - Builds the Lambda validator JAR ((Java ARchive)) - Installs frontend dependencies with npm - Prepares the project for deployment - You only need to run this once. ### Deploy the Infrastructure with Terraform This project uses [`lstk terraform`](https://docs.localstack.cloud/aws/integrations/infrastructure-as-code/terraform/) to run Terraform against LocalStack without any extra configuration. `lstk terraform` is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: ```bash make deploy ``` In the Makefile, the `deploy` target runs `lstk terraform init`, `lstk terraform plan`, and `lstk terraform apply`, which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: - S3 buckets for shipment images and Lambda code - A DynamoDB table pre-populated with sample shipments - A Lambda function for image validation and watermarking - SNS topics and SQS queues for messaging - All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. ### Start the Frontend In a new terminal, start the React frontend: ```bash cd shipment-list-frontend npm start ``` The frontend will be available at http://localhost:3000 ### Start the Backend In another terminal, start the Spring Boot backend: ```bash mvn spring-boot:run -Dspring-boot.run.profiles=dev ``` The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. ## Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 - See a list of shipments - Upload an image to a shipment - Watch that image get processed by a Lambda function - See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. ### Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: ```bash make test ``` This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: ```bash lstk stop ``` ## Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: 1. Installed LocalStack 2. Set up authentication 3. Deployed a real serverless app 4. Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.bd:T1cc5,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, install Docker Desktop first and come back here once it’s running. Install the LocalStack CLI The easiest way to work with LocalStack is through the CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out this link. Once installed, verify it worked: If you see a version number, you are good to go. Start LocalStack Start LocalStack: The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: Developer auth tokens for local development CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly here. Once you have the token, you’re ready to set it locally. One important rule: treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. Option 1: Use the LocalStack CLI Option 2: Use an Environment Variable If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: On Windows PowerShell: Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: With Docker Compose: Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. What This App Does This sample is a shipment management application with: A Spring Boot backend A React frontend Terraform-managed AWS infrastructure Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. Clone the Sample Application Start by cloning the repo: Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. Install Project Dependencies Next, install everything the project needs: This command handles a few things for you: Builds the Lambda validator JAR ((Java ARchive)) Installs frontend dependencies with npm Prepares the project for deployment You only need to run this once. Deploy the Infrastructure with Terraform This project uses to run Terraform against LocalStack without any extra configuration. is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: In the Makefile, the target runs , , and , which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: S3 buckets for shipment images and Lambda code A DynamoDB table pre-populated with sample shipments A Lambda function for image validation and watermarking SNS topics and SQS queues for messaging All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. Start the Frontend In a new terminal, start the React frontend: The frontend will be available at http://localhost:3000 Start the Backend In another terminal, start the Spring Boot backend: The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 See a list of shipments Upload an image to a shipment Watch that image get processed by a Lambda function See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: Installed LocalStack Set up authentication Deployed a real serverless app Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.62:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtymgvkgtk2g",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtymgro3ds2g"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/first-local-aws-app-in-4-steps/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtymgro3ds2g","tags":["AWS","Serverless","LocalDevelopment","DevEx","CloudEngineering"],"$type":"site.standard.document","title":"Run Your First AWS App Locally in 4 Simple Steps with LocalStack","content":{"text":"$bc","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-01-20T00:00:00.000Z","description":"Learn how to build and run your first AWS-style application entirely on your local machine. This step-by-step guide walks through installing LocalStack, configuring authentication, and deploying a real serverless app without deploying to AWS.","publishedAt":"2026-01-20T00:00:00.000Z","textContent":"$bd","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtymgvkgtk2g","sort_date":"2026-01-20T00:00:00+00:00"}}] be:T2394,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. ## Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. ### Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, [install Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) first and come back here once it’s running. ### Install the LocalStack CLI The easiest way to work with LocalStack is through the `lstk` CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out [this link.](https://docs.localstack.cloud/aws/getting-started/installation/) ```bash # macOS or Linux (Homebrew) brew install localstack/tap/lstk # Or via npm npm install -g @localstack/lstk ``` Once installed, verify it worked: ```bash lstk --version ``` If you see a version number, you are good to go. ### Start LocalStack Start LocalStack: ```bash lstk start ``` The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! ## Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. ### What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: - Developer auth tokens for local development - CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly [here.](https://app.localstack.cloud/settings/auth-tokens) Once you have the token, you’re ready to set it locally. One **important rule:** treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. ### Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. **Option 1: Use the LocalStack CLI** ```bash lstk login lstk start ``` **Option 2: Use an Environment Variable** If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: ```bash export LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` On Windows PowerShell: ```powershell $env:LOCALSTACK_AUTH_TOKEN="your-auth-token" ``` Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: ![LocalStack logs showing successful authentication"](../../assets/images/blog/first-local-aws-app-in-4-steps/ls-authenticated.png) ### Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: ```bash docker run -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} localstack/localstack ``` With Docker Compose: ```yaml environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` ## Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. **What This App Does** This sample is a shipment management application with: - A Spring Boot backend - A React frontend - Terraform-managed AWS infrastructure - Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. ![An architecture diagram of the shipment app"](../../assets/images/blog/first-local-aws-app-in-4-steps/architecture.png) ### Clone the Sample Application Start by cloning the repo: ```bash git clone https://github.com/localstack-samples/sample-terraform-fullstack-serverless-shipment-app.git cd sample-terraform-fullstack-serverless-shipment-app ``` ### Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: ```bash lstk start ``` If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. ### Install Project Dependencies Next, install everything the project needs: ```bash make install ``` This command handles a few things for you: - Builds the Lambda validator JAR ((Java ARchive)) - Installs frontend dependencies with npm - Prepares the project for deployment - You only need to run this once. ### Deploy the Infrastructure with Terraform This project uses [`lstk terraform`](https://docs.localstack.cloud/aws/integrations/infrastructure-as-code/terraform/) to run Terraform against LocalStack without any extra configuration. `lstk terraform` is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: ```bash make deploy ``` In the Makefile, the `deploy` target runs `lstk terraform init`, `lstk terraform plan`, and `lstk terraform apply`, which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: - S3 buckets for shipment images and Lambda code - A DynamoDB table pre-populated with sample shipments - A Lambda function for image validation and watermarking - SNS topics and SQS queues for messaging - All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. ### Start the Frontend In a new terminal, start the React frontend: ```bash cd shipment-list-frontend npm start ``` The frontend will be available at http://localhost:3000 ### Start the Backend In another terminal, start the Spring Boot backend: ```bash mvn spring-boot:run -Dspring-boot.run.profiles=dev ``` The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. ## Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 - See a list of shipments - Upload an image to a shipment - Watch that image get processed by a Lambda function - See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. ### Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: ```bash make test ``` This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: ```bash lstk stop ``` ## Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: 1. Installed LocalStack 2. Set up authentication 3. Deployed a real serverless app 4. Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.bf:T1cc5,LocalStack makes it possible to run AWS services locally so you can build and test cloud applications without constantly deploying to a real AWS account. Instead of waiting on remote resources or burning time and money just to see if something works, you can develop against a fully local AWS environment on your own machine. In this guide, we’re going to build your first local AWS app in four steps. You’ll install LocalStack, set your auth token, deploy a real serverless sample, and confirm it’s working. Nothing fancy. Just a clean “it runs on my laptop” win. Step 1: Install LocalStack Let’s start by getting LocalStack running on your machine. This part is pretty straightforward, and once it’s done, everything else builds on top of it. Prerequisites Before installing LocalStack, make sure Docker is installed and running. LocalStack runs inside a Docker container, so if Docker isn’t up, nothing else will be either. If you already use Docker for development, you’re good. If not, install Docker Desktop first and come back here once it’s running. Install the LocalStack CLI The easiest way to work with LocalStack is through the CLI. It handles starting and stopping the local AWS environment and keeps you from dealing with raw Docker commands. The instructions below will get you started if you're using MacOS, Linux, or running Node. If you're running Windows or something else check out this link. Once installed, verify it worked: If you see a version number, you are good to go. Start LocalStack Start LocalStack: The first time you run this, Docker will pull the LocalStack image, which can take a minute. After that, LocalStack will spin up a local AWS environment and run quietly in the background. At this point, you’ve got AWS running locally on your machine. Not bad for step one! Step 2: Configure Your Auth Token Now that LocalStack is running, there’s one more thing to take care of before we deploy anything: your auth token. If you’ve worked with API keys before, this will feel familiar. If not, don’t overthink it. This is mostly a one-time setup. What Is an Auth Token (and Why do I Need One)? Your auth token tells LocalStack who you are and what features you have access to. It’s how LocalStack knows whether you’re using the free tier, a paid plan, or running in CI. There are two main types: Developer auth tokens for local development CI auth tokens for automated workflows For this guide, you’ll be using a developer token. You can find the tokens page directly here. Once you have the token, you’re ready to set it locally. One important rule: treat your auth token like a password. Don’t check it into GitHub, and don’t paste it into screenshots. Set Your Auth Token You’ve got a couple of ways to set your token. Pick whichever feels more natural. Option 1: Use the LocalStack CLI Option 2: Use an Environment Variable If you prefer being explicit or you’re setting this up for scripts, you can export the token as an environment variable. On macOS or Linux: On Windows PowerShell: Once the variable is set, start LocalStack again if it isn’t already running. LocalStack will start authenticated and activate the appropriate features. Here's what you'll see in the logs: Using Docker or Docker Compose If you start LocalStack manually with Docker or Docker Compose, make sure the auth token gets passed into the container. With Docker: With Docker Compose: Step 3: Deploy Your First Local AWS App Now that LocalStack is running and authenticated, let's deploy a real application using Terraform, locally, against LocalStack. This isn't a simple Hello World example, It’s a shipment management app with a backend, a frontend, and multiple AWS services working together. What This App Does This sample is a shipment management application with: A Spring Boot backend A React frontend Terraform-managed AWS infrastructure Lambda-based image validation and processing You can create and manage shipments, upload images, and see those images processed by a Lambda function. Valid images get watermarked, invalid ones get rejected, and updates are pushed in real time. Clone the Sample Application Start by cloning the repo: Make Sure LocalStack Is Running Before deploying, make sure LocalStack is still running: If it’s already running, this won’t hurt anything. If it isn’t, this gets you back on track. Install Project Dependencies Next, install everything the project needs: This command handles a few things for you: Builds the Lambda validator JAR ((Java ARchive)) Installs frontend dependencies with npm Prepares the project for deployment You only need to run this once. Deploy the Infrastructure with Terraform This project uses to run Terraform against LocalStack without any extra configuration. is a thin wrapper around the Terraform CLI that automatically redirects AWS provider endpoints to LocalStack instead of real AWS. Now, let's deploy the entire stack locally: In the Makefile, the target runs , , and , which means the same Terraform files you’d use for AWS are applied locally with no code changes. The result is a local infrastructure deployment that behaves like AWS and provisions everything the app needs, including: S3 buckets for shipment images and Lambda code A DynamoDB table pre-populated with sample shipments A Lambda function for image validation and watermarking SNS topics and SQS queues for messaging All required IAM roles and permissions Terraform will output logs as it works through the deployment. Let it finish. When it’s done, you’ve got a full AWS-style backend running locally. Start the Frontend In a new terminal, start the React frontend: The frontend will be available at http://localhost:3000 Start the Backend In another terminal, start the Spring Boot backend: The backend will run at: http://localhost:8081 The dev profile is configured specifically for LocalStack, so no AWS endpoints or credentials need to change. Step 4: Explore and Experiment If you made it this far, you’ve already done something a lot of teams struggle with. You deployed real infrastructure, ran a full-stack app, and tested AWS-style workflows locally. Now let’s slow down for a second and make sure everything feels solid. If the app is working, you should be able to: Open the frontend at http://localhost:3000 See a list of shipments Upload an image to a shipment Watch that image get processed by a Lambda function See the UI update once processing completes If that all happened, congrats. You’re officially running AWS locally. Run Tests (Optional, but Recommended) If you want to run full end-to-end tests against the local infrastructure: This validates that the application behaves the same way it would against real AWS. Stop LocalStack when you are finished: Wrapping Up At this point, you’ve done more than just follow a tutorial. You stood up real AWS-style infrastructure, deployed a full-stack application with Terraform, and ran the entire workflow locally on your machine. To recap, you just: Installed LocalStack Set up authentication Deployed a real serverless app Verified it works locally That’s a solid foundation. From here, the next step is to take one of your own projects and swap AWS for LocalStack during development and testing. Welcome to local cloud development. Your laptop just got promoted 😉.63:["$","$L31","at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtwdf3mslc2u",{"publication":{"href":"https://blog.localstack.cloud","pubRecord":{"url":"https://blog.localstack.cloud","name":"LocalStack Blog","$type":"site.standard.publication","basicTheme":{"$type":"site.standard.theme.basic","accent":{"b":250,"g":133,"r":172,"$type":"site.standard.theme.color#rgb"},"background":{"b":10,"g":9,"r":8,"$type":"site.standard.theme.color#rgb"},"foreground":{"b":235,"g":227,"r":225,"$type":"site.standard.theme.color#rgb"},"accentForeground":{"b":255,"g":255,"r":255,"$type":"site.standard.theme.color#rgb"}},"description":"News, tutorials, and release notes from LocalStack — the local cloud development platform for AWS, Snowflake, and more.","preferences":{"showComments":true,"showMentions":true,"showPrevNext":false,"showFirstLast":false,"showInDiscover":true,"showRecommends":true,"prevNextDirection":"rtl"},"theme":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtwdesao3k2u"},"ownerDid":"@localstack.cloud","contributors":[{"did":"did:plc:tuj4ihtuielwdb7dfu7t3btk","handle":"localstack.cloud","displayName":"LocalStack"}],"documents":{"comments_on_documents":[{"count":0}],"document_mentions_in_bsky":[{"count":0}],"recommends_on_documents":[{"count":0}],"data":{"path":"/first-local-aws-app-in-4-steps/","site":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.publication/3mtwdesao3k2u","tags":["AWS","Serverless","LocalDevelopment","DevEx","CloudEngineering"],"$type":"site.standard.document","title":"Run Your First AWS App Locally in 4 Simple Steps with LocalStack","content":{"text":"$be","$type":"site.standard.content.markdown","version":"1.0"},"updatedAt":"2026-01-20T00:00:00.000Z","description":"Learn how to build and run your first AWS-style application entirely on your local machine. This step-by-step guide walks through installing LocalStack, configuring authentication, and deploying a real serverless app without deploying to AWS.","publishedAt":"2026-01-20T00:00:00.000Z","textContent":"$bf","theme":"$undefined","preferences":"$undefined"},"uri":"at://did:plc:tuj4ihtuielwdb7dfu7t3btk/site.standard.document/3mtwdf3mslc2u","sort_date":"2026-01-20T00:00:00+00:00"}}]

Tag: serverless

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Using AWS's Official MCP Servers with LocalStack

Teaching Claude to Teach AWS

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

AWS Deep Dives - Amazon SNS (Simple Notification Service)

Day 0.0.0 - Hello, World!

Run Your First AWS App Locally in 4 Simple Steps with LocalStack

Run Your First AWS App Locally in 4 Simple Steps with LocalStack

Run Your First AWS App Locally in 4 Simple Steps with LocalStack

Run Your First AWS App Locally in 4 Simple Steps with LocalStack

Run Your First AWS App Locally in 4 Simple Steps with LocalStack

Run Your First AWS App Locally in 4 Simple Steps with LocalStack

Run Your First AWS App Locally in 4 Simple Steps with LocalStack