Post Syndicated from Brett Ezell original https://aws.amazon.com/blogs/messaging-and-targeting/aws-end-user-messaging-sms-and-voice-v2-api-a-migration-guide-from-v1/

This blog covers the steps on how to upgrade to the latest APIs offered by AWS for SMS messaging.

IMPORTANT: Understanding this Migration in Context of Amazon Pinpoint’s End of Support

Amazon Pinpoint announced its end of support (EOS) on October 2026. However, if you are an existing customer using Amazon Pinpoint for SMS, your current SMS operations are not impacted by the EOS, and you are not required to migrate to the v2 API at this time.

This blog post details an optional upgrade path from the Amazon Pinpoint v1 SendMessages API to the AWS End User Messaging SMS and Voice v2 SendTextMessage API. Transitioning allows you to leverage enhanced capabilities and new features available exclusively in the v2 API.

Regarding your existing resources: Your SMS phone numbers and sender ID resources are already stored in AWS End User Messaging. There is no need to register new numbers (originators) or configure new Sender IDs if you choose to migrate your API usage as described here.

AWS End User Messaging provides developers with a scalable and cost-effective messaging infrastructure without compromising the safety, security, or results of their communications. Developers can integrate messaging over channels such as SMS, MMS, voice text-to-speech, WhatsApp and mobile push to support use cases such as one-time passwords (OTP) at sign-ups, account updates, appointment reminders, delivery notifications, promotions and more. AWS End User Messaging was renamed in 2024 as the new name for Amazon Pinpoint’s communication capabilities. For the SMS protocol, the service includes two sets of APIs, including SMS and Voice, version 2 API (v2 API), which provides enhanced capabilities and flexibility for customer communications and the original Amazon Pinpoint v1 API.

The End User Messaging SMS service provides core building blocks and is the core service in charge of SMS delivery for other AWS services, including Amazon Simple Notification Service (SNS), Amazon Cognito, and Amazon Connect. Transitioning to the v2 API allows customers using the older Amazon Pinpoint v1 API to access enhanced capabilities available now—like improved control via Configuration Sets, Phone Pools, Protect Configurations, and Registrations—as well as ensuring access to future features developed exclusively in the V2 APIs.

In this post, we will focus on why transitioning is beneficial and how developers can transition from Amazon Pinpoint’s v1 SendMessages API to the AWS End User Messaging SMS and Voice, version 2 (SendTextMessage) API. This move offers more functionality for creating custom messaging solutions and integrating seamlessly with third-party applications. Consolidating management and messaging into AWS End User Messaging provides customers with greater control and access to the features and capabilities described below.

What Are the Changes and Benefits of Migrating?

Migrating from the Pinpoint v1 SendMessages API to the AWS End User Messaging v2 SendTextMessage API offers several key advantages in plain language:

• Simpler Code: The new SendTextMessage API has a flatter, more straightforward structure compared to the nested configuration required by the old SendMessages API. This makes your code easier to write, read, and maintain.
• More Control Over Delivery: AWS End User Messaging introduces new tools that give you fine-grained control:
  • Configuration Sets: Apply specific rules for logging via Event Destinations, routing (using specific number pools), and opt-out management per message.
  • Phone Pools: Group your sending phone numbers or sender IDs to manage sender reputation, improve reliability with failover, and handle different use cases more effectively.
  • Protect Configurations: Set account-level safety rules, like blocking messages to certain countries, or filtering messages suspected to be Artificially Inflated Traffic (AIT), enhancing security and compliance.
  • Message Feedback: Enable detailed feedback mechanisms and track message conversion data like one time passcode conversions.
• Better Monitoring & Troubleshooting: With Configuration Sets and Event Destinations, you retain detailed delivery logs, Delivery Receipts (DLRs), and event tracking, similar to Pinpoint’s event streaming. This allows comprehensive monitoring via Amazon EventBridge, Amazon CloudWatch, Amazon Data Firehose, or Amazon SNS.
• Expanded Capabilities: The AWS End User Messaging v2 API exclusively supports Media Messaging Service (MMS) and includes integrated tools for managing control plane activities, such as sender registrations required in many countries.
• Future-Proofing: AWS is actively developing new features exclusively for the AWS End User Messaging v2 API. Migrating ensures you can leverage the latest advancements in messaging technology.

