Amazon Simple Notification Service
Developer Guide (API Version 2010-03-31)

Setting SMS Messaging Preferences

Use Amazon SNS to specify preferences for SMS messaging, such as how your deliveries are optimized (for cost or for reliable delivery), your monthly spending limit, how message deliveries are logged, and whether to subscribe to daily SMS usage reports.

These preferences take effect for every SMS message that you send from your account, but you can override some of them when you send an individual message. For more information, see Sending an SMS Message.

Setting Preferences (Console)

  1. Sign in to the AWS Management Console and open the Amazon SNS console at

  2. In the console menu, set the region selector to a region that supports SMS messaging.

  3. In the navigation pane, choose Text messaging (SMS).

  4. On the Text messaging (SMS) page, choose Manage text messaging preferences.

  5. On the Text messaging preferences page, for Default message type, select the type of SMS message that you will usually send:

    • Promotional (default) – Noncritical messages, such as marketing messages. Amazon SNS optimizes the message delivery to incur the lowest cost.

    • Transactional – Critical messages that support customer transactions, such as one-time passcodes for multi-factor authentication. Amazon SNS optimizes the message delivery to achieve the highest reliability.

    You can override this setting when you send a message.

    For pricing information for promotional and transactional messages, see Global SMS Pricing.

  6. For Account spend limit, type the maximum amount in USD that you want to spend on SMS messages each calendar month. When Amazon SNS determines that sending an SMS message would incur a cost that exceeds your spend limit for that month, Amazon SNS stops publishing SMS messages within minutes.


    Because Amazon SNS is a distributed system, it stops sending SMS messages within a time interval of minutes of the spend limit being exceeded. During that interval, if you continue to send SMS messages, you may incur costs that exceed your limit.

    By default, the spend limit is set to 1.00 USD. If you want to raise the limit, submit an SNS Limit Increase case. For New limit value, enter your desired monthly spend limit. In the Use Case Description field, explain that you are requesting an SMS monthly spend limit increase.

  7. For IAM role for CloudWatch Logs access, create an IAM role that allows Amazon SNS to write logs for SMS deliveries in CloudWatch Logs:

    1. Choose Create IAM role.

    2. On the SNS is requesting permission to use resources in your account page, choose Allow.

  8. For Default percentage of success to sample, specify the percentage of successful SMS deliveries for which Amazon SNS will write logs in CloudWatch Logs. For example, to write logs only for failed deliveries, set this value to 0. To write logs for 10% of your successful deliveries, set it to 10. If you don't specify a percentage, Amazon SNS writes logs for all successful deliveries.

  9. For Default sender ID, type a custom ID that contains up to 11 alphanumeric characters, including at least one letter and no spaces. The sender ID is displayed as the message sender on the receiving device. For example, you can use your business brand to make the message source easier to recognize.

    Support for sender IDs varies by country. For example, messages delivered to U.S. phone numbers will not display the sender ID. For the countries that support sender IDs, see Supported Regions and Countries.

    If you do not specify a sender ID, the message will display a long code as the sender ID in supported countries. For countries that require an alphabetic sender ID, the message displays NOTICE as the sender ID.

    You can override the this setting when you send a message.

  10. For Reports storage, type the name of the Amazon S3 bucket to receive daily SMS usage reports from Amazon SNS. Amazon SNS does not create daily usage reports unless you specify an Amazon S3 bucket to receive them. For more information, see Viewing Daily SMS Usage Reports.

  11. Choose Update preferences.

Setting Preferences (AWS SDKs)

To set your SMS preferences by using one of AWS SDKs, use the action in that SDK that corresponds to the SetSMSAttributes request in the Amazon SNS API. With this request, you assign values to the different SMS attributes, such as your monthly spend limit and your default SMS type (promotional or transactional). For all SMS attributes, see SetSMSAttributes in the Amazon Simple Notification Service API Reference.

Setting Preferences (AWS SDK for Java)

The following example uses the setSMSAttributes method of the AmazonSNSClient class to set values for the different attribute names:

public static void main(String[] args) { AmazonSNSClient snsClient = new AmazonSNSClient(); setDefaultSmsAttributes(snsClient); } public static void setDefaultSmsAttributes(AmazonSNSClient snsClient) { SetSMSAttributesRequest setRequest = new SetSMSAttributesRequest() .addAttributesEntry("DefaultSenderID", "mySenderID") .addAttributesEntry("MonthlySpendLimit", "1") .addAttributesEntry("DeliveryStatusIAMRole", "arn:aws:iam::123456789012:role/mySnsRole") .addAttributesEntry("DeliveryStatusSuccessSamplingRate", "10") .addAttributesEntry("DefaultSMSType", "Transactional") .addAttributesEntry("UsageReportS3Bucket", "sns-sms-daily-usage"); snsClient.setSMSAttributes(setRequest); Map<String, String> myAttributes = snsClient.getSMSAttributes(new GetSMSAttributesRequest()) .getAttributes(); System.out.println("My SMS attributes:"); for (String key : myAttributes.keySet()) { System.out.println(key + " = " + myAttributes.get(key)); } }

This example sets the value for the MonthlySpendLimit attribute to 1.00 USD. By default, this is the maximum amount allowed by Amazon SNS. If you want to raise this limit, submit an SNS Limit Increase case. For New limit value, enter your desired monthly spend limit. In the Use Case Description field, explain that you are requesting an SMS monthly spend limit increase.

To verify that the attributes were set correctly, the example prints the result of the getSMSAttributes method. When you run this example, the attributes are displayed in the console output window of your IDE:

My SMS attributes: DeliveryStatusSuccessSamplingRate = 10 UsageReportS3Bucket = sns-sms-daily-usage DefaultSMSType = Transactional DeliveryStatusIAMRole = arn:aws:iam::123456789012:role/mySnsRole MonthlySpendLimit = 1 DefaultSenderID = mySenderID