Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
Managing phone numbers and SMS subscriptions
Amazon SNS provides several options for managing who receives SMS messages from your
account. With a limited frequency, you can opt in phone numbers that have opted out
of receiving SMS messages from your account. To stop sending messages to SMS
subscriptions, you can remove subscriptions or the topics that publish to
them.
Opting out of receiving SMS messages
Where required by local laws and regulations (such as the US and Canada), SMS
recipients can use their devices to opt out by replying to the message with any
of the following:
-
ARRET (French)
-
CANCEL
-
END
-
OPT-OUT
-
OPTOUT
-
QUIT
-
REMOVE
-
STOP
-
TD
-
UNSUBSCRIBE
To opt out, the recipient must reply to the same origination
number that Amazon SNS used to deliver the message. After opting out, the
recipient will no longer receive SMS messages delivered from your Amazon Web Services account unless you
opt in the phone number.
If the phone number is subscribed to an Amazon SNS topic, opting out does not
remove the subscription, but SMS messages will fail to deliver to that
subscription unless you opt in the phone number.
Managing phone numbers and subscriptions
(console)
You can use the Amazon SNS console to control which phone numbers receive SMS
messages from your account.
Opting in a phone number that
has been opted out
You can view which phone numbers have been opted out of receiving SMS
messages from your account, and you can opt in these phone numbers to resume
sending messages to them.
You can opt in a phone number only once every 30 days.
Sign in to the Amazon SNS console.
-
In the console menu, set the region selector to a region that supports SMS
messaging.
-
On the navigation panel, choose Text messaging
(SMS).
-
On the Text messaging (SMS) page, choose
View opted out phone numbers. The
Opted out phone numbers page displays the
opted out phone numbers.
-
Select the check box for the phone number that you want to opt in,
and choose Opt in. The phone number is no
longer opted out and will receive SMS messages that you send to
it.
Deleting an SMS
subscription
Delete an SMS subscription to stop sending SMS messages to that phone
number when you publish to your topics.
-
On the navigation panel, choose
Subscriptions.
-
Select the check boxes for the subscriptions that you want to
delete. Then choose Actions, and choose
Delete Subscriptions.
-
In the Delete window, choose
Delete. Amazon SNS deletes the subscription and
displays a success message.
Deleting a topic
Delete a topic when you no longer want to publish messages to its
subscribed endpoints.
-
On the navigation panel, choose
Topics.
-
Select the check boxes for the topics that you want to delete.
Then choose Actions, and choose
Delete Topics.
-
In the Delete window, choose
Delete. Amazon SNS deletes the topic and
displays a success message.
Managing phone numbers and subscriptions (Amazon
SDKs)
You can use the Amazon SDKs to make programmatic requests to Amazon SNS and manage
which phone numbers can receive SMS messages from your account.
To use an Amazon SDK, you must configure it with your credentials. For more information, see
The shared config and credentials files
in the Amazon SDKs and Tools Reference Guide.
Viewing all opted out phone
numbers
To view all opted out phone numbers, submit a
ListPhoneNumbersOptedOut
request with the Amazon SNS API.
The following code examples show how to list phone numbers that are opted out of receiving Amazon SNS messages.
- Java
-
- SDK for Java 2.x
-
public static void listOpts( SnsClient snsClient) {
try {
ListPhoneNumbersOptedOutRequest request = ListPhoneNumbersOptedOutRequest.builder().build();
ListPhoneNumbersOptedOutResponse result = snsClient.listPhoneNumbersOptedOut(request);
System.out.println("Status is " + result.sdkHttpResponse().statusCode() + "\n\nPhone Numbers: \n\n" + result.phoneNumbers());
} catch (SnsException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
- PHP
-
- SDK for PHP
-
require 'vendor/autoload.php';
use Aws\Sns\SnsClient;
use Aws\Exception\AwsException;
/**
* Returns a list of phone numbers that are opted out of receiving SMS messages from your AWS SNS account.
*
* 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'
]);
try {
$result = $SnSclient->listPhoneNumbersOptedOut([
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
Checking whether a phone number is
opted out
To check whether a phone number is opted out, submit a
CheckIfPhoneNumberIsOptedOut
request with the Amazon SNS
API.
The following code examples show how to check whether a phone number is opted out of receiving Amazon SNS messages.
- .NET
-
- Amazon SDK for .NET
-
using System;
using System.Threading.Tasks;
using Amazon.SimpleNotificationService;
using Amazon.SimpleNotificationService.Model;
/// <summary>
/// This example shows how to use the Amazon Simple Notification Service
/// (Amazon SNS) to check whether a phone number has been opted out. The
/// example was created using the AWS SDK for .NET version 3.7 and
/// .NET Core 5.0.
/// </summary>
public class IsPhoneNumOptedOut
{
public static async Task Main()
{
string phoneNumber = "+15551112222";
IAmazonSimpleNotificationService client = new AmazonSimpleNotificationServiceClient();
await CheckIfOptedOutAsync(client, phoneNumber);
}
/// <summary>
/// Checks to see if the supplied phone number has been opted out.
/// </summary>
/// <param name="client">The initialized Amazon SNS Client object used
/// to check if the phone number has been opted out.</param>
/// <param name="phoneNumber">A string representing the phone number
/// to check.</param>
public static async Task CheckIfOptedOutAsync(IAmazonSimpleNotificationService client, string phoneNumber)
{
var request = new CheckIfPhoneNumberIsOptedOutRequest
{
PhoneNumber = phoneNumber,
};
try
{
var response = await client.CheckIfPhoneNumberIsOptedOutAsync(request);
if (response.HttpStatusCode == System.Net.HttpStatusCode.OK)
{
string optOutStatus = response.IsOptedOut ? "opted out" : "not opted out.";
Console.WriteLine($"The phone number: {phoneNumber} is {optOutStatus}");
}
}
catch (AuthorizationErrorException ex)
{
Console.WriteLine($"{ex.Message}");
}
}
}
- Java
-
- SDK for Java 2.x
-
public static void checkPhone(SnsClient snsClient, String phoneNumber) {
try {
CheckIfPhoneNumberIsOptedOutRequest request = CheckIfPhoneNumberIsOptedOutRequest.builder()
.phoneNumber(phoneNumber)
.build();
CheckIfPhoneNumberIsOptedOutResponse result = snsClient.checkIfPhoneNumberIsOptedOut(request);
System.out.println(result.isOptedOut() + "Phone Number " + phoneNumber + " has Opted Out of receiving sns messages." +
"\n\nStatus was " + result.sdkHttpResponse().statusCode());
} catch (SnsException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
- JavaScript
-
- SDK for JavaScript (v3)
-
Create the client in a separate module and export it.
import { SNSClient } from "@aws-sdk/client-sns";
// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});
Import the SDK and client modules and call the API.
import { CheckIfPhoneNumberIsOptedOutCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";
export const checkIfPhoneNumberIsOptedOut = async (
phoneNumber = "5555555555"
) => {
const command = new CheckIfPhoneNumberIsOptedOutCommand({
phoneNumber,
});
const response = await snsClient.send(command);
console.log(response);
// {
// '$metadata': {
// httpStatusCode: 200,
// requestId: '3341c28a-cdc8-5b39-a3ee-9fb0ee125732',
// extendedRequestId: undefined,
// cfId: undefined,
// attempts: 1,
// totalRetryDelay: 0
// },
// isOptedOut: false
// }
return response;
};
- PHP
-
- SDK for PHP
-
require 'vendor/autoload.php';
use Aws\Sns\SnsClient;
use Aws\Exception\AwsException;
/**
* Indicates whether the phone number owner has opted out of receiving SMS messages from your AWS SNS account.
*
* 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'
]);
$phone = '+1XXX5550100';
try {
$result = $SnSclient->checkIfPhoneNumberIsOptedOut([
'phoneNumber' => $phone,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
Opting in a phone number that has
been opted out
To opt in a phone number, submit an OptInPhoneNumber
request
with the Amazon SNS API.
You can opt in a phone number only once every 30 days.
Deleting an SMS
subscription
To delete an SMS subscription from an Amazon SNS topic, get the subscription
ARN by submitting a ListSubscriptions
request with the Amazon SNS
API, and then pass the ARN to an Unsubscribe
request.
The following code examples show how to delete an Amazon SNS subscription.
- .NET
-
- Amazon SDK for .NET
-
Unsubscribe from a topic by a subscription ARN.
/// <summary>
/// Unsubscribe from a topic by a subscription ARN.
/// </summary>
/// <param name="subscriptionArn">The ARN of the subscription.</param>
/// <returns>True if successful.</returns>
public async Task<bool> UnsubscribeByArn(string subscriptionArn)
{
var unsubscribeResponse = await _amazonSNSClient.UnsubscribeAsync(
new UnsubscribeRequest()
{
SubscriptionArn = subscriptionArn
});
return unsubscribeResponse.HttpStatusCode == HttpStatusCode.OK;
}
- C++
-
- SDK for C++
-
//! Delete a subscription to an Amazon Simple Notification Service (Amazon SNS) topic.
/*!
\param subscriptionARN: The Amazon Resource Name (ARN) for an Amazon SNS topic subscription.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::SNS::unsubscribe(const Aws::String &subscriptionARN,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::SNS::SNSClient snsClient(clientConfiguration);
Aws::SNS::Model::UnsubscribeRequest request;
request.SetSubscriptionArn(subscriptionARN);
const Aws::SNS::Model::UnsubscribeOutcome outcome = snsClient.Unsubscribe(request);
if (outcome.IsSuccess()) {
std::cout << "Unsubscribed successfully " << std::endl;
}
else {
std::cerr << "Error while unsubscribing " << outcome.GetError().GetMessage()
<< std::endl;
}
return outcome.IsSuccess();
}
- Java
-
- SDK for Java 2.x
-
public static void unSub(SnsClient snsClient, String subscriptionArn) {
try {
UnsubscribeRequest request = UnsubscribeRequest.builder()
.subscriptionArn(subscriptionArn)
.build();
UnsubscribeResponse result = snsClient.unsubscribe(request);
System.out.println("\n\nStatus was " + result.sdkHttpResponse().statusCode()
+ "\n\nSubscription was removed for " + request.subscriptionArn());
} catch (SnsException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
- JavaScript
-
- SDK for JavaScript (v3)
-
Create the client in a separate module and export it.
import { SNSClient } from "@aws-sdk/client-sns";
// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});
Import the SDK and client modules and call the API.
import { UnsubscribeCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";
/**
* @param {string} subscriptionArn - The ARN of the subscription to cancel.
*/
const unsubscribe = async (
subscriptionArn = "arn:aws:sns:us-east-1:xxxxxxxxxxxx:mytopic:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
) => {
const response = await snsClient.send(
new UnsubscribeCommand({
SubscriptionArn: subscriptionArn,
})
);
console.log(response);
// {
// '$metadata': {
// httpStatusCode: 200,
// requestId: '0178259a-9204-507c-b620-78a7570a44c6',
// extendedRequestId: undefined,
// cfId: undefined,
// attempts: 1,
// totalRetryDelay: 0
// }
// }
return response;
};
- Kotlin
-
- SDK for Kotlin
-
This is prerelease documentation for a feature in preview release. It is subject to change.
suspend fun unSub(subscriptionArnVal: String) {
val request = UnsubscribeRequest {
subscriptionArn = subscriptionArnVal
}
SnsClient { region = "us-east-1" }.use { snsClient ->
snsClient.unsubscribe(request)
println("Subscription was removed for ${request.subscriptionArn}")
}
}
- PHP
-
- SDK for PHP
-
require 'vendor/autoload.php';
use Aws\Sns\SnsClient;
use Aws\Exception\AwsException;
/**
* Deletes a subscription to an Amazon SNS topic.
*
* 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'
]);
$subscription = 'arn:aws:sns:us-east-1:111122223333:MySubscription';
try {
$result = $SnSclient->unsubscribe([
'SubscriptionArn' => $subscription,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
- 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
@staticmethod
def delete_subscription(subscription):
"""
Unsubscribes and deletes a subscription.
"""
try:
subscription.delete()
logger.info("Deleted subscription %s.", subscription.arn)
except ClientError:
logger.exception("Couldn't delete subscription %s.", subscription.arn)
raise
- SAP ABAP
-
- SDK for SAP ABAP
-
TRY.
lo_sns->unsubscribe( iv_subscriptionarn = iv_subscription_arn ).
MESSAGE 'Subscription deleted.' TYPE 'I'.
CATCH /aws1/cx_snsnotfoundexception.
MESSAGE 'Subscription does not exist.' TYPE 'E'.
CATCH /aws1/cx_snsinvalidparameterex.
MESSAGE 'Subscription with "PendingConfirmation" status cannot be deleted/unsubscribed. Confirm subscription before performing unsubscribe operation.' TYPE 'E'.
ENDTRY.
Deleting a topic
To delete a topic and all of its subscriptions, get the topic ARN by
submitting a ListTopics
request with the Amazon SNS API, and then
pass the ARN to the DeleteTopic
request.
The following code examples show how to delete an Amazon SNS topic and all subscriptions to that topic.
- .NET
-
- Amazon SDK for .NET
-
Delete a topic by its topic ARN.
/// <summary>
/// Delete a topic by its topic ARN.
/// </summary>
/// <param name="topicArn">The ARN of the topic.</param>
/// <returns>True if successful.</returns>
public async Task<bool> DeleteTopicByArn(string topicArn)
{
var deleteResponse = await _amazonSNSClient.DeleteTopicAsync(
new DeleteTopicRequest()
{
TopicArn = topicArn
});
return deleteResponse.HttpStatusCode == HttpStatusCode.OK;
}
- C++
-
- SDK for C++
-
//! Delete an Amazon Simple Notification Service (Amazon SNS) topic.
/*!
\param topicARN: The Amazon Resource Name (ARN) for an Amazon SNS topic.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::SNS::deleteTopic(const Aws::String &topicARN,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::SNS::SNSClient snsClient(clientConfiguration);
Aws::SNS::Model::DeleteTopicRequest request;
request.SetTopicArn(topicARN);
const Aws::SNS::Model::DeleteTopicOutcome outcome = snsClient.DeleteTopic(request);
if (outcome.IsSuccess()) {
std::cout << "Successfully deleted the Amazon SNS topic " << topicARN << std::endl;
}
else {
std::cerr << "Error deleting topic " << topicARN << ":" <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
- Java
-
- SDK for Java 2.x
-
public static void deleteSNSTopic(SnsClient snsClient, String topicArn ) {
try {
DeleteTopicRequest request = DeleteTopicRequest.builder()
.topicArn(topicArn)
.build();
DeleteTopicResponse result = snsClient.deleteTopic(request);
System.out.println("\n\nStatus was " + result.sdkHttpResponse().statusCode());
} catch (SnsException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
- JavaScript
-
- SDK for JavaScript (v3)
-
Create the client in a separate module and export it.
import { SNSClient } from "@aws-sdk/client-sns";
// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});
Import the SDK and client modules and call the API.
import { DeleteTopicCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";
/**
* @param {string} topicArn - The ARN of the topic to delete.
*/
export const deleteTopic = async (topicArn = "TOPIC_ARN") => {
const response = await snsClient.send(
new DeleteTopicCommand({ TopicArn: topicArn })
);
console.log(response);
// {
// '$metadata': {
// httpStatusCode: 200,
// requestId: 'a10e2886-5a8f-5114-af36-75bd39498332',
// extendedRequestId: undefined,
// cfId: undefined,
// attempts: 1,
// totalRetryDelay: 0
// }
// }
};
- Kotlin
-
- SDK for Kotlin
-
This is prerelease documentation for a feature in preview release. It is subject to change.
suspend fun deleteSNSTopic(topicArnVal: String) {
val request = DeleteTopicRequest {
topicArn = topicArnVal
}
SnsClient { region = "us-east-1" }.use { snsClient ->
snsClient.deleteTopic(request)
println("$topicArnVal was successfully deleted.")
}
}
- PHP
-
- SDK for PHP
-
require 'vendor/autoload.php';
use Aws\Sns\SnsClient;
use Aws\Exception\AwsException;
/**
* Deletes a SNS topic and all its subscriptions.
*
* 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'
]);
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->deleteTopic([
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
- 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
@staticmethod
def delete_topic(topic):
"""
Deletes a topic. All subscriptions to the topic are also deleted.
"""
try:
topic.delete()
logger.info("Deleted topic %s.", topic.arn)
except ClientError:
logger.exception("Couldn't delete topic %s.", topic.arn)
raise
- SAP ABAP
-
- SDK for SAP ABAP
-
TRY.
lo_sns->deletetopic( iv_topicarn = iv_topic_arn ).
MESSAGE 'SNS topic deleted.' TYPE 'I'.
CATCH /aws1/cx_snsnotfoundexception.
MESSAGE 'Topic does not exist.' TYPE 'E'.
ENDTRY.