Understanding Key AWS End User Messaging Components

Migration involves understanding and utilizing several core AWS End User Messaging components:

Phone Pools

• What they are: A Phone Pool is a collection of your origination identities (phone numbers, Sender IDs) that share common settings. When you send a message using a pool, AWS End User Messaging can automatically select an appropriate identity from that pool.
• Benefits:
  • Improved Reliability: Pools provide automatic failover; if one number in the pool fails, another can be used.
  • Reputation Management: You can create separate pools for different use-cases, or types of messages (e.g., transactional vs. promotional) to isolate sender reputations.
  • Simplified Configuration: Apply settings like opt-out lists or two-way SMS configurations to the entire pool.
• When to Use: Pools are highly recommended for managing multiple origination identities, ensuring high availability, or separating traffic. However, they are optional. If you only use a single phone number or Sender ID for a specific use case, you can continue to specify that single identity directly in your SendTextMessage API calls.

Protect Configurations

• What they are: Protect Configurations allow you to define account-wide or configuration-set-level rules that safeguard against unwanted traffic, including Artificially Inflated Traffic (AIT) and messages to specific destinations. They operate using rules applied per country, which can be set to different modes: Block (prevent sending to specified countries), Monitor (analyze traffic for AIT risk without blocking, providing visibility), or Filter (automatically block messages suspected of being AIT based on risk analysis, in addition to blocking specified countries).
  • Read more about these capabilities
    • Protect Filter and Monitor for SMS Fraud
    • Blocking traffic to specific countries
• Benefits:
  • Enhanced Security: Prevent accidental or malicious sending to unintended destinations by explicitly blocking specific countries.
  • Proactive AIT Defense (Filter): Automatically block suspected fraudulent SMS pumping traffic based on risk analysis before messages are sent, reducing exposure to financial costs and potential reputation damage associated with AIT.
  • Risk Visibility (Monitor): Gain insights into potential AIT patterns targeting your account and understand the likely impact of Filter rules without disrupting legitimate message delivery. Recommendations are provided via event destinations.
  • Compliance: Helps enforce geographic sending restrictions required by regulations or internal policies.
  • Cost Control: Avoid unexpected charges from sending to blocked/filtered destinations.
  • Granular Application: Apply different rules (Block/Monitor/Filter) per country and use multiple Protect Configurations tailored to different workflows (e.g., stricter filtering for public-facing forms vs. internal notifications).
• Note: Protect Configurations, including the Monitor and Filter modes for AIT, are features unique to the AWS End User Messaging v2 API and are not available in the Pinpoint v1 API. Check out Defending Against SMS Pumping: New AWS Features to Help Combat Artificially Inflated Traffic to learn more.

Configuration Sets

• What they are: Configuration Sets are collections of rules applied to messages when you send them. You specify which Configuration Set to use in your SendTextMessage API call.
• Benefits:
  • Essential for Monitoring: Configuration Sets are required to receive message event data (including Delivery Receipts – DLRs). They replace the automatic event streaming provided by Pinpoint v1. You must associate an Event Destination (EventBridge, CloudWatch Logs, Amazon Data Firehose, or SNS) with your Configuration Set to capture delivery status, failures, and other events.
  • Granular Control: Apply specific settings per message, such as routing messages through specific Phone Pools, using different default Sender IDs, or associating different opt-out lists.
  • Message Feedback: Enable detailed feedback mechanisms.
• Key Takeaway: Migrating users must create and use Configuration Sets with associated Event Destinations if they need to monitor message delivery status, replicating the functionality previously provided by Pinpoint event streams.

Registrations

• What they are: In many countries and regions, regulations require businesses to register their Sender IDs or phone numbers (like US 10DLC numbers) before sending A2P (Application-to-Person) messages. Some regions (like India or China) may also require pre-registering message templates.
• Benefits:
  • Compliance: Ensures adherence to local telecommunication laws and carrier requirements.
  • Improved Deliverability: Registered traffic is often treated with higher priority and is less likely to be filtered as spam by carriers.
