Modernizing SMS communications: Transitioning from Amazon Pinpoint API to AWS End User Messaging SMS and Voice, version 2 API for multi-business-unit enterprises

Introduction

In today's digital business environment, reliable and scalable messaging capabilities are essential for customer engagement, operational notifications, and service alerts. AWS Enterprise Support partnered with a customer to modernize their SMS communication stack. To accomplish this, they transitioned the stack from Amazon Pinpoint API to AWS End User Messaging SMS and Voice, version API. This enterprise-wide transformation included operations across four distinct business units and achieved a 30% reduction in operational overhead.

This transition was particularly critical because the company needed to enhance their messaging solution capabilities across multiple business units, each with unique requirements. The existing implementation faced significant limitations in governance, cost management, and operational efficiency. 

By transitioning to AWS End User Messaging SMS and Voice, version 2 API, enterprises with complex multi-business-unit structures can achieve enhanced governance and monitoring. They can also maintain the flexibility and isolation that each of their business units requires and ultimately deliver better customer experiences at lower operational costs.

This article explores how Enterprise Support worked with the customer to design and implement an enterprise-grade SMS messaging solution that supports multiple business units. It also covers strategies required to implement a flexible messaging platform that serves diverse business requirements while maintaining compliance across all units.

Customer challenges

A customer with operations that span across different business units used Amazon Pinpoint as their primary SMS communication channel. The variety of use cases from their different business units created significant challenges in management, governance, and customer experience.

When Enterprise Support found this problem during a business review, they identified an opportunity to significantly improve the customer's messaging infrastructure. The Enterprise Support team demonstrated how the new AWS End User Messaging SMS and Voice, version 2 API features could address the customer's challenges while providing enhanced capabilities. After initial discussions, the team led the modernization effort across all the customer's business units.

The customer faced the following critical challenges with their existing implementation:

• Complex self-management opt-out system: The customer maintained their own opt-out databases and logic across multiple business units, creating significant operational overhead and inconsistent best practices. This self-managed approach required dedicated engineering resources and introduced risks of regulatory non-compliance. Maintenance of self-managed opt-out systems required significant engineering resources across each business unit, with dedicated teams handling database management and API development. 

• Inability to apply SMS Protect settings specifically for One Time Password (OTP) messages: The customer could only apply Amazon Pinpoint's SMS Protect settings broadly across an entire account. This setting prevented them from implementing targeted protection for high-risk OTP authentication messages while maintaining different settings for other message types. This limitation was particularly problematic for their online account access system that required stronger protection against artificially inflated traffic (AIT) attacks.

• Lack of comprehensive metrics: Amazon Pinpoint provided limited visibility into message delivery performance. The customer couldn’t effectively track key metrics, such as delivery rates, SMS Protect effectiveness, and message feedback. This lack of data made it difficult to set up alarms and identify issues.

• Absence of message feedback loop: The platform lacked a robust feedback loop mechanism to capture message delivery status. Without this critical information, the customer needed to depend on Delivery Receipts (DLR) that were either best effort or took up to 72 hours to return.

Solution implementation

API changes and migration

Amazon's new AWS End User Messaging SMS and Voice, version 2 API provides a streamlined alternative to the original Amazon Pinpoint API and delivers significant improvements in both structure and functionality. The new SendtextMessage API adopts a flatter parameter structure with direct options, such as DestinationPhoneNumber and MessageBody. These parameters replace Amazon Pinpoint's complex SendMessages nested configurations with Addresses and MessageConfiguration objects.

AWS End User Messaging SMS and Voice, version 2 API introduces features that aren’t available in Amazon Pinpoint API, such as the following:

• DryRun for testing without sending messages

• MaxPrice for cost control

• TimeToLive for message expiration

These improvements make the new API more intuitive and provide enhanced control over SMS messaging operations.

You use the following configuration to initialize the Amazon Pinpoint API:

pinpoint_client = boto3.client("pinpoint")

However, use the following configuration to initialize AWS End User Messaging SMS and Voice, version 2 API:

sms_voice_v2_client = boto3.client('pinpoint-sms-voice-v2')

