Email notifications - Amazon Simple Notification Service

Email notifications

This page describes how to subscribe an email address to an Amazon SNS topic using the AWS Management Console, AWS SDK for Java, or AWS SDK for .NET.

Notes
  • You can't customize the body of the email message. The email delivery feature is intended to provide internal system alerts, not marketing messages.

  • Email delivery throughput is throttled according to Amazon SNS quotas.

To subscribe an email address to an Amazon SNS topic using the AWS Management Console

  1. Sign in to the Amazon SNS console.

  2. In the left navigation pane, choose Subscriptions.

  3. On the Subscriptions page, choose Create subscription.

  4. On the Create subscription page, in the Details section, do the following:

    1. For Topic ARN, choose the Amazon Resource Name (ARN) of a topic.

    2. For Protocol, choose Email.

    3. For Endpoint, enter the email address.

    4. (Optional) To configure a filter policy, expand the Subscription filter policy section. For more information, see Amazon SNS subscription filter policies.

    5. (Optional) To configure a dead-letter queue for the subscription, expand the Redrive policy (dead-letter queue) section. For more information, see Amazon SNS dead-letter queues (DLQs).

    6. Choose Create subscription.

      The console creates the subscription and opens the subscription's Details page.

You must confirm the subscription before the email address can start to receive messages.

To confirm a subscription

  1. Check your email inbox and choose Confirm subscription in the email from Amazon SNS.

  2. Amazon SNS opens your web browser and displays a subscription confirmation with your subscription ID.

To subscribe an email address to an Amazon SNS topic using an AWS SDK

To use an AWS SDK, you must configure it with your credentials. For more information, see The shared config and credentials files in the AWS SDKs and Tools Reference Guide.

The following code examples show how to subscribe an email address to an Amazon SNS topic.

C++
SDK for C++

/** * Subscribe an email address endpoint to a topic - demonstrates how to initiate a subscription to an Amazon SNS topic with delivery * to an email address. * * SNS will send a subscription confirmation email to the email address provided which you need to confirm to * receive messages. * * <protocol_value> set to "email" provides delivery of message via SMTP (see https://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html for available protocols). * <topic_arn_value> can be obtained from run_list_topics executable and includes the "arn:" prefix. */ int main(int argc, char ** argv) { if (argc != 4) { std::cout << "Usage: subscribe_email <protocol_value=email> <topic_arn_value>" " <email_address>" << std::endl; return 1; } Aws::SDKOptions options; Aws::InitAPI(options); { Aws::SNS::SNSClient sns; Aws::String protocol = argv[1]; Aws::String topic_arn = argv[2]; Aws::String endpoint = argv[3]; Aws::SNS::Model::SubscribeRequest s_req; s_req.SetTopicArn(topic_arn); s_req.SetProtocol(protocol); s_req.SetEndpoint(endpoint); auto s_out = sns.Subscribe(s_req); if (s_out.IsSuccess()) { std::cout << "Subscribed successfully " << std::endl; } else { std::cout << "Error while subscribing " << s_out.GetError().GetMessage() << std::endl; } } Aws::ShutdownAPI(options); return 0; }
  • Find instructions and more code on GitHub.

Go
SDK for Go V2
  • Find instructions and more code on GitHub.

Java
SDK for Java 2.x

public static void subEmail(SnsClient snsClient, String topicArn, String email) { try { SubscribeRequest request = SubscribeRequest.builder() .protocol("email") .endpoint(email) .returnSubscriptionArn(true) .topicArn(topicArn) .build(); SubscribeResponse result = snsClient.subscribe(request); System.out.println("Subscription ARN: " + result.subscriptionArn() + "\n\n Status is " + result.sdkHttpResponse().statusCode()); } catch (SnsException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } }
  • Find instructions and more code on GitHub.

JavaScript
SDK for JavaScript V3

Create the client in a separate module and export it.

import { SNSClient } from "@aws-sdk/client-sns"; // Set the AWS Region. const REGION = "REGION"; //e.g. "us-east-1" // Create SNS service object. const snsClient = new SNSClient({ region: REGION }); export { snsClient };

Import the SDK and client modules and call the API.

// Import required AWS SDK clients and commands for Node.js import {SubscribeCommand } from "@aws-sdk/client-sns"; import {snsClient } from "./libs/snsClient.js"; // Set the parameters const params = { Protocol: "email" /* required */, TopicArn: "TOPIC_ARN", //TOPIC_ARN Endpoint: "EMAIL_ADDRESS", //EMAIL_ADDRESS }; const run = async () => { try { const data = await snsClient.send(new SubscribeCommand(params)); console.log("Success.", data); return data; // For unit tests. } catch (err) { console.log("Error", err.stack); } }; run();
PHP
SDK for PHP

require 'vendor/autoload.php'; use Aws\Sns\SnsClient; use Aws\Exception\AwsException; /** * Prepares to subscribe an endpoint by sending the endpoint a confirmation message. * * This code expects that you have AWS credentials set up per: * https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/guide_credentials.html */ $SnSclient = new SnsClient([ 'profile' => 'default', 'region' => 'us-east-1', 'version' => '2010-03-31' ]); $protocol = 'email'; $endpoint = 'sample@example.com'; $topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic'; try { $result = $SnSclient->subscribe([ 'Protocol' => $protocol, 'Endpoint' => $endpoint, 'ReturnSubscriptionArn' => true, 'TopicArn' => $topic, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails error_log($e->getMessage()); }
  • Find instructions and more code on GitHub.

Python
SDK for Python (Boto3)

class SnsWrapper: """Encapsulates Amazon SNS topic and subscription functions.""" def __init__(self, sns_resource): """ :param sns_resource: A Boto3 Amazon SNS resource. """ self.sns_resource = sns_resource def subscribe(topic, protocol, endpoint): """ Subscribes an endpoint to the topic. Some endpoint types, such as email, must be confirmed before their subscriptions are active. When a subscription is not confirmed, its Amazon Resource Number (ARN) is set to 'PendingConfirmation'. :param topic: The topic to subscribe to. :param protocol: The protocol of the endpoint, such as 'sms' or 'email'. :param endpoint: The endpoint that receives messages, such as a phone number (in E.164 format) for SMS messages, or an email address for email messages. :return: The newly added subscription. """ try: subscription = topic.subscribe( Protocol=protocol, Endpoint=endpoint, ReturnSubscriptionArn=True) logger.info("Subscribed %s %s to topic %s.", protocol, endpoint, topic.arn) except ClientError: logger.exception( "Couldn't subscribe %s %s to topic %s.", protocol, endpoint, topic.arn) raise else: return subscription
  • Find instructions and more code on GitHub.

Ruby
SDK for Ruby

require 'aws-sdk-sns' # v2: require 'aws-sdk' def subscription_created?(sns_client, topic_arn, protocol, endpoint) sns_client.subscribe(topic_arn: topic_arn, protocol: protocol, endpoint: endpoint) rescue StandardError => e puts "Error while creating the subscription: #{e.message}" end # Full example call: def run_me protocol = 'email' endpoint = 'EMAIL_ADDRESS' topic_arn = 'TOPIC_ARN' region = 'REGION' sns_client = Aws::SNS::Client.new(region: region) puts "Creating the subscription." if subscription_created?(sns_client, topic_arn, protocol, endpoint) puts 'The subscriptions was created.' else puts 'The subscription was not created. Stopping program.' exit 1 end end run_me if $PROGRAM_NAME == __FILE__