• When Needed: Registration requirements — or lack thereof — vary significantly by country (e.g., US 10DLC, UK Sender IDs, India Sender IDs) and the type of number/Sender ID used. While some origination identities in certain regions may not require pre-registration, the landscape is complex and evolving. Always check the AWS documentation for the specific, current requirements of the countries you send messages to. AWS End User Messaging provides tools within the console and API to help manage any necessary registrations.

Additional Key Differences & Benefits

• MMS Support: The AWS End User Messaging v2 API provides clear, first-class support for sending Multimedia Messaging Service (MMS) messages via the SendMediaMessage API call, offering richer media possibilities than typically available via the older Pinpoint API.
• API Simplicity: The SendTextMessage API call is significantly less nested and complex than the SendMessages API structure, making integration and maintenance easier.
  • Example Comparison:

  • # Pinpoint v1 SendMessages (Nested Structure)
    response = pinpoint_client.send_messages(
        ApplicationId='YOUR_PINPOINT_PROJECT_ID',
        MessageRequest={
            'Addresses': {
                '+12065550100': { # Destination Address
                    'ChannelType': 'SMS'
                }
            },
            'MessageConfiguration': {
                'SMSMessage': {
                    'Body': 'Your message content',
                    'MessageType': 'TRANSACTIONAL',
                    'OriginationNumber': '+12065550199' # Origination Number
                }
            }
        }
    )
    
    # AWS End User Messaging v2 SendTextMessage (Flatter Structure)
    response = end_user_messaging_client.send_text_message(
        DestinationPhoneNumber='+12065550100',
        OriginationIdentity='+12065550199', # Can be Number, SenderID, Pool ARN/ID
        MessageBody='Your message content',
        MessageType='TRANSACTIONAL'
        # Optional: ConfigurationSetName='MyConfigSet'
    )

    This side-by-side comparison clearly shows the reduced nesting and more direct parameter usage in the AWS End User Messaging SendTextMessage API call.

• Broader Regional Availability: The AWS End User Messaging v2 API offers significantly broader regional availability compared to the older Pinpoint v1 API (currently supported in over 30 regions versus 13). AWS also plans to expand this support to an additional 4 regions soon (reaching 34 total), further improving global reach and potentially reducing latency.

How to Use AWS End User Messaging Features Functionally (API Examples)

Here’s how you use the SendTextMessage API (using AWS SDK for Python Boto3 as an example) to leverage these features:

import boto3
import logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)

# Initialize the AWS End User Messaging v2 client
# Note the client name change from 'pinpoint'
end_user_messaging_client = boto3.client('pinpoint-sms-voice-v2')

# --- Basic SMS Send ---
try:
    response = end_user_messaging_client.send_text_message(
        DestinationPhoneNumber='+12065550100',
        OriginationIdentity='+12065550199', # Your AWS End User Messaging registered Phone Number, Sender ID, or Pool ARN/ID
        MessageBody='Hello from AWS End User Messaging!',
        MessageType='TRANSACTIONAL' # Or 'PROMOTIONAL'
    )
    logger.info(f"Basic Send - Message ID: {response.get('MessageId')}")
except Exception as e:
    logger.error(f"Basic Send Failed: {e}")

# --- Send with a Configuration Set (for DLRs/Events) ---
try:
    response = end_user_messaging_client.send_text_message(
        DestinationPhoneNumber='+12065550101',
        OriginationIdentity='+12065550199',
        MessageBody='This message uses a configuration set.',
        MessageType='TRANSACTIONAL',
        ConfigurationSetName='MyConfigSet' # Specify your Configuration Set
    )
    logger.info(f"Config Set Send - Message ID: {response.get('MessageId')}")
except Exception as e:
    logger.error(f"Config Set Send Failed: {e}")

# --- Send using a Phone Pool ---
try:
    response = end_user_messaging_client.send_text_message(
        DestinationPhoneNumber='+12065550102',
        OriginationIdentity='arn:aws:sms-voice:us-east-1:111122223333:pool/MyPhonePool', # Use Pool ARN or ID
        MessageBody='This message is sent via a phone pool.',
        MessageType='TRANSACTIONAL',
        ConfigurationSetName='MyConfigSet' # Still need a Config Set for events
    )
    logger.info(f"Pool Send - Message ID: {response.get('MessageId')}")