The differences in the API methods between the two services are outlined in the following table:

	Feature	Amazon Pinpoint API	AWS End User Messaging, version 2 API
1	Method name	send_messages()	send_text_message()
2	Configuration	Requires Amazon Pinpoint project/application ID	Uses ConfigurationSet
3	Message structure	Nested format with Addresses and MessageConfiguration	Flatter parameter structure with direct configuration
4	Response format	Nested response objects	Direct access to message properties

The differences in API parameters are outlined in the following table:

	Amazon Pinpoint API	AWS End User Messaging SMS and Voice, version 2 API	Remarks
1	ApplicationId	ConfigurationSetName	The Amazon Pinpoint API is project-based and requires an ApplicationId. AWS End User Messaging SMS and Voice, version 2 API is resource-based and uses rule-driven ConfigurationSets for control and monitoring.
2	Addresses with ChannelType	DestinationPhoneNumber	Direct phone number parameter
3	Not available	DryRun	Test mode without sending
4	Not available	MaxPrice	Cost control feature
5	MessageConfiguration.SMSMessage.Body	MessageBody	Simplified structure
6	MessageConfiguration.SMSMessage.MessageType	MessageType	MessageType can either be TRANSACTIONAL or PROMOTIONAL
7	MessageConfiguration.SMSMessage.OriginationNumber	OriginationIdentity	Supports originating identities, such as PhoneNumber, PhoneNumberId/Arn, SenderId/Arn, and PoolId/Arn
8	Not available	TimeToLive	Message expiration in seconds

Response handling is similar to the following for the Amazon Pinpoint API:

# *Nested response structure requiring navigation*
message_id = response\["MessageResponse"\]\["Result"\]\[destination_number\]\["MessageId"\]

Response handling is significantly simplified in the new AWS End User Messaging SMS and Voice, version 2 API:

# *Direct access to message ID*
message_id = response\['MessageId'\]

This streamlined response structure and specific exception handling reduces code complexity and improves reliability so that developers can directly access critical information, such as message IDs, and handle failures gracefully.

Phone pools

A key component of the solution was implementation of dedicated phone pools through the CreatePool API for different business units and message types. A phone pool is a collection of phone numbers or sender IDs that share the same settings and can be used to send messages. When you send messages through a phone pool, it automatically selects an appropriate origination identity to send the message. If an origination identity in the phone pool fails, then the phone pool automatically fails over to another origination identity within the same pool. After you create the phone pool, you can add more origination identities to it with the AssociateOriginationIdentity API.

This approach provided the following benefits:

• Business unit separation through dedicated phone numbers

• Separation of message types into promotional and transactional

• Improved failover capabilities for critical messages

• Enhanced branding consistency for each business unit

Configuration sets

With the solution, the customer could implement separate configuration sets through the CreateConfigurationSet API for each business unit and message type instead of using a single configuration set. All configuration sets shared the same event destination that the CreateEventDestination API created. This setup allowed for centralized event processing and maintained business unit separation.

This approach provided the following benefits:

• Business unit-specific SMS Protect settings

• Message type-specific configuration

• Centralized event processing through shared destinations

• Enhanced governance through standardized configuration

OTP-specific SMS Protect settings

Another improvement was the implementation of targeted SMS Protect settings for OTP messages. The team configured enhanced protection specifically for authentication workflows. This feature wasn’t available with Amazon Pinpoint's account-wide settings.

This targeted approach allowed the customer to do the following:

• Apply strict protection for high-risk OTP messages

• Maintain appropriate settings for other message types

• Significantly reduce AIT attacks on authentication workflows

The customer created a dedicated protect configuration through the CreateProtectConfiguration API. Then, they associated this configuration with the configuration set through the AssociateProtectConfiguration API with specific rules for OTP messages.

Message feedback tracking

The solution included comprehensive message feedback tracking. This is a capability that provides critical visibility into the messaging workflow and isn’t in Amazon Pinpoint. To turn on this feature, the implementation used the SetDefaultMessageFeedbackEnabled API on the relevant configuration set. The team then updated the application to use the PutMessageFeedback API to send events back to AWS End User Messaging. This setup provided a closed-loop system that allowed the customer to do the following:

