How to Manage SMS Opt-Outs with Amazon Pinpoint

Managing SMS can be challenging due to the continued increase in global regulation. One of the common functions that needs to exist for you to be in compliance is to be able to opt out your customers from receiving your communication when they request. Amazon Pinpoint has the ability to automatically opt your customers out of SMS communications using predefined keywords such as, “stop” or “unsubscribe” when responding back to the number from which they do not want to receive communications. This is great in many cases because it does not require any extra configuration for you to remain in compliance with SMS regulations but if you are sending communications across multiple use cases this is not ideal. In this blog post we will explain how to manage SMS sending for multiple use cases while still remaining in compliance with SMS regulations.

The default setup for Pinpoint SMS includes an Opt-Out List whose standard functionality is to block opted-out numbers from all SMS communications from the entire account. With the standard configuration, your only option to remove an endpoint from the default Opt-Out List is to use the DeleteOptedOutNumber action via the API. This can only be done once every 30 days to curtail abusive sending so it’s not the ideal method for managing opt-outs. Note: If you do want to opt-out endpoints completely from your account you can always add Endpoints manually to the Opt-Out List via the PutOptedOutNumber Action and use “default” as the “OptOutListName.” Given the previous this means that the common scenario for many customers, needing to send transactional messages such as One Time Password (OTP) as well as marketing related materials, requires configuring new Opt-Out Lists.

The first step in allowing your customers to receive critical communications like OTPs but opt out of other communications like marketing materials is to make sure that each use case has its own Origination Identity (OID). This means that if you have two use cases for SMS, such as OTP and marketing related messaging, you need to procure an OID for each of them. This needs to be done for each country you plan on having support for sending SMS. While this increases your cost, it is the only way to accomplish differentiated sending across multiple use cases.

Prerequisites

• In order to manage Opt-Out Lists you need to use the V2 API for SMS and voice
  • You can do the setup using the V2 APIs and still use SendMessage if you would like, but setup of Opt-Out Lists are only available in the V2 API
• You must Purchase/Register an OID for each use-case in each country you plan to support
  • Example: If you are sending marketing materials and OTP messages in the US and are using a short code then you will need to purchase at least two short codes and register each use case.
    • If you need help determining what OID you need use this guide.

How to Create Opt-Out Lists and Send SMS
In order to manage opt-outs per origination identity(OID) you need to create an Opt-Out List for each use case. There are two ways to accomplish this, below you will find the process for each:

• Option 1
  • The easiest way to add an Opt-Out List to an OID is when you procure the number.
    • First create an Opt-Out List using CreateOptOutList
    • Then, when procuring a new number either by opening a case or using RequestPhoneNumber, specify the name of that Opt-Out List
      • Note: If you already have a number you can add an Opt-Out List with the UpdatePhoneNumber action
    • Use the PutKeyword action to add keywords
      • Create at least one Opt-In Action Keyword
        • This is the keyword that recipients can use to opt in to receiving your messages for the first time or they can also opt back into previously unsubscribed communications
    • You can now send messages using this phone number and opted-out recipients will be put in your Opt-Out List, not the default Global Account Opt-Out List

While this is a simple way of creating Opt-Out Lists it does not scale well if you are sending globally or are operating as an Independent Software Vendor (ISV) and have multiple locations, use cases, and configurations that you need to assign to lots of numbers.

• Option 2
  • Create a Pool
    • A Pool is a container for OIDs that share the same use case and thus, the same Opt-Out List. See the image below
    • Set an Opt-Out List for the Pool by using the UpdatePool Action and specifying the “OptOutListName”
  • Associate an OID to that Pool
    • You can have multiple OIDs per Pool if necessary
    • Note: Opt-Out Lists of OIDs and Pools must match, so if you previously associated an Opt-Out List to any OIDs you may need to update those OIDs to match that of the Pool prior to associating it with the Pool.
  • Send your SMS using the Pool Id or Pool Arn for the “OriginationIdentity” using the SendTextMessage Action

Conclusion
In this post you have learned how to create Opt-Out Lists that give you better control over how your customers opt out of your communications. Using custom Opt-Out Lists allows you to have multiple SMS use cases and gives your customers the ability to receive critical communications such as OTP, but not receive communications like marketing that they are not interested in. The V2 API for SMS and Voice has many more useful actions not possible with the V1 API so we encourage you to explore how it can further help you simplify and automate your applications.

Review the documentation for the V2 SMS and Voice API here
Confirm the origination IDs you will need here
Check out the support tiers comparison here

Resources
https://docs.aws.amazon.com/pinpoint/latest/apireference_smsvoicev2/Welcome.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-originating-identities-choosing.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-limitations-opt-out.html