except Exception as e:
    logger.error(f"Pool Send Failed: {e}")

# --- Send with a Protect Configuration (via Config Set or directly) ---
# Option 1: Protect Config applied via Configuration Set
# (Configure association in the AWS End User Messaging console or via AssociateProtectConfiguration API)
# No change needed in SendTextMessage call beyond specifying the ConfigurationSetName

# Option 2: Protect Config applied directly per message
try:
    response = end_user_messaging_client.send_text_message(
        DestinationPhoneNumber='+12065550103',
        OriginationIdentity='+12065550199',
        MessageBody='This message has direct protect config applied.',
        MessageType='TRANSACTIONAL',
        ProtectConfigurationId='MyProtectConfig' # Specify Protect Configuration ID or ARN
        # ConfigurationSetName='MyConfigSet' # Can also be used if needed for other rules like events
    )
    logger.info(f"Protect Config Send - Message ID: {response.get('MessageId')}")
except Exception as e:
    logger.error(f"Protect Config Send Failed: {e}")

# --- Standard Exception Handling ---
try:
    response = end_user_messaging_client.send_text_message(
        DestinationPhoneNumber='+12065550104',
        OriginationIdentity='+12065550199',
        MessageBody='Testing exception handling.',
        MessageType='TRANSACTIONAL',
        ConfigurationSetName='MyConfigSet'
    )
    logger.info(f"Exception Test Send - Message ID: {response.get('MessageId')}")
except end_user_messaging_client.exceptions.ThrottlingException:
    logger.error("Rate limit exceeded. Implementing backoff.")
except end_user_messaging_client.exceptions.ValidationException as e:
    logger.error(f"Validation error: {str(e)}")
except Exception as e:
     logger.error(f"Generic error sending message: {e}")

How to Migrate SDKs

Migrating your application code involves updating your AWS SDK initialization:

1. Identify SDK Usage: Locate where your code uses the AWS SDK to interact with the Pinpoint v1 API, specifically for sending SMS (likely using client.send_messages(...)).
2. Update Client Initialization: Change the service client you initialize.
   • Python (Boto3): Change boto3.client('pinpoint') to boto3.client('pinpoint-sms-voice-v2').
   • Other SDKs: Consult the specific AWS SDK documentation for the equivalent change. The service identifier will typically change from pinpoint or similar to pinpoint-sms-voice-v2 or equivalent.
3. Update API Calls: Replace calls to the Pinpoint v1 SendMessages operation with calls to the AWS End User Messaging v2 SendTextMessage operation, adjusting the parameter structure as shown in the examples above.
4. Dependencies: Ensure your application deployment includes the necessary updated SDK libraries.

Data Migration Considerations

Endpoint Contextual Data: Pinpoint allows associating rich attributes and user data with endpoints, often used in campaigns. If your application logic for sending direct SMS via the Pinpoint SendMessages API previously relied on accessing these Pinpoint endpoint attributes at the time of sending (e.g., for personalization), note that the AWS End User Messaging SendTextMessage API operates independently of the Pinpoint endpoint data model. Your application will now need to fetch any required contextual data (user attributes, preferences, etc.) itself before calling SendTextMessage if that information is needed for message construction or logic.

Opt-Out Lists (Optional):

IMPORTANT: End User Messaging has automatically been adding opt-outs to a “default optout list” for all SMS you have sent out unless you have been self managing opt-outs. Check to see if you have numbers in the “default” list in the console or by using DescribeOptedOutNumbers and using “default” as the OptOutListName.

If you are managing opt-outs at the endpoint level, managing them within your application, or only have opt-outs in the “default” list, it’s recommended that you export those numbers into a new End User Messaging Opt-Out List.