• Confirm when authentication codes were successfully used

• Gain critical visibility into the end-to-end authentication workflow

• Gather data for analyzing user conversion and potential delivery issues

AWS managed opt-out system

The team implemented a comprehensive AWS managed opt-out system through AWS End User Messaging SMS and Voice, version 2 API while maintaining business-specific controls. This architecture allowed customers to control their messaging preferences at the business unit level while using robust opt-out infrastructure within AWS. 

This process required the following tasks:

• Creating business unit-specific opt-out lists in AWS End User Messaging through the CreateOptOutList API.

• Migrating existing opt-out numbers from their internal infrastructure into the respective business unit opt-out list through the PutOptedOutNumber API.

• Associating each opt-out list with the appropriate phone pools through the UpdatePool API to make sure that AWS End User Messaging enforces opt-out preferences for each business unit.

Enhanced default metrics

AWS End User Messaging provides comprehensive default metrics that are unavailable in Amazon Pinpoint, such as the following:

• Message delivery metrics: Track successful deliveries, failures, and carrier responses.

• SMS Protect metrics: Monitor blocked messages, artificially inflated traffic, and spam detection.

• Message feedback metrics: Signals from the end customer about delivery.

• Message spend metrics: Monthly spend limit metrics.

These default metrics provide immediate visibility to improve operational monitoring. Also, because AWS End User Messaging provides account-level metrics by default, the team created a custom solution that pushed events to Amazon CloudWatch metrics through AWS Lambda. This allowed for business unit-specific metrics and reporting while maintaining centralized governance.

The team created custom CloudWatch dashboards and alarms to track the following metrics:

• Delivery rates by business unit message type and country

• Cost allocation across business units

IAM policies for each business unit

To maintain proper access control and allow business units to manage their own messaging operations, the team implemented granular AWS Identity and Access Management (IAM) policies through the following actions:

• Creating business unit-specific IAM roles and policies

Example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SendTextMessagesViaSpecificPhonePools",
      "Effect": "Allow",
      "Action": "sms-voice:SendTextMessage",
      "Resource": "arn:aws:sms-voice:region:accountId:pool/poolId"
    }
  ]
}

• Implementing least-privilege access principles

Conclusion

The customer partnered with Enterprise Support and successfully consolidated their fragmented Amazon Pinpoint implementations into a unified AWS End User Messaging platform. The solution specifically addressed the critical limitations of their previous multi-account approach, such as complex account management, inability to apply OTP-specific SMS Protect settings, and lack of comprehensive SMS metrics.

The AWS End User Messaging service provided significant additional advantages, including streamlined registration APIs, enhanced phone pool management, and advanced configuration capabilities. These features allowed the customer to maintain business unit separation while benefiting from centralized governance and analytics.

The customer now operates a modernized enterprise messaging infrastructure that addresses their previous challenges and provides a scalable foundation for future business unit needs. For comprehensive guidance on migrating from v1 to v2, see AWS End User Messaging SMS and Voice v2 API: A migration guide from v1.

To learn more about how AWS Support can help you optimize your messaging operations and implement best practices for customer communications across multiple business units, see AWS Support.

---

About the authors

Sarath Kumar Kallayil Sreedharan

Sarath Kumar is a Senior Technical Account Manager at AWS. Sarath works with Enterprise Support customers to help them architect and build highly reliable and cost-effective solutions on AWS. He specializes in serverless, messaging technologies, and generative AI services, and has a background in application development and architecture. In his spare time, he enjoys reading, traveling, playing cricket, and spending time with his family.

Nideesh K T

Nideesh is an experienced IT professional with expertise in cloud computing and technical support. Nideesh has been working in the technology industry for 9 years. In his current role as a Senior Technical Account Manager, Nideesh provides technical assistance and architect cloud applications to Enterprise Support customers. Outside of work, Nideesh enjoys staying active by going to the gym, playing sports, and spending time outdoors.