1. Extract from Pinpoint: Identify and extract the phone numbers opted out of SMS within your Pinpoint project. This typically involves exporting endpoint data (using the Pinpoint API, like GetEndPoints, or GetSegmentExportJobs) and filtering for endpoints associated with the SMS channel that have an OptOut status set (e.g., ALL). You may need custom processing to isolate the correct phone numbers.
2. Create AWS End User Messaging List: Create a new opt-out list in AWS End User Messaging using the CreateOptOutList API operation (e.g., name it MigratedPinpointOptOuts).
3. Import Numbers: Add the phone numbers extracted from Pinpoint into the newly created AWS End User Messaging opt-out list using the PutOptedOutNumber API operation for each number.
4. Associate List: Associate your new AWS End User Messaging Opt-Out List with the relevant Phone Pool(s) or individual origination phone number(s)/Sender ID(s) using the appropriate AWS End User Messaging API calls (e.g., SetDefaultPoolOptOutList, SetPhoneNumberOptedOut). This ensures AWS End User Messaging automatically blocks sends to these numbers when using those specific origination identities. Note: Opt-out lists are associated with origination identities, not directly with Configuration Sets.

Here’s an accurate AWS SDK for Python (Boto3) example that demonstrates this process:

import boto3

# Initialize clients
pinpoint = boto3.client('pinpoint')
eum = boto3.client('pinpoint-sms-voice-v2')

# Step 1: Extract opted-out numbers from Pinpoint
def get_opted_out_numbers(project_id):
    opted_out_numbers = set()
    paginator = pinpoint.get_paginator('get_endpoints')
    
    for page in paginator.paginate(ApplicationId=project_id):
        for item in page['ItemResponse'].values():
            if item['ChannelType'] == 'SMS' and item.get('OptOut') == 'ALL':
                opted_out_numbers.add(item['Address'])
    
    return opted_out_numbers

# Example usage
project_id = 'YOUR_PINPOINT_PROJECT_ID'
opted_out_numbers = get_opted_out_numbers(project_id)

# Step 2: Create AWS End User Messaging Opt-Out List
opt_out_list_name = 'MigratedPinpointOptOuts'
eum.create_opt_out_list(OptOutListName=opt_out_list_name)

# Step 3: Import Numbers to the new Opt-Out List
for number in opted_out_numbers:
    eum.put_opted_out_number(
        OptOutListName=opt_out_list_name,
        OptedOutNumber=number
    )

# Step 4: Associate the Opt-Out List with a Phone Pool
phone_pool_id = 'YOUR_PHONE_POOL_ID'
eum.set_default_pool_opt_out_list(
    PhonePoolId=phone_pool_id,
    OptOutListName=opt_out_list_name
)

# If you're using individual numbers not in a pool:
# phone_number = 'YOUR_PHONE_NUMBER'
# eum.set_phone_number_opted_out(
#     PhoneNumber=phone_number,
#     OptOutListName=opt_out_list_name
# )

print(f"Migration complete. {len(opted_out_numbers)} numbers added to the opt-out list.")

Conclusion

Migrating from the legacy Amazon Pinpoint v1 SendMessages API to the modern AWS End User Messaging v2 SendTextMessage API aligns strategically with End User Messaging, the focus of AWS’s ongoing messaging development and advancements. As we’ve explored, this transition is driven by tangible benefits and enhanced capabilities designed for contemporary communication needs.

This guide detailed the key advantages, including a significantly simplified API structure that streamlines development and maintenance. We also covered the core components that provide enhanced control and functionality: Configuration Sets, which are crucial for enabling detailed monitoring and delivery reporting (DLRs); Phone Pools for flexible and reliable sender identity management; Protect Configurations for improved security and compliance; and Registrations for adhering to regional requirements and maximizing deliverability.

This post also outlined the practical steps involved in this migration, from updating your SDK client initialization and adapting your code to use the SendTextMessage API with its new features, to the critical process of migrating existing opt-out lists to ensure continuity and compliance.

By understanding these components, leveraging the new features, and executing the necessary technical and data migration steps, you can successfully transition your SMS operations. This move not only modernizes your infrastructure but also positions you to take full advantage of future advancements on the AWS End User Messaging platform, enabling you to build more robust, scalable, and sophisticated messaging solutions.