Tag Archives: AWS

Monitoring AWS End User Messaging SMS Registrations with Lambda

Post Syndicated from Patrick Viker original https://aws.amazon.com/blogs/messaging-and-targeting/monitoring-aws-end-user-messaging-sms-registrations-with-lambda/

Managing AWS End User Messaging SMS registrations can be challenging, especially when dealing with multiple registrations in various states and countries. This post introduces an automated monitoring solution that helps you stay on top of your registration statuses. By leveraging AWS Lambda, EventBridge, and Simple Email Service (SES), you’ll create a system that provides regular updates about registrations that need attention, are under review, in draft pending submission, or have recently been completed.

Whether you’re managing Sender IDs, United States 10DLC campaigns, toll-free numbers, or short codes, this solution will help you maintain visibility across all your registrations and respond promptly to status changes. The setup takes approximately 15-20 minutes and requires no ongoing maintenance beyond occasional adjustments to meet your evolving needs.

Estimated Setup Time: 15-20 minutes

Prerequisites

  • An AWS account with access to Lambda, IAM, EventBridge, End User Messaging SMS, and SES
  • A verified email address in Amazon SES for sending reports.
Figure 1: AWS End User Messaging SMS registrations in the console. This view shows registrations in various states that our Lambda function will monitor.

Figure 1: AWS End User Messaging SMS registrations in the console. This view shows registrations in various states that our Lambda function will monitor.

Step 1: Set up Amazon SES

  1. Open the Amazon SES console
  2. Navigate to “Verified identities”
  3. If you have an identity verified you can skip this section
  4. If you do not already have an identity verified Click “Create identity”
  5. Review this post to learn how to verify an identity
    NOTE: Best practice is to verify a domain identity. This will authenticate your domain and improve deliverability. An email address identity, while more simple, will not be authenticated through DKIM which may decrease deliverability.

Reference: Creating and verifying identities in Amazon SES

Step 2: Create an IAM Role

  1. Open the IAM console
  2. Navigate to “Roles” and click “Create role”
  3. Select “AWS service” and “Lambda” as the use case
  4. Add only the following AWS managed policy: AWSLambdaBasicExecutionRole
  5. Name the role (e.g., “EndUserMessagingRegistrationsMonitorRole”) and click “Create role”
  6. After role creation, click on the newly created role
  7. Select “Add permissions” → “Create inline policy”
  8. Click on the “JSON” tab and paste the following policy: 
    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sms-voice:DescribeRegistrations",
                "sms-voice:DescribeRegistrationVersions"
            ],
            "Resource": "arn:aws:sms-voice:${region}:${account-id}:registration/*"
        },
        {
            "Effect": "Allow",
            "Action": "ses:SendRawEmail",
            "Resource": [
                "arn:aws:ses:${region}:${account-id}:identity/${domain}",
                "arn:aws:ses:${region}:${account-id}:configuration-set/*"
            ],
            "Condition": {
                "StringLike": {
                    "ses:FromAddress": [
                        "*@${domain}"
                    ]
                }
            }
        }
    ]
}
  9. Replace the placeholders in the policy:
    1. ${region}: Your AWS region (e.g., ‘us-west-2’)
    2. ${account-id}: Your AWS account ID
    3. ${domain}: Your verified SES domain
  10. Click “Next”
  11. Name the policy (e.g., “EndUserMessagingRegistrationsAccess”) and click “Create policy”

Reference: Creating a role for an AWS service (console)

Step 3: Create the Lambda Function

  1. Open the Lambda console
  2. Click “Create function”
  3. Choose “Author from scratch”
  4. Configure basic settings:
  5. Name: EndUserMessagingRegistrationsMonitor
  6. Runtime: Python 3.12
  7. Architecture: x86_64
  8. Permissions: Use the IAM role created in Step 2
  9. Click “Create function”
  10. Configure environment variables:
    1. Under “Configuration” tab → “Environment variables”
    2. Set the following key/value pairs:
      1. Key: SENDER_EMAIL, Value: [Your verified SES email]
      2. Key: RECIPIENT_EMAIL, Value: [Email to receive reports]
  11. Configure function timeout:
    1. Under “Configuration” → “General configuration”
    2. Set timeout to 1 minute
  12. In the function code area, paste the following code: 
    import boto3
import json
from datetime import datetime, timedelta
from collections import defaultdict
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
import os

# Constants
REGION = os.environ['AWS_REGION']
SENDER_EMAIL = os.environ['SENDER_EMAIL']
RECIPIENT_EMAIL = os.environ['RECIPIENT_EMAIL']
COMPLETED_LOOKBACK_DAYS = 7

# Initialize AWS clients
sms_client = boto3.client('pinpoint-sms-voice-v2', region_name=REGION)
ses_client = boto3.client('ses', region_name=REGION)

# Global registration dictionary
registrations = {
    'REQUIRES_UPDATES': defaultdict(list),
    'CREATED': defaultdict(list),
    'COMPLETED': defaultdict(list),
    'REVIEWING': defaultdict(list)
}

def get_console_url(registration_id):
    return f"https://{REGION}.console.aws.amazon.com/sms-voice/home?region={REGION}#/registrations?registration-id={registration_id}"

def get_version_details(registration_id, latest_denied_version=None):
    try:
        if latest_denied_version:
            response = sms_client.describe_registration_versions(
                RegistrationId=registration_id,
                VersionNumbers=[latest_denied_version]
            )
        else:
            response = sms_client.describe_registration_versions(
                RegistrationId=registration_id,
                MaxResults=1
            )
        
        if response['RegistrationVersions']:
            return response['RegistrationVersions'][0]
    except Exception as e:
        print(f"Error getting version details for {registration_id}: {str(e)}")
    return None

def is_recently_completed(version_info):
    if 'RegistrationVersionStatusHistory' in version_info:
        history = version_info['RegistrationVersionStatusHistory']
        if 'ApprovedTimestamp' in history:
            approved_time = history['ApprovedTimestamp']
            if isinstance(approved_time, datetime):
                approved_time = approved_time.timestamp()
            lookback_time = (datetime.now() - timedelta(days=COMPLETED_LOOKBACK_DAYS)).timestamp()
            return approved_time > lookback_time
    return False

def categorize_registration_type(registration_type):
    if 'TEN_DLC' in registration_type:
        return 'TEN_DLC'
    elif 'LONG_CODE' in registration_type:
        return 'LONG_CODE'
    elif 'SHORT_CODE' in registration_type:
        return 'SHORT_CODE'
    elif 'SENDER_ID' in registration_type:
        return 'SENDER_ID'
    elif 'TOLL_FREE' in registration_type:
        return 'TOLL_FREE'
    else:
        return 'OTHER'

def categorize_registrations():
    global registrations
    registrations = {
        'REQUIRES_UPDATES': defaultdict(list),
        'CREATED': defaultdict(list),
        'COMPLETED': defaultdict(list),
        'REVIEWING': defaultdict(list)
    }

    try:
        response = sms_client.describe_registrations()
        
        for registration in response.get('Registrations', []):
            status = registration['RegistrationStatus']
            registration_id = registration['RegistrationId']
            registration_type = registration['RegistrationType']
            category = categorize_registration_type(registration_type)
            
            reg_info = {
                'id': registration_id,
                'type': registration_type,
                'status': status,
                'version': registration['CurrentVersionNumber'],
                'console_url': get_console_url(registration_id)
            }

            if 'AdditionalAttributes' in registration:
                reg_info['additional_attributes'] = registration['AdditionalAttributes']

            if status == 'REQUIRES_UPDATES':
                latest_denied_version = registration.get('LatestDeniedVersionNumber')
                version_info = get_version_details(registration_id, latest_denied_version)
                if version_info and 'DeniedReasons' in version_info:
                    reg_info['denial_reasons'] = version_info['DeniedReasons']
                registrations['REQUIRES_UPDATES'][category].append(reg_info)
            
            elif status == 'CREATED':
                registrations['CREATED'][category].append(reg_info)
            
            elif status == 'REVIEWING':
                registrations['REVIEWING'][category].append(reg_info)
            
            elif status == 'COMPLETE':
                version_info = get_version_details(registration_id)
                if version_info and is_recently_completed(version_info):
                    approved_timestamp = version_info['RegistrationVersionStatusHistory']['ApprovedTimestamp']
                    if isinstance(approved_timestamp, datetime):
                        approved_timestamp = approved_timestamp.timestamp()
                    reg_info['approved_timestamp'] = approved_timestamp
                    registrations['COMPLETED'][category].append(reg_info)
                
    except Exception as e:
        print(f"Error listing registrations: {str(e)}")
        raise e

def generate_html_output():
    html = """
    <html>
    <head>
        <style>
            body { 
                font-family: Arial, sans-serif;
                margin: 20px;
                line-height: 1.6;
            }
            .registration-group { margin: 20px 0; }
            .registration-category { 
                background-color: #f0f0f0;
                padding: 10px;
                margin: 10px 0;
                border-radius: 5px;
            }
            .registration-item {
                border-left: 4px solid #ccc;
                margin: 10px 0;
                padding: 10px;
                background-color: #ffffff;
            }
            .requires-updates { border-left-color: #ff9900; }
            .created { border-left-color: #007bff; }
            .completed { border-left-color: #28a745; }
            .reviewing { border-left-color: #6c757d; }
            .denial-reasons {
                background-color: #fff3f3;
                padding: 10px;
                margin: 5px 0;
                border-radius: 3px;
            }
            .console-link {
                color: #007bff;
                text-decoration: none;
                padding: 2px 5px;
                border: 1px solid #007bff;
                border-radius: 3px;
            }
            .console-link:hover {
                background-color: #007bff;
                color: #ffffff;
            }
            .summary {
                margin: 20px 0;
                padding: 15px;
                background-color: #e9ecef;
                border-radius: 5px;
                box-shadow: 0 2px 4px rgba(0,0,0,0.1);
            }
            .divider {
                border-top: 2px solid #dee2e6;
                margin: 20px 0;
            }
            .lookback-info {
                background-color: #e2e3e5;
                padding: 10px;
                border-radius: 5px;
                margin: 10px 0;
                font-style: italic;
            }
            h2, h3, h4 {
                color: #333;
                margin-top: 20px;
            }
            ul {
                margin: 5px 0;
                padding-left: 20px;
            }
            li {
                margin: 5px 0;
            }
        </style>
    </head>
    <body>
    """

    html += f"<h2>Registration Status Report - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}</h2>"

    html += f"""
    <div class="lookback-info">
        Note: Completed registrations shown are those completed within the last {COMPLETED_LOOKBACK_DAYS} days.
    </div>
    """

    html += '<div class="summary"><h3>Summary</h3>'
    for status, categories in registrations.items():
        total = sum(len(regs) for regs in categories.values())
        html += f"<p><strong>{status}:</strong> {total}"
        if status == 'COMPLETED':
            html += f" (last {COMPLETED_LOOKBACK_DAYS} days)"
        html += "<br>"
        for category, regs in categories.items():
            if regs:
                html += f"&nbsp;&nbsp;{category}: {len(regs)}<br>"
        html += "</p>"
    grand_total = sum(sum(len(regs) for regs in categories.values()) for categories in registrations.values())
    html += f"<p><strong>Total Registrations:</strong> {grand_total}</p>"
    html += "</div>"

    html += '<div class="divider"></div>'

    html += "<h3>Detailed Registration Status</h3>"

    for status, categories in registrations.items():
        total = sum(len(regs) for regs in categories.values())
        html += f"""
        <div class="registration-group">
            <h3>{status} Registrations (Total: {total})</h3>
        """

        for category, regs in categories.items():
            if regs:
                html += f"""
                <div class="registration-category">
                    <h4>{category} Registrations ({len(regs)})</h4>
                """

                for reg in regs:
                    css_class = status.lower().replace('_', '-')
                    html += f"""
                    <div class="registration-item {css_class}">
                        <strong>Registration ID:</strong> {reg['id']}<br>
                        <strong>Type:</strong> {reg['type']}<br>
                        <strong>Status:</strong> {reg['status']}<br>
                        <strong>Version:</strong> {reg['version']}<br>
                        <strong>Console:</strong> <a href="{reg['console_url']}" class="console-link" target="_blank">Open in Console</a><br>
                    """

                    if (reg['type'] == 'US_TEN_DLC_BRAND_VETTING' and 
                        status == 'COMPLETED' and 
                        'additional_attributes' in reg and 
                        'VETTING_SCORE' in reg['additional_attributes']):
                        html += f"<strong>Vetting Score:</strong> {reg['additional_attributes']['VETTING_SCORE']}<br>"

                    if status == 'REQUIRES_UPDATES' and reg.get('denial_reasons'):
                        html += '<div class="denial-reasons"><strong>Denial Reasons:</strong><ul>'
                        for reason in reg['denial_reasons']:
                            html += f"""
                            <li>
                                <strong>{reason.get('Reason', 'N/A')}</strong><br>
                                {reason.get('ShortDescription', 'N/A')}<br>
                            """
                            if reason.get('LongDescription'):
                                html += f"{reason['LongDescription']}<br>"
                            if reason.get('DocumentationLink'):
                                html += f'<a href="{reason["DocumentationLink"]}" target="_blank">Documentation</a>'
                            html += "</li>"
                        html += "</ul></div>"

                    if status == 'COMPLETED':
                        approved_time = datetime.fromtimestamp(reg['approved_timestamp']).strftime('%Y-%m-%d %H:%M:%S')
                        html += f"<strong>Approved:</strong> {approved_time}<br>"

                    html += "</div>"
                html += "</div>"
        html += "</div>"

    html += "</body></html>"
    return html

def send_email(html_content, subject, recipient):
    msg = MIMEMultipart('mixed')
    msg['Subject'] = subject
    msg['From'] = SENDER_EMAIL
    msg['To'] = recipient

    html_part = MIMEText(html_content, 'html')
    msg.attach(html_part)

    try:
        response = ses_client.send_raw_email(
            Source=msg['From'],
            Destinations=[recipient],
            RawMessage={'Data': msg.as_string()}
        )
        print(f"Email sent! Message ID: {response['MessageId']}")
    except Exception as e:
        print(f"Error sending email: {str(e)}")
        raise e

def lambda_handler(event, context):
    try:
        print("Starting registration categorization...")
        categorize_registrations()
        
        print("Generating HTML report...")
        html_content = generate_html_output()
        
        print("Sending email...")
        subject = f"End User Messaging SMS Registration Status Report - {datetime.now().strftime('%Y-%m-%d %H:%M')}"
        send_email(html_content, subject, RECIPIENT_EMAIL)
        
        return {'statusCode': 200, 'body': json.dumps('Registration status report generated and sent successfully')}
    except Exception as e:
        print(f"Error in lambda execution: {str(e)}")
        return {'statusCode': 500, 'body': json.dumps(f'Error generating report: {str(e)}')}

Reference: Building Lambda functions with Python

Step 4: Set Up EventBridge Rule

  1. Open the Amazon EventBridge console
  2. Click “Create rule”
  3. Name your rule (e.g., “EndUserMessagingRegistrationsMonitorSchedule”)
  4. For the event pattern, choose “Schedule” then select “Continue in EventBridge Scheduler”
  5. Configure your schedule pattern to your requirements (for example, Cron-based schedule to run at specific days and times or rate-based schedule such as every 1 day). Click “Next”.
  6. Select “Lambda” for “Target detail” and select the Lambda function created in Step 3 as the target from the dropdown. Click “Next”.
  7. For permissions:
    1. Select “Create new role for this schedule”
    2. EventBridge will automatically create a role with the necessary permissions to invoke your Lambda function
  8. Click “Next” to review your configuration
  9. Click “Create schedule”

Reference: Amazon EventBridge Scheduler

Step 5: Test the Setup

  1. Open the Lambda console and navigate to your function
  2. Click “Test” and create a test event (you can use an empty JSON object {})
  3. Run the test and check the execution results
  4. Verify that you receive an email report

Reference: Testing Lambda functions in the console

The generated email report provides a clear summary of all registrations, categorized by their status.

Figure 2: The generated email report provides a clear summary of all registrations, categorized by their status.

Understanding the Lambda Function

Let’s break down the key components of our Lambda function:

  1. Initialization: The script sets up necessary AWS clients and defines constants.
  2. categorize_registrations(): This function fetches all registrations and categorizes them based on their status and type.
  3. generate_html_output(): Creates a formatted HTML report of the registration statuses.
  4. send_email(): Uses Amazon SES to send the HTML report via email.
  5. lambda_handler(): The main entry point for the Lambda function, orchestrating the entire process.

The function categorizes registrations into four main statuses:

  • REQUIRES_UPDATES: Registrations that need attention or modifications
  • CREATED: Newly created registrations
  • REVIEWING: Registrations currently under review
  • COMPLETED: Registrations that have been approved recently (within the last 7 days by default)
Detailed view of a registration requiring updates and created registrations pending submission, including specific denial reasons if applicable and direct console links.

Figure 3: Detailed view of a registration requiring updates and created registrations pending submission, including specific denial reasons if applicable and direct console links.

Customization Options

  1. Lookback Period: Modify the COMPLETED_LOOKBACK_DAYS constant to change how far back the function checks for completed registrations.
  2. Email Formatting: Adjust the HTML and CSS in generate_html_output() to customize the email report’s appearance.
  3. Additional Data: Modify the reg_info dictionary in categorize_registrations() to include more data fields in your report.

Monitoring and Maintenance

  1. CloudWatch Logs: Regularly check the Lambda function’s CloudWatch Logs for any errors or unexpected behavior.
  2. Adjusting Schedule: If you find the current schedule doesn’t meet your needs, adjust the EventBridge rule accordingly.

Conclusion

You now have an automated system that monitors your End User Messaging SMS registrations and sends you regular, detailed status reports. This setup provides:

  • Automated visibility into registrations requiring updates or attention
  • Clear tracking of draft registrations awaiting your submission
  • Monitoring of registrations under review
  • Notifications of recently completed registrations
  • A consolidated view of all registration states through formatted email reports

This automated solution eliminates the need for manual status checking and helps ensure timely responses to registration changes. As your messaging needs grow, you can easily customize the monitoring frequency, lookback period, and report format to match your requirements.

Next Steps:

  • Consider adjusting the EventBridge schedule based on your registration volume
  • Customize the email format to highlight information most relevant to your team
  • Set up CloudWatch alarms to monitor the Lambda function’s health
  • Review and update the completed registrations lookback period as needed

For more complex scenarios, consider extending this solution with additional features like Slack notifications, registration metrics tracking, or integration with your ticketing system.

 

Navigating AWS Migration: Achieving Clarity and Confidence

Post Syndicated from Tim Schmidt original https://blog.rapid7.com/2025/06/09/navigating-aws-migration-achieving-clarity-and-confidence-2/

Navigating AWS Migration: Achieving Clarity and Confidence

Migrating workloads to Amazon Web Services (AWS) represents a significant strategic opportunity, enabling greater agility, scalability, and potential for innovation. But undertaking this transition without a comprehensive strategy for visibility and security can introduce unforeseen risks, operational delays, and challenges in managing the new cloud environment effectively. A critical aspect often overlooked is the discovery and protection of sensitive data as it moves to and resides within the cloud, demanding specific attention.

Addressing security proactively is not merely a technical requirement: it functions as a crucial enabler, allowing organizations to fully realize the strategic benefits of the cloud without being hindered by security roadblocks or compliance failures.

Furthermore, bringing sensitive data protection into focus early connects the technical migration process directly to significant business risks, such as regulatory non-compliance and the potential impact of data breaches, underscoring the importance of robust security solutions for confidently realizing cloud benefits.

Integrating security across the migration lifecycle

A successful and secure migration is not achieved by treating security as an afterthought. Security considerations must be integrated throughout the entire migration lifecycle – from the initial assessment of the current environment, through mobilizing resources and establishing the cloud foundation, to the final migration and modernization phases.

Cloud migration typically involves distinct stages:

  1. Assess: Evaluating the current state, identifying assets, and understanding existing risks.
  2. Mobilize: Preparing resources and establishing a secure cloud foundation or landing zone in AWS.
  3. Migrate and modernize: Transferring workloads and potentially optimizing them for the cloud environment.

Addressing security continuously across these stages helps prevent costly delays and rework often associated with late-stage security implementations. Effective tooling and methodology are essential here.

Rapid7’s security platform is designed to support organizations through this journey, providing the necessary visibility, risk context, and security controls for a smoother transition to AWS. The platform unifies critical capabilities, aiming to provide a 360° view of the attack surface and streamlining security operations across hybrid environments.

Improving migration efficiency through unified security

Efficiency is paramount across migration phases to maintain project velocity without compromising security. Managing multiple disparate tools can impede progress and obscure visibility. Rapid7 helps streamline critical activities by unifying essential capabilities within its Command Platform:

  • Asset Discovery: Identify every vulnerable device and weak identity across your environment with comprehensive attack surface management.
  • Risk-based prioritization: Incorporate business context, third-party vulnerability findings, and threat intelligence into how you assess risk to improve your cloud security posture and protect cloud workloads.
  • Proactive remediation:Customize remediation workflows to seamlessly orchestrate and automatically respond to any vulnerability.

This integrated approach offers advantages beyond simplified tool management, potentially leading to richer context through data correlation and more effective prioritization.

During assessment

Comprehensive planning requires a complete asset inventory. Surface Command accelerates the initial assessment phase through rapid, comprehensive asset discovery across internal and external inventories, including cloud environments like AWS. This helps to eliminate blind spots and identify all assets, including potentially unsecured systems, before they are considered for migration.

Subsequently, Exposure Command builds upon this asset foundation, adding vulnerability data and risk scoring to identify critical weaknesses in on-premises systems slated for migration. It enables teams to focus remediation efforts effectively by prioritizing vulnerabilities based on threat-aware risk context before these systems move to the cloud.

During mobilize and migrate and modernize

In these intensive phases, Exposure Command ensures the AWS landing zone and core services are configured securely according to organizational policies and industry best practices (e.g., CIS Benchmarks) through its Cloud-Native Application Protection Platform  (CNAPP) capabilities, while providing ongoing monitoring for misconfigurations. It also plays a critical role in managing cloud permissions by analyzing identities and access rights to help enforce least-privilege access models.

As workloads are deployed, it offers  vulnerability management tailored for cloud assets, including container security. Concurrently, InsightConnect reduces the manual workload associated with security tasks. As a SOAR solution, it utilizes numerous plugins to automate repetitive processes like configuration validation, vulnerability enrichment, or initiating remediation workflows. This automation frees up valuable security and IT resources, helping maintain project velocity.

Enhancing risk management: Before, during, and after migration

Migrating to the cloud should not involve transferring existing on-premises security risks or inadvertently creating new ones in the AWS environment. Proactive risk management, integrated throughout the migration lifecycle, is essential.

  • Before migration: Surface Command’s ability to discover known and unknown assets provides a foundational inventory, helping prevent the migration of forgotten or unsecured systems. Concurrently, Exposure Command’s vulnerability management capabilities allow organizations to identify and address critical weaknesses in on-premises systems targeted for migration, leveraging threat-aware risk scoring to prioritize remediation efforts before these systems enter the cloud.
  • During migration (mobilize and migrate phases): As the AWS environment is established and workloads deployed, Exposure Command ensures secure configuration and detects drift. Its capabilities aid in managing cloud permissions and enforcing least privilege. Critically, Exposure Command integrates sensitive data discovery capabilities, leveraging technologies like InsightCloudSec or ingesting findings from services such as Amazon Macie. This provides visibility into the location of sensitive data within AWS. This data-centric context is incorporated into Exposure Command’s risk analysis, including attack path analysis, allowing teams to prioritize threats based on the potential business impact of compromised sensitive information.
  • During and after migration (modernization and ongoing operations): In modern cloud environments utilizing CI/CD pipelines, Exposure Command supports a proactive DevSecOps approach. By integrating security checks directly into the development lifecycle—scanning container images and validating Infrastructure-as-Code (IaC) templates—organizations can identify and fix security flaws before deployment to AWS. This “shift-left” strategy, facilitated by integrations with CI/CD platforms, significantly reduces the risk of introducing vulnerabilities into the production AWS environment and embeds security into cloud operations.

Building confidence through visibility, control, and automation

Achieving efficiency and robust risk management culminates in greater organizational confidence throughout the migration process and into ongoing cloud operations. Access to accurate, comprehensive data on assets and their associated vulnerabilities and risks allows for more informed, data-driven migration planning.

This comprehensive approach enables organizations to:

  • Move beyond simple lift-and-shift approaches, using security posture data to strategically decide which workloads to migrate, identify necessary pre-migration remediation, and design secure target architectures in AWS.
  • Validate the security posture of the foundational AWS environment with Exposure Command providing assurance before large-scale workload migration commences.
  • Benefit from consolidated visibility and reporting through dashboards and features like Executive Risk View, offering stakeholders clear insights into the security status and risk landscape. This capability translates technical findings into business-relevant risk information to foster broader confidence.
  • Leverage integrated detection and automatic response capabilities post-migration to ensure the security team can manage potential threats effectively in the new AWS environment.

This level of comprehensive visibility and control replaces uncertainty with operational readiness.

Achieving a secure and confident AWS transition

The transition to AWS offers substantial benefits in terms of agility, scalability, and innovation. However, realizing these benefits securely requires navigating the inherent complexities of migration and cloud operations.

Rapid7’s integrated solutions – Surface Command for foundational visibility and Exposure Command for comprehensive risk management across vulnerabilities, cloud  workloads, sensitive data, and CI/CD pipelines)provide the unified capabilities needed to manage the cloud journey efficiently and securely.

By delivering clarity and control across the entire migration lifecycle and into ongoing operations, the platform helps organizations manage the complexity of cloud security, enabling them to migrate to and operate within AWS with confidence.

Gain complete visibility for your AWS migration. Start your Surface Command free trial today.

Use AI agents and the Model Context Protocol with Amazon SES

Post Syndicated from Zip Zieper original https://aws.amazon.com/blogs/messaging-and-targeting/use-ai-agents-and-the-model-context-protocol-with-amazon-ses/

Amazon Simple Email Service (Amazon SES) delivers a cloud-based email solution that empowers businesses to send emails more efficiently and at a larger scale. Its powerful, scalable platform enables organizations from startups to global brands to send personalized, high-volume email communications while maintaining exceptional deliverability and performance.

Amazon SES caters to a wide range of users, from developers and technical marketing professionals to business communicators. In addition to offering robust programmatic access through APIs and SMTP protocols, Amazon SES provides a comprehensive web console and intuitive dashboards that make email configuration and performance monitoring accessible to users with varying technical backgrounds. Historically, navigating email workflows and configuring advanced email capabilities in Amazon SES has required specialized knowledge, resulting in a learning curve for new users. As seen in many other areas, today’s AI tools can offer more intuitive ways to manage Amazon SES to get the most out of your email communications. We have found, however, that these AI tools occasionally produce inconsistent results, often as a result of the underlying large language model’s (LLM’s) training data.

Recognizing the need for a specialized, service-aware, AI-friendly Amazon SES solution, we are introducing the SESv2 MCP Server, a sample Model Context Protocol (MCP) for Amazon SES. We’ve integrated the SESv2 MCP Server sample with the Amazon SES v2 APIs to provide more precise and reliable AI-assisted use, management, and configuration for Amazon SES.

MCP is an open protocol that enables seamless integration between your AI-powered integrated development environment (IDE) or AI assistant, enriching the capabilities of the AI and enabling you to use Amazon SES using natural language. For more info, see the GitHub repo.

We’ve released the SESv2 MCP Server sample on GitHub and invite current and prospective customers to experiment with it in non-production environments. You can use it with your AI tools to explore ways in which AI can be used with Amazon SES to send emails, check configurations, and review deliverability. We’re interested in learning how you use your AI tools and the SESv2 MCP Server to test out email sending in different services or applications. We’re also curious if new customers find it helpful when configuring and learning about their Amazon SES service. No matter how you use it, we are eager for your feedback, comments, and contributions through the GitHub project’s issues.

Solution overview

You can use the SESv2 MCP Server sample with AI assistant applications like Anthropic’s Claude Desktop. You can also integrate it into MCP-compatible agentic AI coding assistants such as Amazon Q Developer, Amazon Q for command line, Cline, Cursor, and Windsurf. When used as an AI coding assistant, the SESv2 MCP Server sample helps developers add Amazon SES email capabilities to their applications and services using plain, natural language prompting. For recommendations from AWS on how to improve your vibe coding experience, refer to Vibe coding tips and tricks.

After you’ve configured the sample and authenticated with your AWS credentials, you can use natural language in your chosen AI tool. For example, an email marketing manager might want to ask Anthropic’s Claude Desktop “provide me with the status of the verified identities in my SES account, along with any recommendations to improve deliverability.” Someone new to Amazon SES can ask the Amazon Q CLI “create a new Amazon SES configuration set for the octank.com identity, enable it for event publishing for bounces and complaints.” Similarly, the developer of an AI-enabled restaurant booking application might ask the Amazon Q CLI “my application needs to send email confirmation of a customers online booking. Can you walk me thru adding this capability to my app using my SES account?”

As you can see from these examples, although it’s helpful to know a bit about email, and Amazon SES in general, with the help of your AI tool and the SESv2 MCP Server sample, you don’t need to be an email or Amazon SES expert. The combination of your creativity, AI tool, and the SESv2 MCP Server sample empowers even non-developers to create, test, and monitor Amazon SES workflows using natural language.

The SESv2 MCP Server sample release uses the open source Smithy Java project, which is still in development. As such, the SESv2 MCP Server is considered a sample, and we do not recommend employing it for production use. When a stable version is available, we might update this post and the GitHub repository accordingly.

Prerequisites

To follow along with the example use cases, make sure you have the following prerequisites set up:

  • AWS credentials with appropriate permissions.
  • An MCP-compatible LLM client (such as Anthropic’s Claude Desktop, Cline, Amazon Q CLI, or Cursor). For this post, we use the Amazon Q Developer CLI. For installation instructions, refer to Installing Amazon Q for command line.
  • Java 21 (or later) runtime (as required by Smithy Java).
  • Access to GitHub.
  • Git installed locally. For instructions, see Getting Started – Installing Git.

Best practices for using MCPs

To maximize the benefits of MCP-assisted development while maintaining security and code quality, we suggest you follow these essential guidelines:

  • Always review generated code for security implications before deployment
  • Use MCP servers as accelerators, not replacements for developer judgment and expertise
  • Keep MCP servers updated with the latest AWS security best practices
  • Follow the principle of least privilege when configuring AWS credentials
  • Run security scanning tools on generated infrastructure code

Configure the AWS CLI

Use the following command to configure the AWS Command Line Interface (AWS CLI) with the AWS credentials for your Amazon SES account and AWS Region:

aws configure

Clone and build the GitHub repository locally

To use macOS or Linux, use the following command to clone and build the GitHub repo:

git clone https://github.com/aws-samples/sample-for-amazon-ses-mcp.git
cd sample-for-amazon-ses-mcp
./build.sh

For Windows, use the following command:

git clone https://github.com/aws-samples/sample-for-amazon-ses-mcp.git
cd sample-for-amazon-ses-mcp
.\build.bat

Copy the absolute path to the .jar file (JAR_PATH_FROM_BUILD_OUTPUT). This will be printed at the end of the build script:

/<your path>/sample-for-amazon-ses-mcp/artifacts/sample-for-amazon-ses-mcp-all.jar

Configure your AI tool to use SESv2 MCP Server

When the build is complete, add SESv2 MCP Server to your AI tool’s MCP configuration:

{
  "mcpServers": {
    "sesv2-mcp-server": {
      "command": "java",
      "args": [
        "-jar",
        "JAR_PATH_FROM_BUILD_OUTPUT"
      ]
    }
  }
}

See MCP configuration for configuration steps. See the Claude Desktop MCP configuration guide for setup instructions.

After you build the SESv2 MCP Server and configure your AWS credentials, you’re ready to interact with Amazon SES. Keep in mind that effective, thoughtful prompting is crucial for successful AI-assisted development. For more information about vibe coding, see Vibe coding tips and tricks.

Example use cases

In this section, we provide some guided examples using the Amazon Q Developer CLI to interact with Amazon SES. Feel free to experiment on your own use cases, and share your comments and ideas through the GitHub project’s issues. Do not disclose any personal, commercially sensitive, or confidential information.

Get information, recommendations, and configurations your Amazon SES account

Open your AI tool; for these examples, we use a macOS terminal and initiate a chat session with the Amazon Q CLI:

q chat

We’ve found it useful to provide your AI tool with some guidance:

You're connected to the SESv2 MCP Server and have access to the AWS SESv2 APIs.

Ask the Amazon Q CLI about your AWS account’s SES email identities:

Tell me about the identities in my account, and also if the account is in the SES sandbox?

The Amazon Q CLI will request permission to use the SESv2 MCP Server (which provides the Amazon Q CLI with the SESv2 APIs ListEmailIdentities and GetAccount) to query your AWS SES account and reply with a detailed summary.

Ask the Amazon Q CLI if it has any recommendations related to improving deliverability for your Amazon SES account:

Do you have any recommendations to improve email deliverability for my SES account?

The Amazon Q CLI will use the SESv2 MCP Server (which provides the CLI with the SESv2 API ListRecommendations) to query your Amazon SES account and reply with a detailed summary.

Ask the Amazon Q CLI to set up Amazon SES click tracking for one of your domains. We have found it helpful to remind the CLI that it has access to additional knowledge of the AWS service APIs. It’s also a good idea to make sure the AI tool doesn’t invent nonexistent APIs.

You also have access to other AWS service APIs via the AWS CLI and your general knowledge, but you may only use known, documented APIs - do not invent or create any APIs or commands.
Set up Amazon SES click tracking with CloudWatch integration for the domain <my verified identity> to monitor email metrics. Use Amazon's default tracking domain (no SSL or https) for the click tracking to ensure immediate functionality without requiring custom domain setup. Include all necessary configuration steps and verify the setup works correctly. Create a test HTML email to <my email address> from <no-reply@verified domain> with subject "Testing SES click tracking". Create an HTML (with fallback to text) body with links and short descriptions taken from the public AWS webpages for Amazon SES, AWS End User Messaging and Amazon Connect. 

Send emails with your Amazon SES account

Using its knowledge of Amazon SES from the SESv2 MCP Server and permissions to use your Amazon SES account (aws configure), you can use your AI tool to create and send emails using Amazon SES.

If your Amazon SES account is in the Amazon SES sandbox, you are limited to sending and receiving email from verified email addresses. You are also limited to 200 messages in 24 hours. For more information about the Amazon SES sandbox, see Request production access (Moving out of the Amazon SES sandbox). If you’re in the sandbox, you can simply ask your AI tool “verify my email address <[email protected]>.”

Ask the Amazon Q CLI to send a test email with a sample HTML body:

Send a test email to <my verified email address> from <verified SES email identity>. Set the from email display name to "MCP testing". Make the email subject "Test sending an email via SES MCP". Use the information found on the Amazon SES website to create an HTML message body with a few sentences and bullet points about SES. Provide a text version of the message body in case of fallback.

Check your email, where you will receive a response.

You can get creative and ask the Amazon Q CLI to create a formatted email template with personalization using a simple table with email recipients, the product they bought, and their postal code:

Use the table below to send each person in the table an html formatted (with fallback) email message. 
-- table --
email,name,product,zipcode
<my verified email address>,Alice,an umbrella,98101
<my verified email address>,Bob,lots of sunscreen,10001
-- end table --
Use the template below. Create a 5-day weather forecast graphic similar to popular weather app graphics based on estimated weather for their ZIP code.
-- template --
"Hi {{name}}, thanks for buying {{product}}; it looks like you'll need it soon based on the 5-day weather forecast for your local area: <5-day weather forecast graphic>.

As we’ve demonstrated, you don’t need to be a seasoned developer to create and test Amazon SES workflows when you have an AI tool and the SESv2 MCP Server sample.

Conclusion

The SESv2 MCP Server sample democratizes the ability to configure, manage, and create sophisticated email automation workflows with Amazon SES.

The examples and guidance in this post demonstrate how even newcomers can use AI tools like the Amazon Q CLI to test out configuring, monitoring, and sending emails with Amazon SES using natural language. More technical users, including developers, can use the SESv2 MCP Server sample to build and test intelligent email applications that use Amazon SES, or to test out building Amazon SES sending into their own application.

We hope you will experiment with the SESv2 MCP Server sample and provide us with your thoughts and feedback, and perhaps contribute to the project through the GitHub project’s issues.

Additional resources

Navigating AWS Migration: Achieving Clarity and Confidence

Post Syndicated from Jack Clavette original https://blog.rapid7.com/2025/06/05/navigating-aws-migration-achieving-clarity-and-confidence/

Navigating AWS Migration: Achieving Clarity and Confidence

Migrating workloads to Amazon Web Services (AWS) represents a significant strategic opportunity, enabling greater agility, scalability, and potential for innovation. But undertaking this transition without a comprehensive strategy for visibility and security can introduce unforeseen risks, operational delays, and challenges in managing the new cloud environment effectively. A critical aspect often overlooked is the discovery and protection of sensitive data as it moves to and resides within the cloud, demanding specific attention.

Addressing security proactively is not merely a technical requirement: it functions as a crucial enabler, allowing organizations to fully realize the strategic benefits of the cloud without being hindered by security roadblocks or compliance failures.

Furthermore, bringing sensitive data protection into focus early connects the technical migration process directly to significant business risks, such as regulatory non-compliance and the potential impact of data breaches, underscoring the importance of robust security solutions for confidently realizing cloud benefits.

Integrating security across the migration lifecycle

A successful and secure migration is not achieved by treating security as an afterthought. Security considerations must be integrated throughout the entire migration lifecycle – from the initial assessment of the current environment, through mobilizing resources and establishing the cloud foundation, to the final migration and modernization phases.

Cloud migration typically involves distinct stages:

  1. Assess: Evaluating the current state, identifying assets, and understanding existing risks.
  2. Mobilize: Preparing resources and establishing a secure cloud foundation or landing zone in AWS.
  3. Migrate and modernize: Transferring workloads and potentially optimizing them for the cloud environment.

Addressing security continuously across these stages helps prevent costly delays and rework often associated with late-stage security implementations. Effective tooling and methodology are essential here.

Rapid7’s security platform is designed to support organizations through this journey, providing the necessary visibility, risk context, and security controls for a smoother transition to AWS. The platform unifies critical capabilities, aiming to provide a 360° view of the attack surface and streamlining security operations across hybrid environments.

Improving migration efficiency through unified security

Efficiency is paramount across migration phases to maintain project velocity without compromising security. Managing multiple disparate tools can impede progress and obscure visibility. Rapid7 helps streamline critical activities by unifying essential capabilities within its Command Platform:

  • Surface Command: Provides comprehensive asset discovery and attack surface management.
  • Exposure Command: Delivers vulnerability risk management, cloud security posture management, and workload protection.
  • Insight Connect: Enables security orchestration, automation, and response (SOAR).

This integrated approach offers advantages beyond simplified tool management, potentially leading to richer context through data correlation and more effective prioritization.

During assessment

Comprehensive planning requires a complete asset inventory. Surface Command accelerates the initial assessment phase through rapid, comprehensive asset discovery across internal and external inventories, including cloud environments like AWS. This helps to eliminate blind spots and identify all assets, including potentially unsecured systems, before they are considered for migration.

Subsequently, Exposure Command builds upon this asset foundation, adding vulnerability data (often leveraging capabilities from solutions like InsightVM) and risk scoring to identify critical weaknesses in on-premises systems slated for migration. It enables teams to focus remediation efforts effectively by prioritizing vulnerabilities based on threat-aware risk context before these systems move to the cloud.

During mobilize and migrate and modernize:

In these intensive phases, Exposure Command ensures the AWS landing zone and core services are configured securely according to organizational policies and industry best practices (e.g., CIS Benchmarks) through its Cloud Security Posture Management (CSPM) capabilities, while providing ongoing monitoring for misconfigurations. It also plays a critical role in managing cloud permissions by analyzing identities and access rights to help enforce least-privilege access models.

As workloads are deployed, it offers Cloud Workload Protection (CWP) and vulnerability management tailored for cloud assets, including container security. Concurrently, Insight Connect reduces the manual workload associated with security tasks. As a SOAR solution, it utilizes numerous plugins to automate repetitive processes like configuration validation, vulnerability enrichment, or initiating remediation workflows. This automation frees up valuable security and IT resources, helping maintain project velocity.

Enhancing risk management: Before, during, and after migration

Migrating to the cloud should not involve transferring existing on-premises security risks or inadvertently creating new ones in the AWS environment. Proactive risk management, integrated throughout the migration lifecycle, is essential.

  • Before migration: Surface Command’s ability to discover known and unknown assets provides a foundational inventory, helping prevent the migration of forgotten or unsecured systems. Concurrently, Exposure Command’s vulnerability management capabilities allow organizations to identify and address critical weaknesses in on-premises systems targeted for migration, leveraging threat-aware risk scoring to prioritize remediation efforts before these systems enter the cloud.
  • During migration (mobilize and migrate phases): As the AWS environment is established and workloads deployed, Exposure Command’s CSPM functions ensure secure configuration and detect drift. Its capabilities aid in managing cloud permissions and enforcing least privilege. Critically, Exposure Command integrates sensitive data discovery capabilities, leveraging technologies like InsightCloudSec or ingesting findings from services such as Amazon Macie. This provides visibility into the location of sensitive data within AWS. This data-centric context is incorporated into Exposure Command’s risk analysis, including attack path analysis, allowing teams to prioritize threats based on the potential business impact of compromised sensitive information.
  • During and after migration (modernization and ongoing operations): In modern cloud environments utilizing CI/CD pipelines, Exposure Command supports a proactive DevSecOps approach. By integrating security checks directly into the development lifecycle—scanning container images and validating Infrastructure-as-Code (IaC) templates—organizations can identify and fix security flaws before deployment to AWS. This “shift-left” strategy, facilitated by integrations with CI/CD platforms, significantly reduces the risk of introducing vulnerabilities into the production AWS environment and embeds security into cloud operations.

Building confidence through visibility and control

Achieving efficiency and robust risk management culminates in greater organizational confidence throughout the migration process and into ongoing cloud operations. Access to accurate, comprehensive data on assets (via Surface Command) and their associated vulnerabilities and risks (via Exposure Command) allows for more informed, data-driven migration planning.

This comprehensive approach enables organizations to:

  • Move beyond simple lift-and-shift approaches, using security posture data to strategically decide which workloads to migrate, identify necessary pre-migration remediation, and design secure target architectures in AWS.
  • Validate the security posture of the foundational AWS environment with Exposure Command’s CSPM capabilities, providing assurance before large-scale workload migration commences.
  • Benefit from consolidated visibility and reporting through dashboards and features like the Executive Risk View, offering stakeholders clear insights into the security status and risk landscape. This capability translates technical findings into business-relevant risk information, fostering broader confidence.
  • Leverage integrated detection and response capabilities post-migration, often orchestrated through Insight Connect, ensuring the security team is equipped to manage potential threats effectively in the new AWS environment

This comprehensive visibility and control replace uncertainty with operational readiness.

Achieving a secure and confident AWS transition

The transition to AWS offers substantial benefits in terms of agility, scalability, and innovation. However, realizing these benefits securely requires navigating the inherent complexities of migration and cloud operations.

Rapid7’s integrated solutions – Surface Command for foundational visibility, Exposure Command for comprehensive risk management (including vulnerability management, cloud security posture, workload protection, sensitive data context, and DevSecOps integration), and Insight Connect for automation and response – provide the unified capabilities needed to manage this journey efficiently and securely.

By delivering clarity and control across the entire migration lifecycle and into ongoing operations, the platform helps organizations manage the complexity of cloud security, enabling them to migrate to and operate within AWS with confidence.

Gain complete visibility for your AWS migration. Start your Surface Command free trial today.

AWS End User Messaging SMS & Voice v2 API: A Migration Guide from v1

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).
  • 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.

Navigate Bulk Sender Requirements with Amazon SES

Post Syndicated from Vinay Ujjini original https://aws.amazon.com/blogs/messaging-and-targeting/navigate-bulk-sender-requirements-with-amazon-ses/

Introduction

Email communication remains a critical component of business operations and customer engagement. As the digital landscape evolves, major mailbox providers continually update their policies to enhance security and user experience. This blog will explore the changes implemented by Microsoft for bulk senders trying to reach Outlook.com (supporting Hotmail.com, live.com consumer domain addresses). This follows the Google & Yahoo! bulk sender requirements changes in February of 2024. Microsoft is implementing the enforcement of sender requirements for bulk email senders, particularly those sending over 5,000 messages daily, starting May 5, 2025. These requirements focus on improving email authentication and trust. This will ensure Outlook and Hotmail recipients are receiving messages that are authenticated and from who they claim to be from. These measures will help reduce spoofing, phishing, and spam, and safeguarding individuals and businesses relying on email.

This blog will discuss what these changes mean for you, and how Amazon Simple Email Service (Amazon SES) can help you maintain compliance and optimize your email sending practices.

Background

In February 2024, Google and Yahoo implemented new requirements for bulk email senders, building upon industry efforts to combat spam and improve email deliverability. These changes aligned with Google’s 2024 bulk sender requirements initiative, signaling a unified approach among major mailbox providers to enhance the privacy and compliance in email.

What does this mean for customers and email senders?

What’s Changing?

Microsoft’s New Requirements

  1. DMARC enforcement with at least a p=none policy
  2. Sender domain authentication (SPF, DKIM)
  3. Functional unsubscribe links required in the email
  4. Requirement for From and Reply-to addresses to be deliverable

Why These Changes Matter?

These new requirements serve several crucial purposes:

  1. Enhances trust in your sending domain: Validates that the sender is who they are claiming to be. Enhances trust by delivering messages that are authenticated and aligned with the bulk sender requirements.
  2. Improved Deliverability: Ensuring legitimate emails reach the recipients who have subscribed to sender’s messages.
  3. User-Centric: Providing recipients with control over their inboxes.
  4. Industry Standardization: Aligning sender requirements across major email providers

Best Practices for Compliance

To adhere to these new requirements and optimize your email sending practices, consider the following best practices:

1. Implement Strong Authentication

  • Configure SPF: SPF (Sender Policy Framework) is an email authentication standard that’s designed to prevent email spoofing. Domain owners use SPF to tell email providers which servers are allowed to send email from their domains. Follow setup instructions to authenticate your email with SPF. Must pass SPF for sending domain.
    • Configure “custom MAIL FROM“, which is how senders can ensure that the SPF-authenticated domain is aligned with the From header domain’s DMARC policy.
  • Enable DKIM signing: DomainKeys Identified Mail (DKIM) is an email security standard. It is designed to ensure that an email that claims to have come from a specific domain, was indeed authorized by the owner of that domain. It uses public-key cryptography to sign an email with a private key. Recipient servers use a public key, published to a domain’s DNS to verify that parts of the email have not been modified during the transit. Follow these set up instructions to authenticate email with DKIM in SES. Must pass to validate email integrity and authenticity.
    • Verify your domain with Easy DKIM. If currently using email identities, you have to move to domain
    • If you utilize email identities only, you will default all authentication to amazonses.com. That will not align with your friendly from address which will not satisfy the bulk sender requirements. This means that when you send email to mailbox providers, your messages will be rejected because you do not have proper authentication on your emails. To satisfy the bulk sender requirements, you must use domain verified identities which ensure that you have ownership of or permission to use the sending domain. That will allow SES to sign the outgoing emails with a DKIM signature that aligns with the friendly from domain.
  • Set up DMARC with an appropriate policy: Domain-based Message Authentication, Reporting and Conformance (DMARC) is an email authentication protocol that uses SPF and DKIM to detect email spoofing and phishing. To comply with DMARC, messages must be authenticated through either SPF or DKIM. Ideally, when both are used with DMARC, you’ll be ensuring the highest level of protection possible for your email sending.
Name Type Value
_dmarc.example.com TXT “v=DMARC1;p=none;rua=mailto:[email protected]“

In the preceding records:

    • example.com is your domain
    • Value of the TXT record contains the DMARC policy that applies to your domain.
    • In this example, the policy tells email providers to do the following:
      • At least p=none should be implemented.

2. Optimize Email Content

  • Clearly identify yourself as the sender: Use a recognizable “From” name and email address that accurately represents your brand or organization. For example, use “[email protected]” instead of a generic or misleading address.
  • Implement user friendly unsubscribe mechanisms: Include a visible, easy-to-use unsubscribe link in every email, typically in the header. Ensure the unsubscribe process is simple and honors requests promptly, ideally within 24-48 hours. Visit this guide on how Amazon SES helps you do that.
  • Subject line aligns with content: Avoid deceptive subject lines that don’t match the email content.
  • Clearly identify commercial content: If your email is promotional, make it obvious. Use clear language in the subject line and body that indicates the nature of the email, such as “Special Offer” or “Newsletter.”
  • Include a valid physical address: Add your company’s physical mailing address in the email footer. This is not only a legal requirement in many jurisdictions but builds trust with recipients.
  • Verify URLS in the emails: Verify that links in the emails you send work and are not misleading to the reader/subscriber. Be transparent with URLs/links in the email content.

3. Monitor and Maintain

  • Monitor bounces: A bounce typically indicates why a message was not delivered. The SMTP response in the bounce message will have details on why the message was bounced. For example: if it is missing authentication records (fix: include authentication records for the domain – quick fix) versus an IP or domain reputation bounce reason (this maybe a longer term fix).
    • Track both hard bounces (permanent delivery failures) and soft bounces (temporary issues). High bounce rates can indicate list quality problems or delivery issues. Visit this blog to set up notifications for bounces & complaints. Virtual Deliverability Manager (VDM) is an Amazon SES feature that helps you enhance email deliverability. It helps increasing inbox deliverability and email conversions, by providing insights into your sending and delivery data. VDM advices on how to fix the issues that are negatively affecting your delivery success rate and reputation.
  • Track complaint rates: Regularly monitor the number of spam complaints your emails receive with a goal of keeping the complaint rate under 0.2%. Not all mailbox providers have complaint feedback loop data, so use aggregate data from the mailbox providers that do, such as Hotmail and Yahoo. Email providers that don’t provide complaint feedback loops, such as Gmail may have alternative dashboards or tools available like Google Postmaster tools.
  • Perform regular authentication checks: Periodically verify that your SPF, DKIM, and DMARC records are correctly set up and functioning. Alternative to manual DNS checks, Amazon SES has a feature in Virtual Deliverability Manager that performs authentication checks for your sending identities.
  • Maintain list hygiene: Regularly clean your email list by removing inactive subscribers, correcting typos in email addresses, and honoring unsubscribe requests. This helps improve deliverability and engagement rates.

How Amazon SES Helps

Amazon SES provides a robust set of features to help you meet these new requirements and optimize your email sending practices:

Authentication Support

  • Easy DKIM configuration
  • SPF record management
  • DMARC implementation guidance

Comprehensive Monitoring

  • Virtual Deliverability Manager
  • Complaint tracking
  • Bounce rate monitoring
  • Event publishing to Amazon CloudWatch, SNS , Kinesis Firehose and Event Bridge
  • Detailed sending statistics

Compliance Tools

  • List management capabilities (included with SES)
  • Suppression list handling (included with SES)
  • Feedback loop processing (included with SES)
  • Authentication status tracking: This is done through Amazon SES feature Virtual Deliverability Manager (VDM).

Implementation Strategy

To successfully implement these changes, consider the following strategy:

  1. Assessment: Audit your current email practices, review authentication status, and evaluate compliance gaps.
  2. Technical Implementation: Configure authentication protocols, update DNS records, and implement required unsubscribe mechanisms.
  3. Monitoring and Optimization: Track deliverability metrics, monitor complaint rates, and adjust sending practices as needed.

Measuring Success

To ensure ongoing compliance and optimize your email practices, track these key metrics:

  1. Delivery rates
  2. Complaint rates
  3. Authentication pass rates
  4. Engagement metrics (open rates, click-through rates)

Conclusion

The new bulk sender requirements from Microsoft and Yahoo represent an important step towards a more secure and reliable email ecosystem. By leveraging Amazon SES’s powerful features and following industry best practices, you can maintain compliance, improve deliverability, and enhance the overall effectiveness of your email communications.

Amazon SES is committed to helping you navigate these changes and optimize your email sending practices. For the most up-to-date guidance and support, please consult SES’s documentation or contact Amazon SES support.

Additional Resources

The email landscape is constantly evolving. Stay informed and adaptable to ensure your email practices remain effective and compliant.

About the authors:

SMS Onboarding for SaaS, ISV, and Multi-Tenant Applications with AWS End User Messaging

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/sms-onboarding-for-saas-isv-and-multi-tenant-applications-with-aws-end-user-messaging/

Introduction

SMS messaging continues to be one of the most reliable and effective communication channels. However, for Software as a Service (SaaS) companies, Independent Software Vendors (ISVs), and multi-tenant solution providers looking to incorporate SMS capabilities into their offerings, the journey can be complex and filled with challenges.

This guide is specifically designed for technology providers—whether you’re a SaaS company, an ISV, or any platform that enables your customers to send SMS messages to their end users. Throughout this article, the following terminology will be used:

  • Provider: An organization offering SMS capabilities as part of your product or service
  • Customer: The entities using Provider technology to send SMS messages
  • End User: The recipients who opt in to receive SMS messages from Customers

The landscape of SMS implementation can be complicated, with varying country-specific regulations, lengthy registration processes that can take weeks or even months, different originator types (Long Code, Short Code, Sender ID, etc.) with unique capabilities, and the diverse needs of Customers and End Users. These challenges are amplified when you’re a Provider offering SMS services to your own Customers, who in turn serve their End Users.

By the end of this guide, you’ll understand:

  • How opt-in influences architecture
  • Options for how to structure your SMS offering to Customers
  • Strategies for reducing friction in the SMS implementation process

Let’s dive in.

The Registration Dilemma: Who Owns the Relationship?

One of the most critical decisions for your SMS Originator registration is determining whose information is used to apply. The biggest mistake AWS sees Providers make is not knowing how their relationship with their Customers and their Customers’ End Users affects their architecture and how they complete any registrations that are necessary.

Mobile carriers want to know who will be sending SMS to their customers, how that entity will opt them in, and what content they will be sending. When registering for originators, especially in the United States, you will need to succinctly explain how End Users will opt in and how that data will not be shared with any third parties. Your architecture must ensure:

AWS consistently sees Providers register themselves when obtaining an Originator when they do not have a relationship with their Customers’ End Users. The decision of whose information belongs in the registration hinges primarily on a fundamental question: Who does the End User believe they’re entering into a relationship with when they provide their phone number?

The most common scenarios are below:

Scenario 1: End Users interact with the Customer’s brand only

In most cases, End Users are completely unaware of your existence as the Provider. They believe they’re opting in to receive messages from your Customer directly. In this scenario:

  • Registration should be completed using the Customer’s information. There are many ways you can facilitate this process and some ways to reduce this common friction point will be discussed later in this post.
  • Messages should appear to come from the Customer, not the Provider, your service name should not appear in messaging

Scenario 2: End Users explicitly opt in through the Provider application

In some cases, End Users clearly understand they’re opting in to receive messages via your technology platform, on behalf of your Customer. The opt-in data will not be shared with your Customers and your brand, as the Provider, will be the named entity in all SMS sent.

There are a number of ways that this can happen:

  • End Users could opt in using a widget you build that your Customers install on their site or in their app
  • A paper form or verbal script that you supply that clearly identifies you, the Provider

AWS commonly sees this occurring with Providers that supply:

  • Third-party payment processing
  • Shipping and logistics support
  • Customer service platforms
  • One-Time Password (OTP) capabilities

In this scenario your company name would typically appear in the messaging and registration would use your company information.

NOTE: There are edge cases to these two scenarios but the implementation can be complicated, so if you are a Provider and you don’t think that you fit into these two scenarios above make sure to reach out to your Account Manager, open a case, or speak to a specialist before starting to implement anything.

Architectural Models for SMS Implementation

Let’s explore various architectural models for structuring your SMS offering based on your business needs and Customer relationships. Each model has distinct characteristics in the following areas:

1. “Bring Your Own AWS Account” Model

Who does the registration and configuration?

  • The Customer connects their own AWS account, so the registration and any configuration happens in the Customer account.
  • Usually in this scenario the information that is input into the registration is the Customer’s since it’s their account

Customer responsibilities:

  • Customer handles all registration and configuration requirements themselves
  • Customer integrates their account with the Provider service
  • Customer manages sending, opt-out lists, etc.
  • Pays the AWS bill

Provider responsibilities:

  • The Provider offers a user-friendly interface that calls the AWS End User Messaging Service APIs using the Customer’s credentials.
  • The depth of services offered by the Provider can vary

Best for: Technical Customers who want full control and already use AWS; Providers who want to avoid registration and configuration complexities.

2. Provider Account – Manual Registration and Configuration

Who does the registration and configuration?

  • The Provider owns the account and is not providing the Customer with a way to submit their own information so the Provider must enter the information
  • The Customer’s information is captured manually
  • The Provider handles the complexity of registration and configuration through the console

Customer responsibilities:

  • Provide necessary information to the Provider for registration purposes

Provider responsibilities:

  • Captures the registration information manually from Customers.
  • Manages the complexity on behalf of your Customers.

This can be implemented either with separate AWS accounts for each Customer or a multi-tenant architecture in a single account.

Best for: Providers with a small number of high-value Customers who need hand-holding through the SMS implementation process.

3. Semi-Automated Solution – Customer Sending

Who does the registration and configuration?

  • The Provider builds a way for the Customer to submit their registration information, which the Provider then programmatically submits to carriers/regulators.

Customer responsibilities:

  • Your platform manages the technical configuration and provides sending capabilities, but the Customer is responsible for maintaining compliance.

Provider responsibilities:

  • You provide a streamlined way for Customers to submit registration information (webhooks, forms, APIs).
  • You programmatically submit the registration data to carriers/regulators.
  • You manage the technical configuration and provide sending capabilities.

Best for: Providers with moderate technical sophistication who want to reduce friction while maintaining separation of regulatory responsibilities.

4. Fully Automated Solution – Provider Sending

Who does the registration and configuration?

  • The Customer’s information is used in the registration, which you handle programmatically.

Customer responsibilities:

  • You handle all technical aspects of registration, but the Customer is still responsible for maintaining messaging compliance.

Provider responsibilities:

  • You provide hosted, customizable Terms & Conditions and Privacy Policies for each Customer that are compliant out of the box.
  • You offer compliant opt-in pathways (web forms, verbal scripts, etc.).
  • You handle all technical aspects of registration.

Best for: Large-scale Providers serving many Customers with varying levels of technical sophistication.

5. Template-Restricted Fully Automated Messaging

Who does the registration and configuration?

  • The Customer’s information is used in the registration, which you handle programmatically.

Customer responsibilities:

  • You manage all regulatory compliance centrally, and the Customer can only personalize specific fields in pre-approved message templates.

Provider responsibilities:

  • You provide a suite of pre-approved message templates.
  • You manage all regulatory compliance centrally.
  • You simplify the registration process since the content is tightly controlled.

Best for: Use cases with predictable messaging needs like appointment reminders, shipping notifications, or one-time passwords.

6. Fully Managed Programs

Who does the registration and configuration?

  • The Customer authorizes you to send messages on their behalf, so you own the relationship with the end-user and the registration.

Customer responsibilities:

  • Only required to give you any pertinent information necessary for you to send messages to the End-Users. This could be things like tracking numbers or other information that the particular use case requires and is part of the personalization that is allowed.

Provider responsibilities:

  • You manage all aspects of the end-user relationship.
  • You control the entire messaging experience, including opt-in collection and the end-user relationship.

Example: A shipping notification service might send messages like: “ShipTrack: Your order from ACME Corp will arrive tomorrow. Track at [link]”

Best for: Specialized use cases where your platform adds significant value as an identified intermediary.

Shaping Your SMS Offering: Strategic Considerations

Pricing Strategies

When incorporating SMS into your product, one of the first considerations is how to structure your pricing. Unlike many digital services with predictable costs, SMS pricing varies significantly based on destination country, originator type, and volume.

AWS End User Messaging Service bills based on volume sent per country, with each country having its own price point. This pricing is determined by the recipient’s handset country code, not their physical location. This means that even if you primarily serve U.S. based Customers, you may need to account for international rates when recipients have non-U.S. phone numbers.

There are also one-time and ongoing fees to be accounted for. Registrations often have one-time processing fees and Originators can have leasing costs that range from free to more than $1,000 a month for short codes in some countries. Make sure that you think through how those costs will or will not be passed to your Customers.

As you design your pricing model, consider these common volume based approaches:

  • SMS Credits: Create a standardized credit system where Customers purchase credits regardless of destination country. You would internally manage the conversion between credits and actual costs.
  • Dollar-Based Allocation: Provide Customers with a budget that gets depleted based on actual costs per message sent.
  • Tiered Country Pricing: Group countries into tiers (e.g., Tier 1 for North America, Tier 2 for Western Europe) with different pricing for each tier.
  • Bundled Messaging: Include a certain number of messages in your base subscription with overage fees for additional messages.

Each approach has trade-offs in terms of simplicity, transparency, and risk management. Your decision should align with your overall business model and Customer expectations.

Geographic Considerations

Different countries have distinct regulatory requirements for SMS messaging, including:

  • Originator Support: Not all countries support all originator types, view the details here
  • Originator Selection: In cases where multiple types of originators are supported, how do you support your Customer in selecting the right originator for the right use case?
  • Read through this tutorial to help decide what originator(s) are right for your use case(s)
  • Registration: An increasing numbers of countries require you to register before being allowed to send
  • Quiet hours: Many countries restrict when promotional messages can be sent
  • Content restrictions: Certain types of content (gambling, alcohol, adult content, etc.) may be prohibited or heavily restricted. A more comprehensive list can be found here
  • Template requirements: Some jurisdictions require pre-approval of message templates
  • Sender ID regulations: Rules regarding who can use alphanumeric sender IDs vary widely

As a Provider, you need to decide which countries you’ll support and how you’ll ensure compliance across markets. This decision affects not just your pricing but your entire product architecture, especially if you serve global Customers.

Strategies to Reduce Implementation Friction

Implementing SMS can be complex for your Customers. Here are some strategies that can simplify and/or streamline the process. Some of these can be mixed and matched and could also be used as a value-add or even as a paid offering to your Customers:

Provider-Hosted Privacy Policy and/or Terms & Conditions

Create customizable, compliant templates for Privacy Policies and Terms & Conditions that your Customers can use. This ensures proper disclosure of SMS practices without requiring Customers to update their own legal documents.

Registration Webforms and Workflows

Develop user-friendly webforms that collect all required registration information in a guided process. These can significantly simplify complex registrations like 10DLC brand and campaign registration.

Below, Figures 1-3, you will find several examples of compliant forms that could be customized for your use:

Fig. 1

Fig. 2

Fig. 3

Pre-Approved Opt-In Widgets

Create embeddable widgets, such as Figures 1-3 above, that your Customers can add to their websites or apps that implement compliant opt-in processes. These can include all required disclosures and confirmations while being easy to integrate.

Template Libraries

Provide a library of pre-approved message templates for common use cases. This reduces compliance risks and simplifies the sending process for your Customers.

Testing Environments

Create sandbox environments where Customers can test their SMS implementation before going live. This helps catch issues with formatting, opt-in processes, or content compliance.

Documentation and Training

Develop clear documentation and training resources specific to each originator type and use case. This empowers your Customers while reducing support burden.

Conclusion

Incorporating SMS capabilities into your platform can enhance Customer engagement, but the journey can be complex. This guide has explored key considerations to help you navigate it successfully.

This post examined various architectural models, each with tradeoffs in Customer responsibilities and Provider responsibilities. This post reviewed strategic factors like pricing, geographic regulations, and originator types that must be carefully considered.
Finally, practical strategies to reduce implementation friction for Customers such as hosted compliance documents, streamlined registration workflows, and pre-approved templates, you can use to simplify the integration process were discussed .

The critical first step though, is understanding the relationship between you as the Provider, your Customers, and their End Users. This shapes whose information is used for originator registration, which in turn defines the SMS experience.

Ultimately, a successful SMS solution requires balancing technical, regulatory, and Customer-centric factors. Leveraging this guidance will equip you to design and deploy an offering that delights your Customers and their End Users.

Additional resources:

Defending Against SMS Pumping: New AWS Features to Help Combat Artificially Inflated Traffic

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/defending-against-sms-pumping-new-aws-features-to-help-combat-artificially-inflated-traffic/

As businesses increasingly rely on SMS messaging to engage customers, AWS End User Messaging is enhancing its SMS Protect feature to now include automated message filtering based on the risk of Artificially Inflated Traffic (AIT) from each message request. This new capability helps protect against AIT, also known as SMS pumping. AIT occurs when malicious actors use bots and other measures to generate fake SMS traffic, targeting businesses’ customer communication workflows like one-time password triggers, app downloads, and promotional signups. In a recent report co-authored by Enea it was shown that AIT accounted for 19.8 billion to 35.7 billion fraudulent SMS messages in 2023, costing over $1 billion. All workflows with user generated messages are susceptible to AIT but insecure public webforms are the most commonly used as a vector to exploit and generate SMS messages. The goal is to artificially inflate the number of SMS messages a business sends, resulting in increased costs and a negative impact on the sender’s reputation.

We launched AWS End User Messaging Protect to help our customers combat this growing threat. Initially launched with Country Level Blocking, we’ve now launched two new features, called Monitor and Filter, within AWS End User Messaging’s Protect capabilities. Updating your current security posture for SMS with Monitor and Filter, along with adhering to some other best practice security measures we will cover later, will make it harder for bad actors to target and inflate your SMS costs with bots or other measures.

What is SMS Protect Filter and Monitor?

Filter and Monitor are the next layers of defense in our Protect Feature Set. These features are designed to provide enhanced protection against AIT for countries in which you need to send messages by analyzing and proactively blocking messages that are suspected to be fraudulent. The Filter setting blocks suspected AIT messages. The Monitor mode allows you to evaluate how Filter would affect your sending, without blocking. Monitor could also be used for the events it emits, which could be leveraged in your own custom AIT solutions, but again, does not automatically block messages.

Filter Mode: Automated Blocking of Suspected Artificial Traffic

The Filter mode in Protect takes your AIT mitigation efforts to the next level by automatically blocking messages that exhibit patterns of artificial inflation. When you set your configuration to “Filter” the model will automatically filter any messages being sent that match patterns indicative of AIT.

Filter mode provides automated defense against AIT by analyzing and proactively blocking AIT messages before they leave AWS, reducing your exposure to the financial and reputational impacts of SMS pumping. Turning on Filter at the Account level is the quickest way to protecting yourself. The tutorial below will walk you through configuration.

Importantly, when a message is blocked in Filter mode, you do not incur the normal per-message fees, instead you only pay for the lesser costs associated with the Protect Filter capabilities, providing a more cost effective approach to message security.

Monitor Mode: Gain Visibility and Insights into Potentially Suspicious Traffic

The Monitor mode in Protect works identical to filter, it uses the same AIT prediction models behind the scenes, but rather than blocking suspected AIT it simply emits recommendations for blocking based on the patterns of data. The recommendations are delivered in a new field attached to the Delivery Receipts (DLRs) that are already streamed via Event Destinations. The recommendations are also logged in summary to CloudWatch and the End User Messaging Console Dashboards. This provides you with valuable data and insights to help inform your AIT mitigation strategy.

Messages sent while in monitor mode will not be blocked and will be charged the country per message cost as well as the Protect Monitor per message cost.

If you want to see what our AIT prediction models recommend without AWS actually blocking messages, you can start in Monitor Mode and change to Filter when you are more comfortable. This allows you to understand how your traffic is analyzed by our AIT prediction models without immediately blocking messages, offering a cautious and informed approach to how Filter will affect your Account.

The Monitor mode reports include detailed analytics on blocked message volumes, geographic distribution, carrier patterns, and more. By analyzing this data, you can identify specific countries, number ranges, or sending behaviors that may be indicative of artificially inflated traffic. This helps you make informed decisions about where to apply more stringent controls.

Importantly, during the monitoring phase, Protect also provides recommendations on whether a particular message would have been blocked and whether certain numbers should be blocked in the future. This gives you the ability to fine-tune your configurations and better understand your traffic before taking enforcement actions.

How do you get started with Protect Monitor and Filter?

Every customer’s needs are unique, but for most customers, we suggest the following steps:

  1. Block all countries to which you do not send messages
    1. Your first line of defense should be to block all traffic to countries where you don’t conduct business or need to send messages. Preventing unwanted messages from being sent is the simplest way to help prevent SMS pumping in the first place. You can use Protect Country Blocking rules to do this and they can can be applied to SMS, MMS, and voice messages sent from your AWS account. For a tutorial on how to do this you can read this earlier blog on Protect.
  2. Create an account level “Filter” configuration
    1. When considering the risk of AIT in a specific country we recommend aligning risk level with the SMS per message cost. The higher the cost the higher the risk.
  3. Make sure that your forms and other vulnerable public facing messaging workflows are protected with best practice security measures that we will review further on in this post.

How to create a protect configuration

You can use a Protect configuration at different levels of granularity:

  1. As the default for your entire AWS account(Good for customers with a single use case)
  2. Associated with a specific Configuration Set
  3. Directly specified when calling the SendMediaMessage, SendTextMessage, or SendVoiceMessage APIs
    NOTE: You can only change your MMS country rules list through the AWS End User Messaging SMS and voice v2 API or AWS CLI. The Voice rules can be changed in the console but only after creating an SMS Protect Configuration. Once you have created your first Configuration you can edit it and select the “Voice Rules” tab.

The main benefit of Protect configurations is the ability to control where you send messages and avoid unexpected costs or compliance issues. By creating multiple configurations you can apply specific rules that control how messages are processed and delivered based on your unique business needs. Let’s walk through how to set them up.

Creating a Protect Configuration

  1. To create a Protect Configuration, log into the AWS Management Console and navigate to End User Messaging.
  2. From there, go to the “SMS” section and select “Protect configurations”.
  3. Click the “Create protect configuration” button and give your new configuration a name.
    1. Define the specific allow and block rules for SMS, MMS, and voice messages.
      1. Checking a box next to a country blocks that country and checking the box for a region will block all countries associated with that region.

Once you’ve configured the country rules, you can choose how to associate this Protect configuration:

  1. Set it as the default for your entire AWS account
    1. For many customers this should be the default. Having an account level configuration as a fallback helps protect you incase you forget to specify a protect configuration in your request.
    2. Note: To use a protect configuration with other AWS services to send messages, like Amazon SNS, Amazon Connect, or Amazon Pinpoint, you need to set your protect configuration as the account default
  2. Associate it with one or more Configuration Sets
    1. This setting will be applied anytime you send SMS with the config set associated with this Protect Configuration
  3. Leave it unassociated to use it explicitly in API calls
    1. This setting allows you to apply it whenever you want. This will override any previous associations when you reference the “ProtectConfigurationId” in your SendMediaMessage, SendTextMessage, or SendVoiceMessage calls

You can also add optional tags to help organize your resources.

  1. Click “Create protect configuration”
    1. NOTE: You can only change your MMS country rules list through the AWS End User Messaging SMS and voice v2 API or AWS CLI. The Voice rules can be changed in the console but only after creating an SMS Protect Configuration. Once you have created your first Configuration you can edit it and select the “Voice Rules” tab.
  2. How to add Filter or Monitor to the Protect Configuration you just created
    1. Click into the Protect Configuration you just created
      1. Note the “SMS Rules” tab and the “Voice Rules” tab can have different rule settings. Make sure you are editing the right channel
  3. You will once again select the country or region you wish to set to Filter(recommended) or Monitor

    1. Confirm the changes and you will see your changes in the next screen

Getting more granular with Protect Configurations

In most cases you should be using “Filter” account wide for the countries you are concerned about AIT in, but If you have different public and/or private messaging workflows you may benefit from a more precise, or granular, approach to your messaging and security practices. If you want more control, the first step is to identify your traffic that is a high risk for SMS pumping. Any public-facing forms or workflows that trigger SMS being sent are prime targets for attackers to try and pump SMS are at high risk, such as:

  • One-time passwords or 2FA flows
  • Password/User resets
  • New user registrations
  • Other

Creating a separate Protect Configuration for each of these different workflows will help the models in Protect more effectively identify anomalies and tailor its detection models to your specific messaging patterns. Service-initiated messages, such as appointment reminders or marketing campaigns that are not user-generated are at much less risk of SMS pumping attacks so you may decide not to include them in the same Protect config as a public facing workflow to reduce overall costs.

You can follow the directions above for creating a Protect Configuration for each of the workflows you identify. You might configure something like the below, where “OTP New Sign Up” and “Password Reset” have Filter enabled for the countries of concern and the “Marketing Newsletter” Configuration would not have either configured since that use case does not involve a publicly available form that triggers an SMS being sent. Creating a Protect Configuration for different use cases gives you more granular control over your messaging, your messaging budget, and ensuring the integrity of your communications

Updating an Existing Protect Configuration

After creating a Protect configuration, you may need to modify the country rules, change the association or as we saw above, add Filter or Monitor to certain countries. To do this, simply navigate back to the “Protect configurations” section and select the one you want to update.

From here you can edit the allow/block country lists, change the association, or even delete the configuration if needed. Just be careful with the account default – you’ll want to be sure you have another default in place before removing the existing one.

Using Protect Configurations

Once you have your Protect configurations set up, you can start putting them to use. If you’ve associated one with a Configuration Set, any messages sent using that Configuration Set will automatically have the Protect rules applied.

Alternatively, you can specify the ProtectConfigurationId parameter when calling the SendMediaMessage, SendTextMessage, or SendVoiceMessage APIs. This allows you to override the account default or Configuration Set association on a per-message basis.

Reporting on Protect Configurations

There are two places within the console that you can see metrics for your Protect Configurations. The Monitoring tab on a protect configuration provides an overview of message delivery metrics for the protect configuration. To view all metrics for your account in the AWS End User Messaging SMS console choose Dashboard in the left hand navigation. You can also use CloudWatch to view and create alarms. For more information on CloudWatch metrics, see Dashboard metrics, and Create CloudWatch Alarms.

Monitoring tab on a specific Protect Configuration

End User Messaging provides multiple charts that helps you understand how your country rule configurations (Allow, Block, Monitor, or Filter), along with phone number rule overrides are controlling SMS sending overall, and to specific countries.

The included charts are:

  • Number and Percentage of Blocked Messages: Shows the count and percentage of SMS and MMS messages that were blocked during the selected time period. This includes messages blocked by country rules set to ‘block’ or ‘filter’ mode, as well as messages blocked by phone number override rules.
  • Number of Blocked Messages by Country: Shows the count of SMS and MMS messages that were blocked during the selected time period, broken down by destination country.
  • Number and Percentage of Messages Recommended to Block: Shows the count and percentage of SMS and MMS messages that were identified as risky by the AIT risk prediction model. This includes messages in both ‘monitor’ and ‘filter’ modes. In monitor mode, these messages are delivered but flagged; in filter mode, these messages are blocked.
  • Number of Messages Recommended to Block by Country: Shows the count of SMS and MMS messages identified as risky by the AIT prediction model, broken down by destination country.

Implementing a Layered Approach to SMS Security

While Filter and Monitor are new tools in the fight against AIT, they should be implemented as part of a broader, layered security strategy for your SMS messaging infrastructure. Here are some best practices to consider:

Identify and compartmentalize Your Traffic

You are able to create multiple Protect Configurations based on different use cases, such as one-time passwords, marketing campaigns, and appointment reminders. This granular approach allows Protect’s prediction models to better understand your expected traffic patterns and identify anomalies more accurately. Once you have identified your traffic types you can assign different configurations to them. You may set a marketing configuration to not be filtered or monitored because it’s not user generated but an OTP type with a publicly available form you may want to set to Filter. In this way you save money by protecting only the messages that are more likely to be susceptible to AIT. Each of these may block the same countries but operate differently with regards to identifying and blocking potentially fraudulent traffic.

Leverage Geographic Controls:

Always start by blocking countries where you have no business presence, then allow-list the regions where you actively engage customers and have not seen AIT issues. For countries where you suspect potential abuse, utilize the Monitor mode to gather data before deciding on a blocking strategy.

Allow-list Legitimate phone numbers in countries you are blocking

To avoid impacting your critical messaging workflows, implement phone number rule overrides for specific countries where you are blocking traffic. As an example, if you have engineers in Columbia that you want to be able to send SMS to but you don’t have any legitimate reason other than that to send to Columbian handsets you can block Columbia but allow-list those engineer’s phone numbers. You can also provide your front end support teams the functionality to add numbers to allow-lists in case a number is mistakenly blocked by Filter recommendations

  1. To create a phone number override rule using the console, follow these steps:
  2. Open the AWS End User Messaging SMS console at https://console.aws.amazon.com/sms-voice/.
  3. In the navigation pane, under Protect, choose the Protect configuration you want to add allow-list numbers in
  4. Choose the Rule overrides tab and in the Rules override section choose Add override.
    1. In the Rule override details section, enter the following:
      1. For Destination phone number enter the phone number to create the rule for. The phone number must start with a ‘+’ and can’t contain any spaces, hyphens, or parentheses. For example, +1 (206) 555-0142 is not in the correct format, but +12065550142 is.
      2. For Override type choose either Always allow or Always block.
      3. For Expiration date – optional choose a date for the rule expire or leave it blank for the rule to never expire.
  5. Choose Add rule override.

Integrate with Complementary Security Services

Enhance your SMS security posture by integrating Protect with other AWS services, such as AWS Web Application Firewall (WAF) for web-based attack protection and Amazon Cognito for robust user authentication. See this post on Cognito Security for more detailed information on how to add self-service sign-up, sign-in, and control access features to your web and mobile applications while benefitting from SMS authentication and fraud protection with End User Messaging Protect Block, Monitor, and Filter.

WAF has out of the box support for complementary security protections such as CAPTCHA, IP blocking, and JA3 fingerprint matching which are all best practice features to help protect your public forms that may be at risk for SMS pumping.

Review and Iterate

Regularly review your Protect configurations, analyze false positive rates, and update your allow-lists and rules as your messaging patterns evolve. If you are satisfied with your blocking, leave it alone. If you want to get more precise and remove false positives, look for which protect configurations have identified suspected AIT, and try to make them more granular. For example, if you have a sign-up form that is currently being triggered from two separate web pages, you could have a config set for each of those pages and trigger a different config set with Filter mode activated for each. Maintaining an agile, data-driven approach is key to ensuring optimal balance between security and service availability for your legitimate customers.

Conclusion

Take a proactive, multilayered approach to combating the growing threat of SMS fraud by leveraging the new Filter and Monitor capabilities within AWS End User Messaging Protect. These features empower you to gain visibility into potentially malicious traffic, automate the blocking of suspected AIT, and protect your messaging infrastructure while preserving the seamless experience your customers expect.

To get started with Protect and explore these new features, visit the AWS End User Messaging documentation or reach out to your AWS account team. We’re here to help you strengthen the security and integrity of your SMS communications.

Automating Sender ID Configuration for SMS with AWS End User Messaging APIs

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/automating-sender-id-configuration-for-sms-with-aws-end-user-messaging-apis/

Global SMS messaging with consistent Sender ID branding requires configuring the same Sender ID across multiple countries, which is a time-consuming process for businesses operating internationally. In this post, we’ll show you how to automate the configuration of Sender IDs for countries that do not have registration requirements using the AWS End User Messaging v2 API.

The Challenge of Multi-Country Sender ID Configuration

When sending SMS messages internationally, if you are using Sender ID, you want your brand to be consistently recognized. This means configuring the same Sender ID in each country you send to. However there are several challenges related to this:

  • Each country must be done manually, one at a time, if using the AWS Console
  • If you have multiple environments for testing the process must be repeated for each Account/Region
  • If you are moving account/regions you have to reconfigure each country in the new Account/Region
  • Manual configuration can be error prone
  • Errors can be detrimental to a brand

The Solution: AWS Lambda Automation

This solution can be applied to any country that supports Sender ID configurations and does not require registration. You can view a comprehensive list of these eligible countries here.

Below is an AWS Lambda function that streamlines this process by handling bulk configuration requests. The function solves the challenges in handling multiple country configurations in a single automated workflow. Here’s the complete code:

import boto3
import uuid
import json
import time
from typing import Dict, Any, List

def validate_input(sender_id: str, countries: List[str]) -> bool:
    if not 1 <= len(sender_id) <= 11:
        raise ValueError("Sender ID must be between 1 and 11 characters")
    
    if not sender_id.replace('_', '').replace('-', '').isalnum():
        raise ValueError("Sender ID can only contain alphanumeric characters, underscore, and hyphen")
    
    if not countries:
        raise ValueError("At least one country code must be provided")
    
    return True

def request_sender_id(client, sender_id: str, countries: List[str], message_types: List[str] = None, tags: List[Dict] = None) -> List[Dict]:
    if message_types is None:
        message_types = ["TRANSACTIONAL", "PROMOTIONAL"]
    
    results = []
    
    for i, country in enumerate(countries):
        if i > 0:
            time.sleep(1)  # Rate limiting: 1 request per second
            
        try:
            print(f"Processing country: {country} ({i+1}/{len(countries)})")
            request_params = {
                'ClientToken': str(uuid.uuid4()),
                'SenderId': sender_id,
                'IsoCountryCode': country.upper(),
                'MessageTypes': message_types,
                'DeletionProtectionEnabled':True
            }
            
            if tags:
                request_params['Tags'] = tags
                
            response = client.request_sender_id(**request_params)
            
            results.append({
                'Country': country,
                'Status': 'Success',
                'SenderIdArn': response.get('SenderIdArn'),
                'MonthlyLeasingPrice': response.get('MonthlyLeasingPrice')
            })
            
        except Exception as e:
            results.append({
                'Country': country,
                'Status': 'Failed',
                'Error': str(e)
            })
            
        print(f"Completed {country}: {'Success' if results[-1]['Status'] == 'Success' else 'Failed'}")
    
    return results

def lambda_handler(event: Dict[str, Any], context: Any) -> Dict[str, Any]:
    try:
        # Extract parameters from event
        sender_id = event['sender_id']
        countries = [c.strip().upper() for c in event['countries'] if c.strip()]
        tags = event.get('tags')  # Optional
        message_types = event.get('message_types', ["TRANSACTIONAL", "PROMOTIONAL"])  # Optional
        
        # Validate input
        validate_input(sender_id, countries)
        
        # Initialize the AWS SMS Voice v2 client
        client = boto3.client('pinpoint-sms-voice-v2')
        
        # Process the request
        results = request_sender_id(
            client=client,
            sender_id=sender_id,
            countries=countries,
            message_types=message_types,
            tags=tags
        )
        
        # Calculate summary
        successful = sum(1 for r in results if r['Status'] == 'Success')
        
        return {
            'statusCode': 200,
            'body': {
                'results': results,
                'summary': {
                    'total': len(countries),
                    'successful': successful,
                    'failed': len(countries) - successful
                }
            }
        }
        
    except Exception as e:
        return {
            'statusCode': 500,
            'body': {
                'error': str(e)
            }
        }

How the Lambda Function Works to Configure Sender IDs

The Lambda function automates the Sender ID configuration process through these key steps:

  • Input Validation: Ensures the Sender ID meets format requirements (1-11 alphanumeric characters, with optional underscores or hyphens).
  • Bulk Registration: Processes each country sequentially with built-in rate limiting (1 request per second) to prevent API throttling.
  • Logging: Returns the full ARN of each successfully configured Sender ID
  • Flexible Configuration Settings:
    • Supports multiple message types (transactional, promotional, or both)
    • Enables resource tagging for organizational and cost tracking
    • Provides deletion protection to prevent accidental removal
  • Cost Transparency: Displays monthly leasing price for each successful country configuration
  • Error Handling: Individual country failures don’t halt the entire process, allowing partial success if a single country were to fail for some reason.

Using the Lambda Function

To use this function, create a Lambda with the code above and configure an event. The tags are optional and we have provided an example below:
NOTE: Depending on the number of countries you are attempting to register at a time, you may need to increase the 3 second default Lambda timeout. For reference, in our testing, we were able to do all Sender IDs(160) in less than 3 minutes.

Test Event Example

{
    "sender_id": "YourBrand",
    "countries": ["GB", "DE", "FR"],
    "tags": [
        {
            "Key": "Environment",
            "Value": "Production"
        },
        {
            "Key": "Department",
            "Value": "Marketing"
        }
    ]
}

IAM Permissions

Your Lambda will need these minimum AWS Identity and Access Management (IAM) permissions, scale back the resource if necessary:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sms-voice:RequestSenderId",
                "sms-voice:TagResource"
            ],
            "Resource": "arn:aws:sms-voice:*:**ACCOUNT#**:sender-id/*"
        }
    ]
}

The Trust Policy required for Lambda to assume the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Results Example

The Lambda will return results for each country, including configuration status and monthly costs, if any. Below you will see an example of 3 countries being configured:


{
  "statusCode": 200,
  "body": {
    "results": [
      {
        "Country": "GB",
        "Status": "Success",
        "SenderIdArn": "arn:aws:sms-voice:us-west-2:**ACCOUNT#**:sender-id/LAMBDATEST2/GB",
        "MonthlyLeasingPrice": "0.00"
      },
      {
        "Country": "DE",
        "Status": "Success",
        "SenderIdArn": "arn:aws:sms-voice:us-west-2:**ACCOUNT#**:sender-id/LAMBDATEST2/DE",
        "MonthlyLeasingPrice": "0.00"
      },
      {
        "Country": "FR",
        "Status": "Success",
        "SenderIdArn": "arn:aws:sms-voice:us-west-2:**ACCOUNT#**:sender-id/LAMBDATEST2/FR",
        "MonthlyLeasingPrice": "0.00"
      }
    ],
    "summary": {
      "total": 3,
      "successful": 3,
      "failed": 0
    }
  }
}
Function Logs:
START RequestId: 81d2d144-9023-413d-b976-c87c79a82eae Version: $LATEST
Processing country: GB (1/3)
Completed GB: Success
Processing country: DE (2/3)
Completed DE: Success
Processing country: FR (3/3)
Completed FR: Success

After processing your Sender ID configurations, it’s crucial to verify them. You can do this via the AWS console or by using the DescribeSenderIds API. This API offers flexible retrieval options:

  • Specify individual Sender IDs for targeted information
    • Providing an invalid Sender ID will result in an error
  • Apply filters to narrow your results
  • Retrieve all Sender IDs associated with your AWS account by omitting both

Conclusion

Automating Sender ID configuration with the AWS End User Messaging v2 API and a Lambda function will dramatically reduce the time spent on manual configuration, ensure consistent branding across all supported and configured countries, and simplify a complex process. You’ll gain a scalable, reliable solution that allows you to deploy and manage your Sender IDs with confidence.

Additional resources:

AWS End User Messaging SMS documentation

SMS V2 API

Building a voice interface for generative AI assistants

Post Syndicated from Reynaldo Hidalgo original https://aws.amazon.com/blogs/messaging-and-targeting/building-voice-interface-for-genai-assistant/

Generative AI is revolutionizing how businesses interact with their customers through natural conversational interfaces. While organizations can implement AI assistants across various channels, phone calls remain a preferred method for many customers seeking support or information.

We’ll demonstrate how to create a voice interface for your existing Amazon Bedrock generative AI assistant, enabling customers to engage in phone-based conversations with your AI implementation.

Solution overview

Using Workflow Studio for Amazon Web Services (AWS) Step Functions, we built a voice communication interface that connects with the Amazon Nova Micro model in Amazon Bedrock (Figure 1). The demo application uses the base model to enable open-ended questions. Organizations can implement either Amazon Bedrock Agents or Flows to address specific business requirements.

A Step Functions workflow diagram illustrating a voice communication system integrated with Amazon Bedrock. The workflow shows a sequential process starting with call handling, followed by parallel branches: one for managing hold music and another for processing voice input through Amazon Transcribe and Amazon Nova Micro model. The diagram demonstrates the complete call flow from initial welcome message through question-answer cycles to call completion.

Figure 1 – Step Functions workflow that enables voice communication to a generative AI assistant

How it works:

  1. Inbound call arrives
  2. System plays welcome message
  3. System asks caller for questions
  4. Voice recording starts, stopping when silence is detected
  5. Parallel flows begin:
    • First flow
      1. Plays some music while the caller is on-hold
    • Second flow
      1. Transcribes the recording using Amazon Transcribe
      2. Sends transcribed question to the Amazon Nova Micro model in Amazon Bedrock
      3. Upon receiving the response, stops the on-hold music
  6. Text-to-speech plays the model’s answer
  7. System asks for additional questions and loops to Step 4 or ends the call

 Expanded capabilities and optimizations

These are potential improvements, additional functionalities, and advanced features that can enhance the demo application:

  • The transcription component is interchangeable with any speech-to-text generative AI model (including Whisper Large V3 Turbo on Amazon Bedrock Marketplace)
  • The PSTN audio service RecordAudio Action can be tuned to adjust silence duration and background noise levels
  • Enabling the PSTN audio service VoiceFocus feature to improve call clarity by reducing background noise and enhancing voice quality
  • PSTN audio service Session Initiation Protocol (SIP) media applications can also handle calls through SIP trunking by using Amazon Chime SDK Voice Connector, streamlining integration with existing phone systems
  • The UpdateSipMediaApplicationCall API is a PSTN audio service feature that lets you regain call control and apply new actions during active calls
  • Parallel workflow states allow user-friendly handling of API service calls by playing music during processing
  • PSTN audio service provides pay-per-minute rates with serverless, scalable telephony infrastructure

Deploying the solution

 The following steps allow you to deploy the voice communication interface workflow (Figure 1) together with the supporting serverless architecture for Step Functions and PSTN audio service integration. In a previous blog, we demonstrated how combining Step Functions and Amazon Chime SDK PSTN audio service streamlines the development of reliable telephony applications through a visual workflow design.

 Prerequisites:

  1. AWS Management Console access
  2. Node.js and npm installed
  3. AWS Command Line Interface (AWS CLI) installed and configured
  4. Enable access to the Amazon Nova Micro model through the Amazon Bedrock console

 Walkthrough:

The AWS Cloud Development Kit (AWS CDK) project on the AWS GitHub repository will deploy the following resources:

  • phoneNumberBedrock – Provisioned phone number for the demo application
  • sipMediaApp – SIP media application that routes calls to lambdaProcessPSTNAudioServiceCalls
  • sipRule – SIP rule that directs calls from phoneNumberBedrock to sipMediaApp
  • lambdaProcessPSTNAudioServiceCalls – AWS Lambda function for call processing
  • roleLambdaProcessPSTNAudioServiceCalls – AWS Identity and Access Management (IAM) Role for lambdaProcessPSTNAudioServiceCalls
  • stepfunctionBedrockWorkflow – Step Functions workflow for the telephony application
  • roleStepfuntionBedrockWorkflow – IAM Role for stepfunctionBedrockWorkflow
  • s3BucketApp – Amazon Simple Storage Service (Amazon S3) bucket for storing customer questions recordings
  • s3BucketPolicy – IAM Policy granting PSTN audio service access to s3BucketApp
  • lambdaAudioTranscription – Lambda function for audio transcription
  • lambdaLayerForTranscription – Lambda layer required for lambdaAudioTranscription
  • roleLambdaAudioTranscription – IAM Role for lambdaAudioTranscription

Follow these steps to deploy the CDK stack:

  1. Clone the repository.
git clone https://github.com/aws-samples/sample-chime-sdk-bedrock-voice-interface
cd sample-chime-sdk-bedrock-voice-interface
npm install
  1. Bootstrap the stack.
#default AWS CLI credentials are used, otherwise use the –-profile parameter
#provide the <account-id> and <region> to deploy this stack
cdk bootstrap aws://<account-id>/<region>
  1. Deploy the stack.
#default AWS CLI credentials are used, otherwise use the –-profile parameter
#phoneAreaCode: the United States area code used to provision the phone number
cdk deploy –-context phoneAreaCode=NPA
  1. Call the provisioned phone number to test the sample application.

Cleaning up:

To clean up this demo, execute:

cdk destroy

Conclusion

We demonstrated how organizations can add voice capabilities to their existing generative AI implementations using Amazon Bedrock. The solution enables customers to interact with AI assistants through traditional phone calls, expanding accessibility and user engagement. The demo application showcases an architecture combining AWS Step Functions and Amazon Chime SDK PSTN audio service, delivering natural voice conversations with AI models through quick deployment using visual workflows.

Organizations benefit from cost optimization with pay-per-minute pricing, enterprise-ready telephony integration through PSTN or SIP trunking, and automatic scaling to match customer demand. This foundation enables businesses to build practical AI applications ranging from all day customer service agents, to multi-language support services, and knowledge base assistants. By following this solution, you can quickly extend your generative AI investments to voice channels, providing more value to your customers while maintaining operational efficiency.

Contact an AWS Representative to know how we can help accelerate your business.

Improving email security with Amazon SES Mail Manager and Hornetsecurity’s Vade Advanced Email Security Add On

Post Syndicated from Zip Zieper original https://aws.amazon.com/blogs/messaging-and-targeting/improving-email-security-with-amazon-ses-mail-manager-and-hornetsecuritys-vade-advanced-email-security-add-on/

Email continues to be a critical communication channel for businesses, powering essential communications across time zones and locations. But as cyber threats grow more sophisticated, how can organizations protect their most vulnerable communication channel? With the increasing complexity of email-based security risks, businesses need robust solutions to safeguard their digital communications. Today, we’re excited to announce the launch of Hornetsecurity’s Vade Advanced Email Security Add On for Amazon Simple Email Service (SES) Mail Manager, a powerful new tool in the fight against email-borne threats.

Amazon SES: Powering email communication at scale

Amazon SES is a cloud-based email service that helps you automate high-volume email communications seamlessly. In May 2024, we launched Mail Manager, introducing email relay and gateway features that help you manage email traffic, ensure compliance and enforce corporate policies. The launch also included an introduction to Mail Manager Email Add Ons which provides optional access to a collection of powerful security tools from certified providers that help you manage and filter incoming emails. Add Ons from our partners deliver advanced email security with flexible, meter-based pricing that is easily activated and integrated into your email workflows directly from the Mail Manager console or Mail Manager APIs.

In this blog, we’ll introduce Hornetsecurity’s Vade Email Add On for Amazon SES Mail Manager, and demonstrate how to enable its advanced email security capabilities to help protect your critical email communications.

Introducing the Vade Email Add On by Hornet Security

Hornetsecurity, a global leader in email security, produces next-generation cloud-based security, compliance, backup, and security awareness solutions that help companies and organizations of all sizes around the world. Its email filters process billions of emails daily, using a vast global email database to power their artificial intelligence (AI) engine. This approach allows the Vade Email Add On to continuously refine and adapt to the latest email threats and filter-bypassing techniques.

The Vade Email Add On brings Vade’s expertise directly to you, providing a seamless and powerful email security solution within the familiar AWS environment:

“Enhance your email service with advanced cybersecurity capabilities by integrating Vade Email Security’s state-of-the-art filtering solution. This Add On empowers users with automated, real-time defense against spam, malware, and phishing—ensuring safer communication. Vade’s AI-powered technology employs a multi-layered approach—combining heuristics, behavioral analysis, and natural language processing—to analyze messages in real time. Strengthen your platform by ensuring ongoing protection against evolving cyber threats.”

Advanced Email Security with the Vade Add On for Mail Manager

Hornetsecurity’s Vade Add On for Mail Manager provides automated, real-time defense against spam, malware, and phishing, which help ensure safer communication, including:

  • Advanced Threat Detection: Identifies and blocks sophisticated phishing attempts, malware, and ransomware, providing comprehensive protection against a wide range of cyber threats.
  • Behavioral Analysis: Examines the behavior patterns of message senders and content based on over 130 potential data points in each message to detect anomalies and potential threats.
  • Patented AI Technology: Leverages proprietary AI algorithms to analyze communication patterns and detect misuse of your service’s digital assets. This technology is powered by our global network of over 1 billion protected mailboxes.
  • Real-Time Scanning: Instantly analyze attachments without delaying delivery, thanks to its real time code interpreter.
  • Ease of Use: Seamless integration with Mail Manager rules, scanning only messages that meet specific criteria.

The Vade Email Add-On integrates with Mail Manager’s rules engine. This engine routes messages based on Vade’s scan results and optional detailed verdicts. These verdicts enable precise categorization and handling of incoming emails, improving security and email management.

Configure the Vade Email Add On

In the following example, we’ll walk thru the steps needed to subscribe and configure a rule set with two rules that are processed in priority order:

  • Rule 1 – drop-all-malicious-emails This rule has a condition that uses Vade to scan all incoming email and identify messages that are malicious (contain malware or phishing). These messages are then processed by Rule 1’s “Drop action“. Messages that are deemed “safe” are passed to Rule 2 after automatically being inspected and marked as “likely to be spam”, or “not-spam”.
  • Rule 2 – forward-to-mailbox Messages passed into Rule 2 are immediately forwarded to the user’s mailbox. In our example, we’re using Amazon WorkMail and Mail Manager’s built-in “Deliver to mailbox” action.
    • The Vade Add On also distinguishes between spam and clean email, and automatically adds a corresponding header to each message (see below) that can be used to route spam into the user’s “junk” folder.
      • X-SES-Vade-Advanced-Email-Security-AddonVerdict: spam:high
    • Thanks to the seamless integration between Mail Manager Add Ons and WorkMail, messages marked as spam are automatically sent to the user’s Junk folder, enhancing both security and user experience.

Vade Email Add On workflow

Follow the steps below to configure the Vade Email Add On using the Amazon SES console for the simple mail flow described above (note – the SES Mail Manager API can be used in lieu of the console).

  1. Open the Amazon SES console and in the left navigation rail, expand Mail Manager and click Email Add Ons.
  2. Select the Vade Add On, read the description. Click Subscribe and read the Terms and Conditions. Click Subscribe again to activate the Vade Advanced Email Security Add On in your SES account.
    • Pricing is detailed in the Email Add On description page. When this blog was published the price per 1,000 emails processed = $0.415 USD (subject to change, please refer to SES Pricing for the most up to date information).

Vade Email Add On

  1. In the left navigation rail under Mail Manager, click Rule Sets.
  2. Create a new Rule set ( process-via-vade ) (or modify an existing Rule set).
    1. Create a rule ( drop-all-malicious-emails )
    2. Under Rule conditions, click select property and select Vade Advanced Email Security Category from the drop-down menu (note the property modifiers allow for increasingly detailed inspection / results for the scan).
    3. Click the Select operator drop-down and select Equals from the menu.
    4. Click the Value drop-down and select Phishing and Malware.
    5. Under Actions, select Drop action to stop processing and discard messages that are found to be malicious.

Rule 1 - drop-all-malicious-emails

  1. Create rule ( forward-to-mailbox ) to process messages that were passed along by Rule 1.
  2. Under Actions, select Deliver to mailbox (note – if not using Amazon WorkMail, you would select a previously configured SMTPRelay action to send messages to your inbox provider. See this blog for more info).
    1. Provide your WorkMail ARN
    2. Select an IAM role that has permission for SES Mail Manager to access to your WorkMail mailbox

Rule 2 - forward-to-mailbox

  1. Save the Rule set (it will look like this):

New Vade Rule Set

  1. To use this new Rule set, add it to an active Mail Manager Ingress endpoint. When you click save, the Ingress endpoint will begin using the new Rule set immediately.

The Vade Add-On’s rule conditions (below) enable granular control of email routing. When combined with customizable actions, these rules create an automated email handling system that matches your business needs.

VADE result mapping

Conclusion

Hornetsecurity’s Vade Email Add On for Amazon SES Mail Manager represents a significant step forward in email security for Amazon SES Mail Manager customers. By combining an advanced artificial intelligence (AI)-driven security engine with the powerful management capabilities of Mail Manager, you can enhance your defense against email-borne threats while maintaining precise control over your email workflows.

Get started today and take your email security to the next level with the Vade Add On for Amazon SES Mail Manager

We encourage you to try the Vade Add On for Amazon SES Mail Manager and experience the benefits of enhanced email security firsthand. To learn more about implementation details and best practices, please visit:

Join the Conversation:
Connect with other administrators and security professionals on the AWS re:Post community to share insights and learn best practices.

Detecting sensitive data and misconfigurations in AWS and GCP with Cloudflare One

Post Syndicated from Alex Dunbrack original https://blog.cloudflare.com/scan-cloud-dlp-with-casb/

Today is the final day of Security Week 2025, and after a great week of blog posts across a variety of topics, we’re excited to share the latest on Cloudflare’s data security products.

This announcement takes us to Cloudflare’s SASE platform, Cloudflare One, used by enterprise security and IT teams to manage the security of their employees, applications, and third-party tools, all in one place.

Starting today, Cloudflare One users can now use the CASB (Cloud Access Security Broker) product to integrate with and scan Amazon Web Services (AWS) S3 and Google Cloud Storage, for posture- and Data Loss Prevention (DLP)-related security issues. Create a free account to check it out.

Scanning both point-in-time and continuously, users can identify misconfigurations in Identity and Access Management (IAM), bucket, and object settings, and detect sensitive information, like Social Security numbers, credit card numbers, or any other pattern using regex, in cloud storage objects.

Cloud DLP


Over the last few years, our customers — predominantly security and IT teams — have told us about their appreciation for CASB’s simplicity and effectiveness as a SaaS security product. Its number of supported integrations, its ease of setup, and speed in identifying critical issues across popular SaaS platforms, like files shared publicly in Microsoft 365 and exposed sensitive data in Google Workspace, has made it a go-to for many.

However, as we’ve engaged with customers, one thing became clear: the risks of unmonitored or exposed data at-rest go far beyond just SaaS environments. Sensitive information – whether intellectual property, customer data, or personal identifiers – can wreak havoc on an organization’s reputation and its obligations to its customers if it falls into the wrong hands. For many of our customers, the security of data stored in cloud providers like AWS and GCP is even more critical than the security of data in their SaaS tools.

That’s why we’ve extended Cloudflare CASB to include Cloud DLP (Data Loss Prevention) functionality, enabling users to scan objects in Amazon S3 buckets and Google Cloud Storage for sensitive data matches​.


With Cloudflare DLP, you can choose from pre-built detection profiles that look for common data types (such as Social Security Numbers or credit card numbers) or create your own custom profiles using regular expressions​. As soon as an object matching a DLP profile is detected, you can dive into the details, understanding the file’s context, seeing who owns it, and more. These capabilities provide the insight needed to quickly protect data and prevent exposure in real time.


And as with all CASB integrations, this new functionality also comes with posture management features, meaning whether you’re using AWS or GCP, we’ll help you identify misconfigurations and other cloud security issues that could leave your data vulnerable​, like buckets that are publicly-accessible or have critical logging settings disabled, access keys needing rotation, or users without multi-factor authentication (MFA). It’s all included.

Simple by default, configurable where you want it

Cloudflare CASB and DLP are simple to use by default, making it easy to get started right away. But it’s also highly configurable, giving you the flexibility to fine-tune the scanning profiles to suit your specific needs.


For example, you can adjust which storage buckets or file types to scan, and even sample only a percentage of objects for analysis​. The scanning also runs within your own cloud environment, so your data never leaves your infrastructure​. This approach keeps your cloud storage secure and your costs managed while allowing you to tailor the solution to your organization’s unique compliance and security requirements.

Looking ahead, our roadmap also includes expanding support to additional cloud storage environments, such as Azure Blob Storage and Cloudflare R2, further extending our comprehensive, multi-cloud security strategy. Stay tuned for more on that!

How it works

From the start, we knew that to deliver DLP capabilities across cloud environments, it would require an efficient and scalable design to enable real-time detection of sensitive data exposure.

Serverless architecture for streamlined processing

An early design decision was made to leverage a serverless architecture approach to ensure sensitive data discovery is both efficient and scalable. Here’s how it works:

  • Compute Account: The entire process runs within a cloud account owned by your organization, known as a Compute Account. This design ensures your data remains within your boundaries, avoiding costly cloud egress fees. The Compute Account can be launched in under 15 minutes using a provided Terraform template.

  • Controller function: Every minute, a lightweight, serverless controller function in your cloud environment communicates with Cloudflare’s APIs, fetching the latest DLP configurations and security profiles from your Cloudflare One account.

  • Crawler process: The controller triggers an object discovery task, which is processed by a second serverless function known as the Crawler. The Crawler queries cloud storage accounts, like AWS S3 or Google Cloud Storage, via API to identify new objects. Redis is used within the Compute Account to track which objects have yet to be evaluated.

  • Scanning for sensitive data: Newly discovered objects are sent through a queue to a third serverless function called the Scanner. This function downloads the objects and streams their contents to the DLP engine in the Compute Account, which scans for matches against predefined or custom DLP Profiles.

  • Finding generation and alerts: If a DLP match is found, metadata about the object, such as context and ownership details, is published to a queue. This data is ingested by a Cloudflare-hosted service and presented in the Cloudflare Dashboard as findings, giving security teams the visibility needed to take swift action.

Scalable and secure design

The DLP pipeline ensures that sensitive data never leaves your cloud environment — a privacy-first approach. All communication between the Compute Account and Cloudflare’s APIs are initiated by the controller, also meaning there is no need to perform any extra configuration to allow ingress traffic.

How to get started

To get started, reach out to your account team to learn more about this new data security functionality and our roadmap. If you want to try this out on your own, you can login to the Cloudflare One dashboard (create a free account here if you don’t have one) and navigate to the CASB page to set up your first integration.

Watch on Cloudflare TV

Enable single-sign-on for Amazon WorkMail with IAM Identity Center and Okta Universal Directory

Post Syndicated from Zip Zieper original https://aws.amazon.com/blogs/messaging-and-targeting/enable-single-sign-on-for-amazon-workmail-with-iam-identity-center-and-okta-universal-directory/

Securing your business email is more critical than ever in today’s digital workplace. To help you protect your users and data in Amazon WorkMail (WorkMail), we regularly introduce security features that give organizations more control and protection for their business email. Thanks to the recently announced integration between WorkMail and AWS Identity and Access Management (IAM) Identity Center (IAM IdC), WorkMail users can now enjoy single sign-on (SSO) via compatible 3rd party external identity providers including Okta Universal Directory (Okta), Microsoft Entra ID, Google Workspace, JumpCloud, OneLogin, Ping Identity products and Active Directory.

This blog post explains the specific steps needed to integrate WorkMail with Okta via IAM IdC. WorkMail customers who use other 3rd party identity providers that are compatible with IdC will also find this post useful alongside the AWS documentation for their specific identity source. Alternatively, WorkMail organization administrators who do not use an external identity provider, but wish to enable multi-factor-authentication (MFA) for WorkMail viaIAM IdC will find guidance in a different blog post.

By integrating WorkMail with Okta via IAM IdC, users benefit from the security, convenience, and familiarity of SSO when accessing their WorkMail inbox and calendars via the WorkMail web-app. WorkMail organization administrators benefit from the security and efficiency of managing WorkMail user additions, modifications, or removals via the Okta admin tools. More detailed information about this integration can be found in the IAM IdC documentation as well as in the WorkMail documentation.

Introduction

Email remains a critical business communication tool, yet it is also one of the most targeted entry points for cyber threats. A single compromised email account can expose sensitive business data, damage an organization’s reputation, and serve as a gateway for further cyber attacks. As traditional username and password authentication becomes increasingly inadequate, organizations must adopt stronger access controls to protect their users and communications.

You can enhance your WorkMail organization’s security and simplify user authentication with SSO and a familiar login experience by integrating WorkMail with IAM IdC and Okta. This (and similar) integrations provide a more seamless authentication experience and helps administrators enforce consistent security policies across their organization.
The integration between WorkMail, IAM IdC and Okta supports these industry standards:

WorkMail authentication options

When you first set up WorkMail, you use the built-in user directory which relies upon standard username | password authentication for the WorkMail web browser client as well as popular desktop and mobile email clients such as Microsoft Outlook, Apple Mail and Thunderbird.

WorkMail standard username/password

By default, WorkMail uses username | password authentication

The integration between IAM Identity Center and Okta uses the SCIM protocol to provision and map user attributes in Okta to named attributes in IAM IdC. Once enabled, user and group information from Okta is automatically synchronized with IAM IdC. IAM IdC in turn uses the SAML protocol to provide Okta users with a familiar and convenient SSO experience.

After integrating IAM IdC with Okta, WorkMail uses:

  1. Okta SSO for users of the WorkMail web-app.
  2. Personal access tokens (PAT) for users of desktop &/or mobile email applications.
WorkMail uses Okta SSO or PATs

After integration with IdC and Okta, WorkMail uses SSO (web-app) and username | PAT (desktop/mobile) for authentication

Prerequisites for the WorkMail, IAM IdC and Okta integration

  • Admin access to an AWS account
    • You can evaluate the integration in this post for a limited period of time using an AWS Free Tier Account
  • Admin access to an Amazon WorkMail Organization
    • The integration uses the email domain that is configured as WorkMail’s default
  • Admin access to Amazon IAM Identity Center
    • Or admin access to the IdC organization account
  • Your WorkMail and IAM Identity Center must be in the same AWS region
  • IAM Role with the security credentials needed to deploy AWS infrastructure via the AWS CDK
  • Administrator access to a fully functional Okta Identity account populated with users and (optionally) group(s) that you want to integrate and synchronize with IAM IdC and WorkMail.
  • Access to the AWS Samples GitHub repository, where you’ll find sample code that deploys via AWS CDK. This code sample deploys a customizable AWS Lambda initially configured to perform user synchronization between IAM IdC and WorkMail every 15 minutes.
  • A source code editor such as Visual Studio Code with your AWS admin credentials.

High-level Steps

  1. Configure Identity Center (See our documentation for detailed information).
  2. Configure Okta Identity integration with IAM Identity Center. See this post for more information
  3. Provision and synchronize Okta’s Groups (or Okta Users) with IAM Identity Center
  4. Configure WorkMail to use Identity Center
  5. Deploy the AWS CDK sample project found in aws-samples in GitHub
  6. Test user access to WorkMail with and without Okta SSO (web-app) and Personal Access Token (desktop & mobile email clients)
  7. Notify WorkMail users of upcoming changes to login procedures.
  8. Switch WorkMail Authentication Mode to IAM IdC.

Detailed Configuration Guidance

The instructions that follow walk you through the steps needed to integrate your Okta system with IAM IdC. Once IAM IdC is synchronizing with Okta, you’ll integrate IAM IdC with WorkMail. This process will keep your WorkMail organization’s users and groups synchronized with Okta. Once fully enabled, your WorkMail users will use their Otka SSO credentials to access the WorkMail web-client or a username and unique Personal Access Tokens to access desktop &/or mobile email clients. Let’s get started!

Configure Okta integration with IAM Identity Center (these steps have been adapted from this blog post)

    1. Open the Okta admin landing page in a new browser (tab).

Okta admin landing page

    1. Click the Applications Section in the left menu.
    2. Click on Applications in the dropdown menu.
    3. Click Browse App Catalog.

Applications page.

    1. Type AWS IAM Identity Center in the search box.
    2. Click on the app that matches AWS IAM Identity Center.

AWS IAM Identity Center

    1. Click Add Integration to initiate the integration process.

Add Integration button

    1. Type a memorable name (like Workshop AWS IAM Identity Center) for the application label, and click Done.

Application Labe

    1. Click on the Sign On tab, scroll down to view SAML Signing Certificates.

    1. Click Actions to download the certificate to your local machine. Keep the Okta Admin dashboard Open, you will need the SAML information found here to configure IdC in the next section.

Configure AWS IAM IdC

  1. In a new browser window (or tab), open the IAM IdC console in the same region as your WorkMail Organization (we’re using us-east-1).
  2. If this is your first time accessing IAM IdC, you’ll be greeted with the IdC console home page prompting you to “Enable IAM Identity Center”. Click Enable.

Enable IAM Identity Center

  1. Check that you are in the correct region, click Enable (note – this will enable an Organization instance of IdC, which is recommended. If you want to use an Account instance of IdC, please see the documentation).

enable an Organization instance of IdC

  1. Once IdC has been enabled, scroll down to the IAM Identity Center setup section and click Confirm Identity Source.

  1. Click Actions, and select Change identity source from dropdown menu.

Change identity source

  1. Select External identity provider and click Next.

External identity provider

  1. Upload the SAML certificate you downloaded from Okta (above, step xx)
  2. Open the Okta dashboard browser/tab. Under the SAML 2.0 configuration, scroll down and expand > More details.
    • Copy the Sign on URL from Okta SAML and paste the URL into the IdP sign-in URL field in IdC.
    • Copy the Issuer URL from Okta SAML and paste the URL into the IdP sign-in URL field in IdC.
    • Click Next.
  1. Type ACCEPT in the confirmation text box & click Change identity source.

Change identity source

  1. Switch back to the IAM IdC console browser window/tab. On the Settings page, locate the Automatic provisioning information box, and then choose Enable. Leave this browser window/tab open as you’ll need it to copy the values for the SCIM endpoint and Access token into Okta shortly (note – IdC Automatic provisioning uses SCIM protocol to provision users from Okta).

IdC Automatic provisioning

  1. Return to the Okta admin dashboard (you should have left it open in another browser window or tab). Under IAM Identity Center applications, select the Workshop AWS IAM Identity Center and open the Provisioning tab.
  2. Under Integration, click Configure API Integration.

Configure API Integration

  1. Select the checkbox next to Enable API integration to enable provisioning.
  2. Refer to the IAM IcC console browser window/tab you left open and copy (from IdC) and paste (into Okta) the values for:
    • Base URL field – paste the IdC SCIM endpoint value (make sure there is no trailing forward slash at the end of the URL).
    • API Token field, enter the Access token value.
    • Import Groups should be checked
  1. Click Test API Credentials to verify the credentials entered are valid (the message AWS IAM Identity Center was verified successfully! should appear).

AWS IAM Identity Center was verified successfully

  1. Save.
  2. Under Settings, choose To App, click Edit and select Enable for Create Users, Update User Attributes and Deactivate Users. Click Save.

Update User Attributes and Deactivate Users

  1. In the Okta admin dashboard’s left-hand menu pane, click on Directory.
    • Choose Groups to see the list of existing groups.
    • Click on the Add Group button to create a new group called workmail_users.
    • Fill in the required details for the new group, including:
      • Group Name: Enter workmail_users for the group.
      • Group Description (optional): Provide a description for the group’s purpose (WorkMail_users).
    • Save the New Group
    • Reload the page to see the newly created group
    • Click Assign people
    • Add Okta users to the workmail_users group
    • Click Save
  1. In the Okta admin dashboard’s left-hand menu pane, click on Applications and open the AWS IAM Identity Center application.
  2. Click the Assignments tab, choose Assign, then choose Assign to people.
  3. Choose the Okta users that you want to have access to WorkMail via IAM Identity Center app.
  4. For each user, click Assign, review the user info, and click Save then Go Back
  5. When all Okta users for whom you want WorkMail users created/synced have been assigned, click Done to start the process of provisioning the users into IAM Identity Center.

provisioning the users into IAM Identity Center

  1. On the Assignments page, choose Assign, and then choose Assign to groups.
  2. Click the Okta group (workmail_users) that you want to have access to WorkMail via IAM Identity Center.
  3. Click Assign, review the selections, click Save and Go Back. Click Done. This starts the process of provisioning the users in the workmail_users group into IAM Identity Center.
  4. Choose the Push Groups tab.
  5. Choose the workmail_users group that contains all the users that you assigned to the IAM Identity Center app.
  6. If the group is not found in the list, choose the Find groups by name option by clicking (+)Push Groups Menu.
  7. Enter the group name ( workmail_users) that you created in the previous step and select it from the search results
  8. Click Save. The group status changes to “pushing” then “Active” (this can take several minutes), once the Okta workmail_users group and all its members have been pushed to IAM Identity Center.
  9. Return to the browser window/tab with the IAM Identity Center console.
  10. In the left navigation, select Groups (or Users) (you should see the Group (or users) list that was just populated by the Okta “push” action).

elect Groups (or Users)

Enable IAM Identity Center in Amazon WorkMail

  1. Open a new browser window (tab) to the WorkMail console in the same region as IdC, and open your WorkMail Organization.
  2. In WorkMail’s left navigation rail click Identity Center
  3. Click on Multi-factor authentication setup guide, Click Enable Identity Center, read the default configuration notice ,and click Enable

Enable Identity Center

  1. Under Identity Center Settings, click the Authentication mode tab and ensure it is set for WorkMail directory and Identity center (this is the default).
  2. This mode is needed for testing and to allow desktop & mobile email client users to retrieve their unique personal access tokens.
  3. Once the integration with IdC is successfully tested, and those WorkMail users who rely on desktop or mobile email clients for access have had the opportunity to login to the WorkMail web app to retrieve a PAT, you will change the Authentication mode to Identity center only.

Deploy the sample solution from GitHub

Solution prerequisites:

– AWS Account
– AWS IAM user with Administrator permissions
– Python (> v3.x) and Pip fully installed and configured on your computer
– AWS CLI (v2) installed and configured on your computer
– AWS CDK (v2) installed and configured on your computer
– Sample CDK project that creates and deploys an AWS Lambda in your AWS account to perform users synchronization between IAM IdC and WorkMail.

The instructions that follow guide you in deploying a sample solution for the AWS Samples Serverless-Mail repository that programmatically creates/syncs WorkMail users from IAM Identity Center using the AWS CDK CLI. The sample uses naming conventions used in this blog. For example, the Lambda only syncs those users found in the IdC Group named "workmail_users". If your IdC group has a different name, or you want to sync multiple IdC groups with WorkMail, you will need to modify the sample code before proceeding. (BE AWARE: The sample code base is an Open Source starter project designed to provide a demonstration and a base to start from for specific use cases. It should not be considered fully Production-ready, nor should it be deployed in a production environment. Refer to the README.md and License.md for more information.)

  1. Clone the sample project to your computer (git clone https://github.com/aws-samples/serverless-mail/tree/main/idc_okta-workmail). CD into the ‘idc_okta-workmail‘ directory.
  2. Create a virtual environment for packaging in Python (Docker must already be running locally) with python3 -m venv .venv
  3. Activate the virtual environment with source .venv/bin/activate
  4. Make sure cdk.json references the correct path to Python (by default cdk.json refers to .venv/bin/python app.py). If you need to locate Python, run the which python command.
  5. Install the project dependencies with pip3 install -r requirements.txt
  6. Check the AWS CLI local credentials and region with aws sts get-caller-identity . If you need to change any parameter, run aws configure
  7. Prepare the `app.py` file by running python3 get-my-variables.py  . The ‘get-my-variables.py’ script fetches the necessary variables from your AWS account and create the `app.py` file needed by the CDK. You may want to review the auto-generated `app.py` file for accuracy, especially if the AWS account has been used for other IdC or WorkMail related projects. The app.py file requires the following account variables:
    • AWS accountId
    • AWS Region – the region must be the same for IdC and WorkMail.
    • IDENTITYSTORE_ID – – found in the Identity Center console under settings or via the AWS CLI aws identitystore list-groups --identity-store-id {identity_store_id}
    • IDENTITY_CENTER_INSTANCE_ARN – found in the Identity Center console under settings or via the AWS CLI aws sso-admin list-instances
    • IDENTITY_CENTER_APPLICATION_ARN – found in the Identity Center console under Applications or via the AWS CLI aws sso-admin list-applications --instance-arn {instance_arn}`
    • WORKMAIL_ORGANIZATION_ID – found in the WorkMail console under Organizations or via the AWS CLI aws workmail list-organizations
    • OKTA_GROUP_ID_TO_ASSIGN_TO_WORKMAIL – found in the Identity Center console under Groups > General Information or via the AWS CLI aws identitystore list-groups --identity-store-id {identity_store_id}
  8. Bootstrap the package (this step may take several minutes to complete) with cdk bootstrap
  9. Synthesize the package (this step may take several minutes to complete) with cdk synthesize
  10. Deploy your package (this step may take several minutes to complete) with cdk deploy and follow the prompts in the AWS CDK CLI.
  11. Once deployment to your AWS account starts, you can view the deployment status in the CloudFormation console.

Confirm WorkMail Authentication mode

WorkMail’s default Authentication mode should be set to WorkMail directory and Identity center. Don’t change this yet. This mode will allow WorkMail web-app users to continue to login to the WorkMail client directly, without Okta SSO. WorkMail’s Personal access token configuration default is set to active, and token lifespan set to 365 days. You can change this if your security needs differ from the default. PATs are used by desktop and mobile email clients to login to WorkMail. Leaving WorkMail’s default Authentication mode set to WorkMail directory allows desktop and mobile email clients to continue to login to the WorkMail with their username and password, without yet requiring a PAT instead of password.

Conduct a few spot tests to verify WorkMail web-app users can properly access their WorkMail accounts via:

  1. The Amazon WorkMail web application URL (found on the WorkMail organization page)

Webmail login link

  1. Your organization’s unique AWS access portal URL (found on the setting page of the IAM IdC dashboard).

  1. This will open a new browser tab that redirects to the Okta user login page.

Okta user login page

  1. Once user has authenticated, this page will redirect to the AWS access portal with linked application tiles to all of the AWS applications that have been integrated with IAM Identity Center.

AWS access portal with linked application tiles

  1. Click on the WorkMail logo, and the WorkMail web-app will load.

WorkMail web-app

  1. Desktop or mobile email software users need to create a WorkMail Personal Access Token (PAT) to access WorkMail. These users must retrieve their own PATs after logging into the WorkMail web-client. Open the Webmail login link found on the WorkMail Organization page under User Login

Webmail login link

  1. In the WorkMail web-app,
    1. click the settings gear (in top right)
    2. Click Personal Access token and enter a token name (i.e. desktop-thunderbird-pat)
    3. Click Create token.
    4. Click Create token.
    5. Copy the token value (this is the only time you can retrieve this token value).
  2. Open your desktop or mobile email software, enter your username and your PAT (the PAT replaces your existing user password).

WorkMail web-app

  1. In settings, click Personal Access token and Create token
  2. Enter a token name (typically the device on which you’ll use this PAT) and select create token.
  3. Copy the token value (this is the only time you can retrieve this token value).
  4. Open your desktop or mobile email software, enter your username and your PAT (the PAT replaces your existing user password), and test your new login (username | PAT).

enter your username and your PAT

Notify your WorkMail users of upcoming changes to login procedures

Once you have tested the integration between WorkMail and IAM Identity Center with a few test users, you should prepare your WorkMail users for the increased login security. For example, you could send them an email that explains:

  • The organization is adding an additional login security step to help protect their inboxes.
  • Inform them that they should anticipate an email from the AWS IAM Identity Center with info about the upcoming implementation of MFA for web-app users and PATs for desktop and mobile client users.
  • Users should accept the invitation and create a new password for the AWS IAM Identity Center.
  • Inform them that once WorkMail MFA is enabled, all WorkMail web-app users will be required to use their username, password and MFA.
  • Inform them that once WorkMail PATs are enabled, all WorkMail desktop and mobile email client users will need to login to the WorkMail web client (with MFA) via the AWS access portal URL, create one PAT per software client (the same PAT can not be used on desktop and mobile). They then must update their desktop or mobile email software to use their username and PAT, instead of their current password. Explain that the PAT is now their email client application password and their personal desktop or mobile email software passwords will no longer work.
  • Provide users with a way to request support.

Switch WorkMail Authentication Mode to Identity Center only

  1. Once you are satisfied that your WorkMail users have incorporated Okta SSO and/or PATs into their WorkMail login routines, the WorkMail administrator should disable the WorkMail directory Authentication mode found in the WorkMail console under Organization > Identity Center.

disable the WorkMail directory Authentication mode

  1. Optional – Ask several trusted users to test their ability to login to WorkMail web app via Okta credentials.

Congratulations, your WorkMail organization’s authentication is now being managed by IAM Identity Center and your external identity provider, Okta.

Conclusion

By integrating IAM Identity Center with Okta Identity and WorkMail, you can provide your users with the convenience of Okta SSO for the WorkMail web-app. This allows your organization to improve it’s email security posture, better safeguard sensitive communications and protect you WorkMail organization against unauthorized access. Furthermore, this integration reduces admin overhead as user access to WorkMail is allowed, or revoked via the Okta administration dashboard.

Take control of your email communications today with Amazon WorkMail:

  1. Visit the WorkMail Console to begin configuration.
  2. Enable IAM Identity Center Integration with Okta and WorkMail.
  3. Connect your WorkMail organization to centralized access management.
  4. Configure WorkMail to require:
    1. Okta SSO – Adds an extra layer of security for web-app users.
    2. Personal Access Tokens (PAT) – Add an extra layer of security for desktop and mobile client access.

Need guidance? Check out our technical documentation. Contact your AWS account team.

To help keep your WorkMail organization secure, we recommend:

  • Regularly reviewing your WorkMail audit logs for unexpected activity.
  • Monitoring for unauthorized access attempts.
  • Staying informed about the latest security practices.

Dive deeper into WorkMail security with these resources:

Join the Conversation:
Connect with other administrators and security professionals on the AWS re:Post community to share insights and learn best practices.

Visually build telephony applications with AWS Step Functions

Post Syndicated from Reynaldo Hidalgo original https://aws.amazon.com/blogs/messaging-and-targeting/visually-build-telephony-applications-with-aws-step-functions/

Developers face numerous challenges when building telephony applications: managing unpredictable user responses, handling disconnections, processing incorrect inputs, and addressing errors. These challenges extend development cycles and create unstable applications that fail to meet user expectations.

This blog demonstrates how Amazon Web Services (AWS) Step Functions, combined with Amazon Chime SDK Public Switched Telephone Network (PSTN) audio service, offers a solution to overcome these challenges.

Overview of the solution

To demonstrate our solution, we built a sample telephony application that lets business owners manage customer calls through a dedicated business phone number. This solution helps small business owners separate personal and business communications, while managing all calls from their existing phone.

The beta version of this sample application delivers these six core call flows:

  1. During business hours: Routes incoming customer calls to the business owner
  2. After hours: Enables customers to leave voice messages
  3. Message retrieval: Allows owner to access customer voice messages
  4. Business caller ID: Enables owner to call customers using the business number
  5. Call scheduling: Permits owner to schedule customer calls for later in the day
  6. Automated calling: Initiates scheduled calls between owner and customer automatically

Using Workflow Studio, we built a Step Functions workflow (Figure 1) that processes all six call flows and handles unexpected scenarios.

Figure 1 – Visual diagram of a telephony workflow created in Workflow Studio for Step Functions, showing six interconnected call routing paths with decision points and error handling states. Each path represents a different customer interaction scenario, connected by arrows indicating the flow direction.

Figure 1 – Step Functions telephony workflow designed in Workflow Studio

How it works

AWS Step Functions enable agile visual workflow design, through pre-built components and error handling rules. This creates workflows composed of event-driven states that input, process, and output JavaScript Object Notation (JSON)-formatted messages. The PSTN audio service streamlines telephony applications through its serverless approach using a request/response programming model. It invokes AWS Lambda functions with Events and waits for Actions responses, both in predefined JSON formats. This shared JSON format enables seamless integration between the PSTN audio service and Step Functions, leading us to design a serverless architecture (Figure 2) that allows for bidirectional JSON message exchange between the two services.

Figure 2 – Architectural diagram showing the integration flow between AWS Step Functions and PSTN audio service. Arrows indicate JSON message exchange between services, with Lambda functions handling the communication. The diagram illustrates the serverless architecture components and their connections in a top-to-bottom layout.

Figure 2 – Serverless architecture for Step Functions and PSTN audio service integration

Main components:

  • eventRouter: Lambda function managing JSON message exchange
  • appWorkflow: Step Functions implementing call flow logic
  • actionsQueue: Amazon Simple Queue Service (Amazon SQS) queue storing response actions

Architecture flow:

  1. PSTN audio service receives inbound call
  2. Service sends NEW_INBOUND_CALL event to eventRouter
  3. eventRouter creates the actionsQueue
  4. eventRouter asynchronously executes appWorkflow with event data
  5. eventRouter begins long-polling from actionsQueue, waiting for next action(s) message
  6. appWorkflow processes JSON-formatted event data, computing next action(s)
  7. appWorkflow queues next action(s) using Amazon SQS SendMessage API with Wait for Callback with Task Token integration pattern to stop the workflow until the next event call is received
  8. eventRouter retrieves and removes action(s) from actionsQueue
  9. eventRouter returns action(s) to PSTN audio service

Observations:

  • eventRouter code logic is generic and agnostic from the calls and different Step Function workflows
  • eventRouter queries an environment variable to determine the workflow to call
  • Pairs of actionsQueue and appWorkflow instances lives for the duration of each call
  • eventRouter is responsible for the creation and deletion of each actionsQueue
  • appWorkflow instances are created by the eventRouter at the start of each call
  • appWorkflow instances complete its execution when all parties involved on the call hang up

Building your telephony application

Prerequisites:

Implementation Guidelines:

  • Create dedicated Step Functions workflows for each telephony application
  • Design and implement workflows using Workflow Studio
  • Use a Standard workflow type to accommodate extended call durations
  • Update the eventRouter Lambda function’s “CallFlowsDIDMap” environment variable to map phone numbers to their workflow Amazon Resource Name (ARN)
  • Set workflow variables in the “Init” state Variables tab (Figure 3). The eventRouter function automatically sets “QueueUrl”, and adding other variables here removes the need for external storage
Figure 3 – Screenshot of Workflow Studio's Variables tab showing an editable text box for JSON data entry. The interface displays a code editor with syntax highlighting for entering variable names and their values that persist throughout the workflow execution.

Figure 3 – Step Functions “Init” state Variables tab showing workflow data configuration

  • Configure Choice state rules to route calls based on conditions. Rules one through three (Figure 4) handle call routing based on inbound/outbound direction, owner/customer identification, while the default rule manages unexpected scenarios.
Figure 4 – Screenshot of Workflow Studio's Choice state configuration panel. The interface shows a rules editor where multiple condition blocks are displayed. Each block contains dropdown menus and input fields for setting call routing logic based on variable values. The rules appear in a vertical list with options to add, edit, or remove conditions.

Figure 4 – Step Functions Choice state defines rules for call routing decisions

  • Configure the SQS: SendMessage state (Figure 5) to instruct the next action to the PSTN audio service by:
    • Formatting the message content to match supported actions for the PSTN audio service
    • Setting TransactionAttributes to pass back and forth the values of the “WaitToken” and “QueueUrl” throughout the call duration
    • Enabling the Wait for Callback with a Task Token integration pattern
Figure 5 – Screenshot of the SQS: SendMessage state configuration in Step Functions Workflow Studio. The interface shows three main concepts: a message content formatter for PSTN audio service actions, transaction attribute fields for the WaitToken and QueueUrl values, and callback integration pattern settings. The message content input section displays input fields and options for setting up the message structure that enables communication between Step Functions and the PSTN audio service.

Figure 5 – SQS: SendMessage state configuration for PSTN audio service callback integration

  • Leverage AWS service integration states to interact with other AWS services directly from the workflow.
    • Example: Use a DynamoDB PutItem state (Figure 6) to store Amazon Simple Storage Service (Amazon S3) recording files, including bucket name and key, in Amazon DynamoDB.
Figure 6 – Screenshot of Step Functions Workflow Studio showing a DynamoDB PutItem state configuration. The interface displays fields for setting up direct interaction with DynamoDB to store S3 recording file information. The configuration panel includes input parameters for the DynamoDB table, item details, and S3 bucket and key values.

Figure 6 – AWS service integration states enable direct service connections without custom code

  • Utilize JSONata expressions (Figure 7) to minimize the number of Lambda functions.
    • Example: For Amazon EventBridge scheduling, compute time expressions using JSONata functions [$fromMillis(), $millis(), number()] and string concatenation to handle customer call scheduling.
Figure 7 – Screenshot of Step Functions Workflow Studio showing JSONata expression configuration. The interface displays a code editor with syntax highlighting where time calculation expressions are written using JSONata functions like $fromMillis(), $millis(), and number(). The panel demonstrates how to transform data directly within the workflow, eliminating the need for separate Lambda functions. Example expressions show date and time calculations for EventBridge scheduling.

Figure 7 – JSONata expressions for direct data transformation without Lambda functions

  • Use Step Functions error handling with success and fail states (Figure 8) to manage error paths and call termination results.
Figure 8 – Screenshot of Step Functions Workflow Studio showing the error handling configuration interface. The panel displays multiple state configurations: error catching paths for failed calls, success state definitions for completed calls, and termination handling settings. The interface includes dropdown menus and input fields for defining error types, retry attempts, and fallback actions. Visual connections between states illustrate the error handling flow from detection through resolution.

Figure 8 – Call error handling and termination setup

Key benefits

This approach for building telephony applications offers multiple advantages:

  1. Visual workflow-based designer
  2. Self-document call flow logic
  3. Managed versioning and publishing
  4. Native integration with AWS Services
  5. Visual log and inspection for each call
  6. Auto-scalable
  7. Pay-per-use pricing

Deploying the solution

 The following steps allows you to deploy the sample telephony application together with the serverless architecture (Figure 2).

 Prerequisites:

  1. AWS Management Console access
  2. Node.js and npm installed
  3. AWS Command Line Interface (AWS CLI) installed and configured

 Walkthrough:

The Cloud Development Kit (CDK) project on the AWS GitHub repository will deploy the following resources:

  • phoneNumberBusiness – Provisioned phone number for the sample application
  • sipMediaApp – SIP media application that routes calls to lambdaProcessPSTNAudioServiceCalls
  • sipRule – SIP rule that directs calls from phoneNumberBusiness to sipMediaApp.
  • stepfunctionBusinessProxyWorkflow – Step Functions workflow for the sample application
  • roleStepfuntionBusinessProxyWorkflow – IAM Role for stepfunctionBusinessProxyWorkflow
  • lambdaProcessPSTNAudioServiceCalls – Lambda function for call processing
  • roleLambdaProcessPSTNAudioServiceCalls – IAM Role for lambdaProcessPSTNAudioServiceCalls
  • dynamoDBTableBusinessVoicemails – DynamoDB table to store customer voicemails
  • s3BucketApp –S3 bucket for storing system recordings and customer voicemails
  • s3BucketPolicy – IAM Policy granting PSTN audio service access to s3BucketApp
  • lambdaOutboundCall – Lambda function for placing scheduled customer calls
  • roleLambdaOutboundCall – IAM Role for lambdaOutboundCall
  • roleEventBridgeLambdaCall – IAM Role to allow the EventBridge service to execute lambdaOutboundCall

Follow these steps to deploy the CDK stack:

  1. Clone the repository
git clone https://github.com/aws-samples/amazon-chime-sdk-visual-media-applications 

cd amazon-chime-sdk-visual-media-applications 

npm install
  1. Bootstrap the stack
#default AWS CLI credentials are used, otherwise use the –-profile parameter
#provide the <account-id> and <region> to deploy this stack 
cdk bootstrap aws://<account-id>/<region>
  1. Deploy the stack
#default AWS CLI credentials are used, otherwise use the –-profile parameter
#personalNumber: the personal phone number of the business owner in E.164 format 
#businessAreaCode: the United States area code used to provision the business number 
cdk deploy –-context personalNumber=+1NPAXXXXXXX –-context businessAreaCode=NPA

Call the provisioned phone number to test the sample application. Optionally, edit the workflow to update the business name and working hours on the “Init” Task state, in the Variables tab.

Cleaning up:

To clean up this demo, execute:

cdk destroy

Conclusion

This blog demonstrates how combining AWS Step Functions and Amazon Chime SDK PSTN audio service streamlines the development of reliable telephony applications through visual workflow design and managed error handling. We provided a sample application, implementing six core business phone features, showcasing how the solution effectively manages multiple conditional paths and edge cases like disconnections and invalid inputs.

The serverless architecture created enables seamless integration between the two services through JSON-based communication, while providing automatic scaling and pay-per-use pricing. Together, these components create a robust foundation for building sophisticated telephony applications that reduce maintenance costs and enhance reliability.

Contact an AWS Representative to know how we can help accelerate your business.

How to Register a Sender ID Using APIs with AWS End User Messaging

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-register-a-sender-id-using-apis-with-aws-end-user-messaging/

Introduction

Welcome to our comprehensive guide on using the AWS End User Messaging V2 APIs to obtain a Sender ID in countries that require registration. Sender ID registration is a crucial step for businesses looking to establish a trusted communication channel with their customers via SMS. In countries such as Jordan, the Philippines, Qatar, and others registering a Sender ID is mandatory to ensure compliance with local regulations and to enhance message deliverability. You can view a list of countries that support Sender ID and require registration here.

NOTE: This post is specific to Sender IDs, to learn more about choosing the right originator for your use case read this post on How to Send SMS Globally Using AWS End User Messaging.

This guide will walk you through the high-level process of creating and submitting a Sender ID registration using AWS End User Messaging V2 APIs. While we will use Jordan as a case study in this post, the principles and steps outlined here apply to other countries with similar registration requirements for Sender ID.

High-Level Understanding of the Registration APIs

To successfully register a Sender ID, you’ll need to interact with several AWS End User Messaging APIs. Here’s a brief overview of the key APIs involved and their roles in the registration process:

1. DescribeRegistrationTypeDefinitions

  • Purpose: Retrieves the specified registration type definitions.
  • Use Case: View the requirements for creating, filling out, and submitting each registration type.
  • Key Point: Each country has a specific “RegistrationType” that needs to be used in the next step to create a registration.
  • Documentation: DescribeRegistrationTypeDefinitions

2. CreateRegistration

  • Purpose: Creates a new registration “container”. This is an empty registration that we are going to fill with our data in later steps.
  • Key Field: RegistrationType
    • Controls the type of registration (e.g., Toll-Free, 10DLC, JO_SENDER_ID_REGISTRATION, etc.).
  • Documentation: CreateRegistration

3. DescribeRegistrationFieldDefinitions

  • Purpose: Retrieves the specified RegistrationType field definitions.
  • Use Case: View the requirements for creating, filling out, and submitting each registration type. There are different field types (SELECT, TEXT, ATTACHMENT) dependent on the type of data required to register as well as the actual questions that need to be answered.
  • Documentation: DescribeRegistrationFieldDefinitions

4. CreateRegistrationAttachment

  • Purpose: Uploads additional documentation that some countries require. Not all countries require documentation that needs to be uploaded so this may be an optional step depending on the country you are registering for. We will be registering for Jordan in this example which does require us to upload a document to complete the registration.
  • Key Field: RegistrationAttachmentId
    • Used in the next action to include an attachment in the registration when you are required to provide one. Not all registration types require an attachment.
  • File Specifications:
    • Maximum file size: 500kb
    • Valid file extensions: PDF, JPEG, or PNG
  • Documentation: CreateRegistrationAttachment

5. PutRegistrationFieldValue

  • Purpose: Sets the value for a specific registration field.
    • This action needs to be repeated for all required fields.
  • Documentation: PutRegistrationFieldValue

6. SubmitRegistrationVersion

  • Purpose: Submits the specified registration version for review and approval. You are able to create new versions of the registration using CreateRegistrationVersion so make sure if you created another Registration Version that you use the correct ID.
  • Important Notes:
    • Ensure that you are using the correct Version if you created multiple
    • Ensure all data is correct before submission.
    • Initial status will be “CREATED” and should change to “REVIEWING” within 24 hours.
    • You cannot edit or delete the registration until it is approved or rejected.
  • Documentation: SubmitRegistrationVersion

Detailed Steps for Sender ID Registration in Jordan

In the following sections, we’ll dive deeper into each of these steps, providing more detail on the API calls and responses as well as best practices to ensure a smooth registration process. Whether you’re registering in Jordan or another country with similar requirements, this guide will equip you with the knowledge you need to successfully register a Sender ID.

Step 1: DescribeRegistrationTypeDefinitions

The first step is to run DescribeRegistrationTypeDefinitions to retrieve all specified registration type definitions. This API provides a detailed response that includes various attributes related to the registration process. Let’s break down these attributes for Jordan:

  • Country: JO
    • Description: Specifies the country code for which the registration type definitions are being described. JO stands for Jordan.
    • Implication: Understanding the country code is crucial because registration requirements and processes can vary significantly from one country to another.
  • ResourceType: SENDER_ID
    • Description: Indicates the type of resource for which the registration is being defined.
    • Implication: Knowing that the resource type is SENDER_ID helps you understand that the registration process is focused on obtaining approval specifically for a Sender ID as there are some countries that have multiple registration types.
  • Registration Type: JO_SENDER_ID_REGISTRATION
    • Description: Specifies the exact type of registration required for the given country and resource type.
    • Implication: This registration type is critical because it dictates the specific steps, documentation, and criteria you need to meet to successfully register a Sender ID in Jordan.
    • You will use this value to create the initial registration
  • Association Behavior: ASSOCIATE_ON_APPROVAL
    • Description: Describes how the registered Sender ID will be associated with your AWS account once the registration is approved.
    • Implication: ASSOCIATE_ON_APPROVAL means that the Sender ID will be automatically associated with your account as soon as the registration is approved, simplifying the process post-approval. There will be nothing more for you to do once you have successfully submitted your registration and it has been approved. Some registration types require steps to be taken after the registration is approved, this is not one of them.
  • Disassociation Behavior: DISASSOCIATE_ALL_CLOSES_REGISTRATION
    • Description: Explains what happens when you disassociate the Sender ID from your account.
    • Implication: This behavior is important to note because it means that the origination identity must be disassociated from the registration before the registration can be closed.

Step 2: CreateRegistration

Next, use CreateRegistration with the RegistrationType for Jordan, “JO_SENDER_ID_REGISTRATION,” to generate a blank registration “container” for a Jordan Sender ID. Make sure to log the “RegistrationId” for later use as it will be used throughout the rest of the process.

Below is a screenshot of the registration that was created in the console

Step 3: DescribeRegistrationFieldDefinitions

Use DescribeRegistrationFieldDefinitions with “JO_SENDER_ID_REGISTRATION” as the RegistrationType to pull down all the fields that need to be filled out to submit the registration.

Important Field Attributes

  • FieldPath
    • Value: A string that specifies the path to the field within the registration form (e.g., companyInfo.companyName).
    • Description: The FieldPath attribute provides a hierarchical path to the specific field within the registration form. It identifies one of the fields we will use later to input the data into our registration
    • Implication: Ensures that you place the required information in the correct field, essential for accurate processing.
  • FieldRequirement
    • Value: Indicates whether the field is required, optional, or conditional (REQUIRED, OPTIONAL, CONDITIONAL).
    • Description: The FieldRequirement attribute specifies the necessity of the field in the registration process. A REQUIRED field must be filled out for the registration to be submitted, while an OPTIONAL field can be left blank if not applicable. A CONDITIONAL field depends on other fields and may become required based on certain conditions.
    • Implication: Helps prioritize which fields to complete and ensures critical information is not missed.
  • FieldType
    • Value: Describes the type of data expected in the field (SELECT, TEXT, ATTACHMENT).
    • Description: Indicates the format and type of data that should be entered into the field.
    • Implication: Ensures the registration form is valid and reduces the risk of errors or rejections due to incorrect data formats.

See the categories of the Jordan registration in the screenshot below

Let’s break down the required fields that are common across all Sender Id registrations and their descriptions in a more readable format:

Sender ID Information:

  1. Sender ID (Required)
    1. Must be 3-11 alphanumeric characters
    2. Must contain at least one letter
    3. Example: “EXAMPLE”
  2. Sender ID Description (Optional)
    1. Explain the connection between company name and sender ID
    2. Max 500 characters
  3. Proof of Sender ID Connection (Optional)
    1. Required only if the connection between company name and sender ID isn’t obvious
    2. Must provide evidence of intellectual property rights

Below is a screenshot of the Console version

Company Information:

  1. Company Name (Required)
    1. Legal company name
    2. Max 100 characters
    3. Example: “Example Corp”
  2. Company ID (Required)
    1. Legal identification number (EIN/VAT)
    2. Alphanumeric only
    3. Max 30 characters
  3. DBA Name (Optional)
    1. “Doing Business As” name if different from legal name
    2. Max 100 characters
  4. Website (Required)
    1. Company’s full URL
    2. Example: “https://www.example.com”
  5. Area of Business (Required)
    1. Choose one: Agriculture, Communication, Construction, Education, Energy, Entertainment, Financial, Government, Healthcare, Hospitality, Insurance, Manufacturing, Real estate, Retail, Technology, Other

Below is a screenshot of the Console version

Company Address:

  1. Address Line 1 (Required)
  2. Address Line 2 (Optional)
  3. City (Required)
  4. State/Province (Optional)
  5. Postal Code (Optional)
  6. Country Code (Required)
    1. Two-letter ISO code
    2. Example: “US”

Below is a screenshot of the Console version

Contact Information:

  1. Email Address (Required)
    1. Valid email format
    2. Example: “[email protected] “
  2. Phone Number (Required)
    1. Must contain at least 3 digits
    2. Example: “+12065550100“

Below is a screenshot of the Console version

Messaging Use Case:

  1. Use Case Category (Required)
    1. Choose one: One-time passcodes, Account/security alerts, Purchase/delivery notifications, Public service announcements, Polling/surveys, Info on demand, Other
  2. Use Case Description (Required)
    1. Max 500 characters
  3. Monthly Message Volume (Required)
    1. Choose one: 10, 100, 1,000, 10,000, 100,000, 1,000,000, 10,000,000+
  4. Opt-in Description (Required)
    1. How users will opt-in to receiving messages
    2. Max 500 characters

Below is a screenshot of the Console version

Message Samples:

  1. Message Sample 1 (Required)
    1. Max 306 characters
  2. Message Sample 2 (Optional)
    1. Max 306 characters
  3. Message Sample 3 (Optional)
    1. Max 306 characters

Below is a screenshot of the Console version

Jordan-Specific Requirements

Some countries, not all, also have country-specific requirements. Jordan requires the following for this registration:

  1. Company Registration Documentation (Required)
    1. Must provide company registration docs (both local and international companies)
    2. This is an Attachment type so we will need to use “CreateRegistrationAttachment” first in order to put this value into the registration. We will cover this further down in the process
  2. Transactional Acknowledgement (Required)
    1. Must acknowledge that only transactional messages will be sent
    2. Promotional content is not allowed
    3. This is a “Select” field type with the only option being “Yes” meaning you will be unable to register unless you agree to this acknowledgement

Below is a screenshot of the Console version

Step 4: CreateRegistrationAttachment

Now that you know all the fields required for the Jordan Sender ID registration, you need to gather all the necessary data, including the required attachment. The Jordan Sender ID registration requires only one attachment. Let’s review how to add this attachment to your registration.

To add an attachment to your registration, use the CreateRegistrationAttachment API. You have two options for providing this document:

  1. Specify a file in S3:
    1. Ensure you use Standard buckets, S3 Express is not supported.
  2. Upload it as a Base64-encoded binary data object:
    1. This method allows you to directly upload the document without needing to store it in S3 first.

Important: After successfully running the CreateRegistrationAttachment command, you will receive a “RegistrationAttachmentId.” Make sure to log this ID, as you will need it to attach the upload to your registration.

Step 5: PutRegistrationFieldValue

Use PutRegistrationFieldValue to input data into each field. Loop through each input as each call only inputs a single value. Specify the “RegistrationId” logged earlier when making each call. Your options for field values are:

  • RegistrationAttachmentId: The unique identifier for the registration attachment
  • SelectChoices: An array of values for the form field that were specified in the payload earlier
  • TextValue: The text data for a free form field

Step 6: Review your registration

Once you have successfully inputted all the values for your registration, you can review your inputs in one of two ways:

  1. View in the Console:
    1. Your registration details are accessible directly in the AWS Management Console.
  2. Use DescribeRegistrationFieldValues:
    1. You can pull down your registration and review each of its values using the DescribeRegistrationFieldValues API. Make sure to use the right version ID of your registration.

Step 7: Submitting Your Registration

Once all values in your registration are complete and correct, submit your registration for review using the SubmitRegistrationVersion API. Provide your “RegistrationId” when making this call.

Initial Status:

  • The initial status of your registration will be “CREATED.”
  • It should change to “REVIEWING” within 24 hours.
  • If the status does not change from “CREATED” to “REVIEWING” within 24 hours and you’ve confirmed you SUBMITTED your registration version, create a support case for assistance.

Sender ID Registration Review Process

Each country has its own review process and timeline. Each registration is examined on a first-in/first-out basis by the registrar for each country. AWS does not review your registrations so make sure that you are completing this registration with this in mind. There are humans reviewing these registrations that do not know your company or your use case so make sure to be clear and concise in your responses.

If the registrar is confused by your submission, they may reject it, and you will need to start the process over, amending the registration where necessary and resubmitting. This puts you in the back of the line again, which will increase your timeline.

Conclusion

Completing a Sender ID registration using the End User Messaging V2 APIs involves several steps, each critical to ensuring compliance and successful registration. By following this guide, you can navigate the process efficiently, from understanding the required fields to submitting your registration for review. Whether you’re registering in Jordan or another country with different requirements, this guide provides the knowledge and steps needed to successfully obtain a Sender ID and establish a trusted communication channel with your customers via SMS.

How to Register for a United States (US) SMS Short Code with AWS End User Messaging

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-register-for-a-united-states-us-sms-short-code-with-aws-end-user-messaging/

Obtaining and using SMS short codes in the United States requires a thorough understanding of the detailed application process and strict requirements set forth by mobile carriers. This comprehensive guide walks through the step-by-step procedure for registering a US SMS short code from AWS End User Messaging, which provides SMS capabilities to all AWS services.

This guide covers the process from initial creation of a support case, the short code application form with all necessary details and documentation, and the multi-stage provisioning process involving carrier review and approvals. Particular emphasis is placed on establishing compliant opt-in workflows, crafting SMS-specific terms and privacy policies, and preparing the required message templates – all of which are closely scrutinized by the carriers.

While the application process may be time-consuming, the benefits of using a short code, include:

  • High throughput – They start out at 100 messages per second
  • Ability to scale to thousands of messages per second
  • Higher deliverability rates – Because of the increased upfront scrutiny in the registration process they have less issues with filtering and blocking. Critical use cases such as One-Time Password(OTP)/Two-Factor Authentication(2FA) are use cases that, even if you don’t need the high throughput, you may want to consider using a US short code to deliver them in the US
    • Short codes investigate issues before blocking through proactive audits, while other registered originator types such as toll-free or 10DLC block/filter first and investigate later when issues arise
  • Easy for customers to remember and identify – Short codes are 5-6 digit numbers, which is easier for recipients to remember than 10+ and lends credibility and trust to your message

The US Short Code Application Process

Step 1: Create a Case in AWS Support Center

Currently short codes are only available by opening a case. The first step to register a short code is to open a short code request case in the AWS Support Center, providing detailed information about your use case and opt-in policies. A request must be opened for each country in which you want a short code. Each country has their own registration process and requirements so if you are registering for other countries besides the US having a case for each allows for much easier tracking and updating as there are communications going back and forth between you, the customer, support, and any downstream clarifications that may come back.

NOTE: If you require a HIPAA eligible Short Code for your use case please respond to the case with explicit confirmation that you require a HIPAA eligible Short Code. We will provide you a unique form for this use case

Along with attaching the correct form Support will request that you confirm that you understand the pricing, billing, and time frame of this request so make sure that you respond to the case, don’t just start on the application.

Step 2: Complete the Short Code Application

We will walk through the US Short Code application in detail below. Make sure that everything you submit is 100% correct to your knowledge, as any missing information or information that needs to be corrected extends the time it takes to receive your short code.

NOTE: Application forms are occasionally revised to clarify or add to existing information. By the time you read this post, the form that you receive might differ slightly from the form that we review in this post.

The first section of the US Short Code form contains basic information about your company.

Company Information

Most of the fields in the first section are straightforward but the key thing to make sure you have a good understanding of is, who owns the relationship with the recipients? The company that owns the opt-in data and controls the message(not just the delivery) is the company that needs to have their information submitted.

IMPORTANT: If you are a SaaS/mutli-tenant/service provider, providing SMS capabilities to YOUR customers or a business within a larger portfolio make sure that you are clear on that. It does not matter WHERE the opt-in is happening, it matters who owns the data and the clear relationship between that entity and the recipient. The company that owns that relationship is the company who’s information needs to be used.

There are a few fields in this section that people ask how they will be used:

Primary Contact name, email address, phone number

These contact details will be used during the Company vetting/validation step we will discuss later in this post. It would also be used to contact you if there is ever an audit of your short code.

Customer Care Information

The customer care contact points are required to be actively monitored.

Customer Care URL

The URL of a page where your customers can go to find information about contacting your Customer Support team.

Customer Care Email

The Carriers require you to provide an email address that customers can contact if they have questions about your short code messaging program. This address should be a shared mailbox or distribution list (such as [email protected]) rather than an individual person’s email address and must match the domain of the Company URL in the Company Information section above.

Customer Care Phone Number

Like the support email address, customers should be able to call this phone number to get support for your short code messaging program. The phone number doesn’t have to be a toll-free number, but it does have to be a US-based phone number.

Short Code Service Information

AWS Region

The AWS Region that you use AWS End User Messaging in. If you’re not sure, check with the person or team within your organization that is responsible for managing your AWS accounts.

IMPORTANT: Short codes can only be used in the region that they are requested in and cannot be moved. Short codes can be shared to other accounts via Resource Access Management but they must be in the same region. All resource billing, such as the shortcode monthly leasing fee, will still run through the managing account but the cost for SMS volume will be charged to the sending account.

Short Code Option

In the US you have the option of either a 5-6 digit random code or a “vanity” code that you can specify. These vanity codes are numeric only, take longer to procure, and come with a higher cost. You can check if your preferred vanity code is available at: https://www.usshortcodes.com/find-short-code

Short Code Use Case

Mobile Carriers need to know how you plan to use your short code, and how you will interact with users. It is very important to be clear and concise in this section. Humans are reviewing these so make sure that everything you write can be understood without any prior knowledge of your company or your use case.

Company Overview

Provide a short description of the products/services that your Company provides to its customers. This should concisely answer the question, “Who are you and what do you do?”

Service Name

A name or phrase that identifies your messages as being from you. Service names typically are a recognizable form of your company or brand name. It can be a shortened version as long as it is something that your recipients would recognize as coming from you.

  • For example, if Example Corp. wants a short code for sending account-related notifications, they could use a service name like “Example Corp.” The Carriers require you to put this service name at the beginning of each message. Keep in mind that SMS has a limit of 160 characters so you do want to keep this short.
  • A message might look like this:
    “Example Corp. – This is an account notification for your account #[XXXXXX].”
Message Type(s)

You can choose more than one message type but keep in mind that for each message type that you select you will need to provide examples of those types of messages later in the form and you also need to collect consent for each one. We recommend to not mix promotional and transactional type messages on a single code but at the time of publication this is acceptable by the carriers.

Message Examples

You need to provide at least ONE message example for each of the message types you chose above. Carriers will review these examples during the approval process. These are only examples and will not be the only messages you will be able to send but they should represent all of the types of messages that you plan on sending. If you need more room it is fine to add more examples. Remember you do NOT need to include every message you plan on sending, as long as you have a representative sample of all message types.

  • Requirements:
    • Include your service name in every message sample
    • Ideally each message is 160 characters or less to reduce your costs. Any message over 160 characters is broken into message parts in 160 character chunks and each message part is charged. 161 characters would be two message parts
      • If your message uses only characters in the GSM 03.38 character set, also known as the GSM 7-bit alphabet, it can contain up to 160 characters. If your message contains any characters that are outside the GSM 03.38 character set, it can have up to 70 characters. When you send an SMS message, AWS End User Messaging SMS automatically determines the most efficient encoding to use. We provide a tool in the AWS console to check your messages.
      • If your messages will include variables, it’s fine to use either placeholder values or variables.
        • For example, both of the following are acceptable: “Hello John. Your one-time password is 654321” and “Hello [first_name]. Your one-time password is [otp code] .”
      • Do not use unbranded link shorteners i.e., “bit.ly/yourlink”
        • If you have to use a shortener make sure that it is branded and that there are not multiple redirects. Also make sure to provide examples of the branded shortened domain so that it is on file with the carriers
    • Include an example of all of the message types you are registering for
    • If you plan on sending in languages other than English, include those versions
    • Read them all and make sure that they are clearly a part of the message type/use case that you are registering for
  • If you plan on sending Multimedia Messages(MMS) make sure you include at least one example
Multimedia message sample (MMS)

MMS capabilities must be requested at the time the short code is requested. If you intend to send MMS messages make sure you check the box and include a message example in the section above

Will you use your short code for any of the following?

Selecting “Sweepstakes or contest” or “Debt Collection” will require more documentation. For example, official sweepstakes rules and terms would be requested if that was your use case. If neither of these apply then select “N/A”

NOTE: Debt collection in particular is highly regulated. If you are a 3rd party debt collector you will not be able to get a short code.

Per-user message frequency

This is an estimate but will be used later in some of the message templates so be sure to have this correct. Will you be sending out 1 message per day? Week? Month? Programs like Two Factor Authentication(2FA) or One-Time Password (OTP) are examples of “message frequency varies” or “1 message per login”.

Carrier requirements for user sign-ups

The core requirement for communicating with SMS is explicit consent – end users must have the option to consent to receive your messages, know exactly what the program will include, and are able to opt-out or ask for help at any time. There are no exceptions to this regardless of the use case or your business type. As a reminder, Carriers make their own rules which will override things like FCC exemptions.
The Carriers pay extra attention to the information provided in the following section, so be thorough and follow the guidelines provided. An in-depth review of how to build a compliant SMS opt-in process can be found here.

How the User will opt-in

There are lots of compliant ways to capture an opt-in. Choose the option that applies to your use case. It’s fine to choose more than one option. However, you must provide mockups of the opt-in workflows for all of the options that you select. Be prepared to provide a verbal script for any opt-in processes where the user does not have the written call-to-action and SMS disclosures in front of them to read. Examples include:

  • Sending a keyword to your short code
  • Website or mobile app
  • Over the phone/In-Person
  • Paper forms
  • Other – Which you will need to explain in detail. As long as you can be compliant, it should be accepted
User Experience Flow

This is one of the most comprehensive parts of the form and where many customers tend to receive a lot of feedback because there are several things that MUST be included in this section and there are no exceptions. Below you will find a list of the required components and descriptions of each. Keep in mind that these can be written or verbal opt-ins but this does not change the below requirements. Keep this concise, only detailing the opt-in process and nothing else.

  • The Opt-in location must include the following:
    • Program (brand) name
    • A call-to-action phrase like “To receive SMS account notifications from [SERVICE NAME], enter your mobile number below”
    • You must expressly collect consent for each use case(s) that you detailed above. A single checkbox for all use cases will not be approved.
      • For example, If you are sending account notifications and OTP you must have two separate statements such as:
        • “To receive SMS One Time Password notifications from [SERVICE NAME], check this box and enter your mobile number below.”
        • “To receive SMS account notifications from [SERVICE NAME], check this box and enter your mobile number below.”
    • The opt-in must be “explicit” this means that any checkboxes, radio buttons, etc. must be left unchecked or at least not defaulted to SMS if you have options. If it is a verbal script then there must be a verbal consent given and you should track the date of that consent. If it is written then the recipient must sign and date the consent.
    • You must supply a secondary channel such as email. SMS must be optional and another option must be provided. This is mandated by Verizon in the US.
    • Link to a publicly accessible Terms & Conditions page
      • We will detail what needs to be included later in this guide
    • Link to a publicly accessible Privacy Policy page
      • We will detail what needs to be included later in this guide
    • Message frequency disclosure
      • Same as stated earlier in this application
    • Customer care contact information
      • Email address, phone number, Text “Help”, are all valid
    • Opt-out information
    • “Message and data rates may apply” disclosure.
      • This must be verbatim

This must be explained for each process that you checked in the “How the user will opt-in” section. If you are using a keyword and also have the ability to opt-in from your website or mobile app for example, then both of those processes need to be documented here.

If you are using a paper form or a verbal opt-in all of the required components must still be present. If verbal, components such as the Privacy Policy location must be read back to the person opting in. If written, then the full URL needs to be present. Regardless of your process you must include all of the components for you to be approved.

Opt-In Mockup

This is where you can supply screenshots if the opt-in location is online. You can also provide the verbal script or written opt-in form here as well. Make sure that the Opt-in mockup exactly matches the above requirements and that you explain the process.

Example of an online form

Terms and Conditions URL

This is the URL where your SMS-specific Terms and Conditions document resides, or where it will reside. You can also include a link to your standard Terms and Conditions page, as long as it includes a section dedicated to SMS messaging. If those terms and conditions aren’t live yet, or are not available online, you must include a copy of the Terms and Conditions along with your completed application. There are boilerplate items that MUST be included here with no exceptions, see here for more detail and below for those items:

  1. {Program name}
  2. {Insert program description here; this is simply a brief description of the kinds of messages users can expect to receive when they opt-in.}
  3. You can cancel the SMS service at any time. Just text “STOP” to the short code. After you send the SMS message “STOP” to us, we will send you an SMS message to confirm that you have been unsubscribed. After this, you will no longer receive SMS messages from us. If you want to join again, just sign up as you did the first time and we will start sending SMS messages to you again.
  4. If you are experiencing issues with the messaging program you can reply with the keyword HELP for more assistance, or you can get help directly at {support email address or toll-free number}.
  5. Carriers are not liable for delayed or undelivered messages
  6. As always, message and data rates may apply for any messages sent to you from us and to us from you. You will receive {message frequency}. If you have any questions about your text plan or data plan, it is best to contact your wireless provider.
  7. If you have any questions regarding privacy, please read our privacy policy: {link to privacy policy}
Privacy Policy URL

Message Senders are responsible for protecting the privacy of Consumers’ information and must comply with applicable privacy law. Message Senders should maintain a privacy policy for all programs and make it accessible from the initial call-to-action. The privacy policy should be labeled clearly and privacy policy disclosures must provide up-to-date, accurate information about program details and functionality. For verbal scripts, a URL must be read off to the end-user enrolling in the SMS program, or the comprehensive terms or link to those terms must be directly included in the script.

  • One of the key items Carriers look for in a Privacy Policy is the sharing of end-user information with third-parties. If your privacy policy mentions data sharing or selling to non-affiliated third parties, there is a concern that customer data will be shared with third parties for marketing purposes and your registration could be rejected at worst or delayed while you explain or update your Privacy Policy.
  • Express consent is required for SMS; therefore, sharing data is prohibited. Privacy policies must specify that this data sharing excludes SMS opt-in data and consent. Privacy policies can be updated (or draft versions provided) where the practice of sharing personal data to third parties is expressly omitted from the number registration. You can include an SMS specific section within your privacy policy if your company or business model requires data sharing. This part is non-negotiable and Carriers are incredibly strict about this requirement
    • Example: “The above excludes text messaging originator opt-in data and consent; this information will not be shared with any third parties.”
Confirmation SMS / Double Opt-In

A confirmation message is the message sent when someone opts into your program. It is required you send your customers an opt-in confirmation message. It is optional, but a best practice, to include a “Double Opt-In,” such as the example below, asking the recipient to text back a confirmation to prove “humanness” and also validates your end user provided you with their correct phone number

There is one exception to the above if your use case is an OTP/2FA. In this one instance, the OTP code that you send to your recipients is considered a confirmation. You MUST however, still opt them in initially, adhering to all of the prior requirements we have detailed in the above sections.

This message must include the following in 160 characters or less:

  • The service name that you specified earlier in the application
  • The phrase “message and data rates may apply”
  • Information about how often recipients will receive messages from you (such as “up to 30 messages per month” or “message frequency varies”)
  • Information about getting help (typically, something similar to “Text HELP for more info”)
  • Information about opting out (typically, something similar to “Text STOP to opt out”).

Example Message:

  • “Welcome to AnyCo! Reply “YES” to confirm your subscription and get special offers once a month. Msg & data rates may apply. Text ‘STOP’ to opt out.”
    • It is best practice, but not required, to do a “double opt-in” as seen in the example where the recipient will text back “YES” to confirm that they did want to register.
HELP Response

The “Help message” is the response that is required to be sent to end-users when they text the keyword “HELP” (or similar keywords). The purpose is to provide information to the end-user related to how they can get support or opt-out of the messaging program.

  • The message must include:
    • Program (brand) name OR product description
    • A method of contacting your support organization. Email addresses, websites, and phone numbers are all acceptable methods of communication. We recommend that you include two contact methods in your response (such as a phone number and a website).
  • The following is an example of a HELP response that complies with the requirements of the US mobile carriers:
    • ExampleCorp Account Alerts: For help call 1-888-555-0142 or go to example.com. Msg&data rates may apply. Text STOP to cancel.
STOP Response

The “Stop message” is the response that is required to be sent to end-users when they text the keyword “STOP” (or similar keywords). End-users are required to be opted out of further messages when they text the STOP (or equivalent) keyword to your number and confirms with them that they will no longer receive messages for the program.

  • The message must include:
    • Program (brand) name OR product description
    • Confirmation that no further messages will be delivered
  • The following is an example of a compliant STOP response:
    • You are unsubscribed from ExampleCorp Account Alerts. No more messages will be sent. Reply HELP for help or call 1-888-555-0142.

Step 3: Submit the Application and Supporting Documents

Attach your completed application to your AWS Support case. Make sure to monitor this case daily as there can be clarifications that are needed or additional information and any delay can cause substantial delays in receiving your short code.

NOTE: Billing for short codes starts at the time the application is submitted to be reviewed, which is before the short code is registered for use. We will let you know when that review period begins.

Step 4: Documentation Pre-Review

Your documentation will be reviewed prior to submitting it to the Carriers. This does not guarantee that there will be no questions/revisions but it does make step 6 more efficient as there should be less potential questions from the Carriers. Once your documentation is considered compliant your company will be submitted for vetting.

Step 5: Vetting

This is similar to a credit check process where your data will be validated by a third-party and you will need to prove you are a member of your company through a domain validation email.

Example email for vetting

Step 6: Resolve Follow-up Issues

Respond promptly to any questions or concerns raised during the review process. Make sure to monitor this case daily as there can be clarifications that are needed or additional information and any delay can cause substantial delays in receiving your short code.

The Provisioning Process – Post Approval

After approval, Carriers begin setting up your short code on their networks. This process typically takes 6+ weeks to complete across all US carrier networks. This is a part of the overall timeline given.
Expected sequence of events for Carrier Review

  1. The Carriers will review your application. We’ll answer any questions/corrections requested by the aggregator or the Carriers for your application. You may need to provide additional information.
  2. The Carriers will connect the short code to their network for testing. Each carrier will approve your application and provision on their network.
  3. We will send you a confirmation that your short code is ready and activated in the End User Messaging service once all Carriers finish their approval and provisioning process. This process is only as fast as the slowest carrier approval.

What happens if I don’t complete these steps or if I need to change something?

Customers sometimes ask what would happen if they didn’t implement all of the requirements that are discussed in the preceding sections. If your application for a new short code doesn’t meet these requirements, the answer is simple: the Carriers will reject your request for a short code. These carrier-imposed requirements are not optional.

If you submit an application that meets all of the carrier requirements and you are approved but your real-world production use case doesn’t meet those requirements, there could also be consequences. The Carriers periodically perform audits of short codes to ensure that they are being used in a compliant manner. You can review the process here in the CTIA Short Code Monitoring Handbook If they find that your opt-in process differs greatly from what you showed in your short code application, or your use case is different than what you registered for they could pause your short code’s ability to send messages on their networks. Remember, one advantage of using a short code compared to other originator types is that, because of the increased scrutiny for being approved, when this happens, the Carriers typically provide some time to remedy the issue, rather than just block your messages without warning.

We will alert you if there is an audit of your short code and advise you on what changes/additions need to be made in order to remain within compliance and continue sending via your short code.

What do I do if I need to make edits to my registration after it is approved?

It’s OK to make minor edits such as correcting typos, clarifying text, or using a variation of a message template that was already approved after you receive your short code. Remember it is critical that you do not deviate from the use case that you registered for, short codes are periodically audited, and deviating from the use case in your application could lead to your short code being suspended if you do not respond and comply with the requests. When in doubt, open a case and request that support reviews your change, prior to making it, to determine whether you can launch the new template/process without risking an audit.

If you need to make substantial changes to these templates after you receive the short code, you may need to submit your updated message templates to the carriers. Substantial changes could include the following:

  • Changes to the brand name that appears on your messages (for example, if your company rebrands under a new name, or is acquired by another company).
  • Changes to the use case (for example, if your application specified a one-time password use case, but you start sending account notifications through the same short code). This type of change might require you to re-collect consent from your customers before you start sending the new type of messages.

In these situations, you should open a case with AWS Support. We will work with the Carriers to have your short code registration information updated or depending on the change, you may need to register for another short code.

Conclusion

Obtaining and utilizing SMS short codes in the United States is a complex and highly regulated process that requires meticulous attention to detail. However, the benefits that short codes offer – such as high throughput, enhanced deliverability, and strong brand recognition – make them a valuable communication tool for businesses that need to engage customers at scale through SMS.

The key to successfully navigating the short code application and provisioning journey lies in proactively planning and preparing. By thoroughly understanding the carrier requirements upfront, companies can avoid common pitfalls and delays that often plague short code implementations. This includes thoughtfully designing compliant opt-in workflows, crafting robust terms of service and privacy policies, and developing a comprehensive set of message templates that align with approved use cases.

While the investment of time and resources may seem daunting, the long-term advantages of leveraging a short code make it a worthwhile endeavor. Short codes instill a sense of trust and familiarity with customers, allowing businesses to stand out in a crowded messaging landscape. Moreover, the rigorous vetting process ensures that only legitimate players gain access to this high-value communication channel, protecting consumers from spam and fostering a healthy ecosystem.

Ultimately, the decision to pursue a short code should be made with a clear understanding of the commitment required. However, by leveraging the guidance and best practices outlined in this comprehensive guide, companies can navigate the complexities with confidence and position themselves for success in delivering impactful, high-performing SMS campaigns that drive meaningful engagement and business outcomes.

Automate the Creation & Rotation of Amazon Simple Email Service SMTP Credentials

Post Syndicated from Zip Zieper original https://aws.amazon.com/blogs/messaging-and-targeting/automate-the-creation-rotation-of-amazon-simple-email-service-smtp-credentials/

[Amazon Simple Email Service] provides a secure email solution that scales with your business needs. Unfortunately, all email systems, including Amazon SES, remain the primary target for spammers and bad actors due to email’s widespread use and accessibility.

While SES offers powerful features for application-based email sending, its SMTP credentials require careful management to prevent unauthorized access. Compromised credentials enable bad actors to send malicious emails through legitimate domains, which can bypass security filters and damage sender reputation.

To protect your SES implementation, you must encrypt SMTP credentials during storage and transmission. Additionally, implementing role-based access controls helps restrict credential access to authorized personnel only. Regular credential rotation at fixed intervals, typically every 90 days, minimizes potential security breaches. Automating this rotation process eliminates human error and ensures consistent security practices across your organization.

Problem Statement

Imagine you are the administrator for a large financial institution. You recently began using Amazon SES to send email from two dozen on-premises servers. Your email servers authenticate with SES using SMTP credentials to access the SES SMTP interface. Your organization’s security policies mandate regular credential rotation, including the ability to rotate them on-demand. How can you automate SMTP credential rotation such that you can meet your organization’s security policies?

This blog post will present two solutions that automate the secure management and automatic rotation of SMTP credentials for Amazon SES. Each will help enhance email security, comply with regulations, and minimize operational overhead.

Both solutions provide SES customers who use SMTP with additional tools to improve email security, ensure compliance, and reduce operational overhead. You can deploy the option that best suites your needs by following the guidance in this blog post.

If your environment supports automated rotation, AWS Systems Manager Documents (SSM Documents) can help by providing pre-defined or custom automation workflows for securely managing secrets rotation, deploy Option 1.

If your environment does not support automated rotation, you can still implement an auditable, managed rotation solution by storing your secrets in AWS Systems Manager Parameter Store by deploying Option 2.

As a pay-per-use platform, the underlying AWS services used in either deployment option will only charge you for the resources that you actually consume. You can leverage the AWS Pricing Calculator to estimate the run-time costs for your specific workload. Alternatively, you can work directly with your AWS account team to understand the pricing for these solutions.

Getting SES SMTP Credentials

To send emails through the Amazon SES SMTP interface, email servers must first authenticate with SES using dedicated SES SMTP credentials. Typically, a systems administrator logs into the AWS SES console, clicks the Create SMTP Credentials button, and navigates to the AWS Identity and Access Management] (IAM) console. There, the administrator creates an IAM user with permissions for SES. The administrator then uses the IAM user’s secret access key to generate the SES SMTP password, which they use to configure their email servers or SMTP-enabled applications for use with SES.

Multiple SMTP Credentials

The SES SMTP interface authenticates requests using an SMTP credential derived from an IAM user’s access key ID and secret access key. Since temporary access keys cannot be used to derive SES SMTP credentials, you must deploy and regularly rotate a long-lived key.

While the manual process of creating SES SMTP credentials works for a small number of credentials, it becomes cumbersome for customers with numerous email servers or strict password rotation policies. These customers may find the automated credential rotation mechanisms described in the following solutions better suited to their production needs.

Option 1 – Fully Automated Credential Rotation:

The fully automated version of this solution uses a custom Lambda function to create an SMTP password, which is stored in AWS Secrets Manager. AWS Secrets Manager’s built-in rotation feature then triggers the rotation of SES SMTP credentials. AWS Systems Manager Documents utilize AWS Systems Manager Agents to automatically make the changes to the authentication configuration on email servers.

The key advantages of using AWS Systems Manager to make the email server configuration changes include:

  • Ability to deploy changes to on-premises and Amazon EC2 hosts, allowing rotation of secrets across a hybrid estate.
    Customization of the document to specific email software configurations.
    Targeting the secret (SMTP credential) rotation document on all email servers based on tags.

Let’s dive deep into Option 1 – Fully Automated Credential Rotation.

Option 1 - Fully Automated Credential Rotation

How Option 1 works:

Refer to the image above for the workflow:

  1. AWS Secrets Manager initiates a rotation request, either on a schedule or via an authorized user’s request, triggering the “rotation Lambda” to rotate the SES SMTP credentials.
  2. The SES Secret Rotation Function Lambda (see figure x above):
    • a. Creates a new IAM secret access key for the designated SES IAM user, derives the new SES SMTP password, and stores it in AWS Secrets Manager.
    • b. Connects to SES to verify the new SMTP password can authenticate.
    • c. Initiates an AWS Systems Manager Run Command to update the new SMTP password on target email servers using a pre-configured Systems Manager Document.
    • d. (and e.) Monitors the status of the Systems Manager Document execution until all updates complete successfully
    • f. Deletes the old IAM access and secret access keys.

With this fully automated solution, SES SMTP credentials can be rotated on a schedule or triggered manually, with no impact to email service uptime.

Deploying the Fully Automated Solution in Your AWS Account (Option 1)

Prerequisites for the Fully Automated Solution

  1. AWS Account Access, typically with admin-level permission to allow for the deployment.
  2. Your preferred IDE with AWS CLI version 2 and named profile setup.
    • Alternatively, you can use the AWS CLI from the AWS CloudShell in your browser.
  3. Clone the Github repository (for this solution, you only need the README.md and sesautomaticrotation.yaml files found in /ses-credential-rotation/automatic-rotation).
    • git clone -b ses-credential-rotation https://github.com/aws-samples/serverless-mail.git
    • Note – We follow the principles of least privilege in this solution. The CloudFormation templates we’ve supplied require you to specify an identity, or configuration-set resource to use in the SES sending operation. You can find guidance on defining these values at Actions, resources, and condition keys for Amazon SES. Additionally, we’ve limited the IAM User to the ses:SendRawEmail action, which you can adjust as appropriate).
  4. Console access to your AWS SES account that is properly configured to send emails via at least one verified identity.
  5. Target email server(s) properly configured to send email via SES using SES SMTP authentication.
    • The AWS Systems Manager agent(s) must be correctly installed and configured on your target email server(s) as detailed in Setting up AWS Systems Manager.
    • The target email servers must be decorated with the tag (“SSMServerTag“) and value (“SSMServerTagValue“). These values allow the Systems Manager Document to identify them.
      • We use the tag “EmailServer” and the value “True” in our example, but you can use any tag and value that you wish).
  6. An email address (or list) to receive SMTP rotation notifications.
  7. Console access to your AWS Secrets Manager.
  8. Console access to your AWS Systems Manager.

Deployment Steps

  1. Clone the GitHub repository to your IDE
    • If using AWS CloudShell, ensure you are in the same region as your AWS Systems and Secrets Manager
    • run: git clone https://github.com/aws-samples/serverless-mail.git
    • Navigate to the directory ses-credential-rotation/automatic-rotation
  2. Follow the steps in README.md to
    • Create a S3 bucket to deploy the CloudFormation Template.
    • Package the Lambda functions and upload them to Amazon S3.
    • Deploy the Cloud Formation Template.
    • Update the appropriate AWS Systems Manager sample document created by the CloudFormation Template to reflect your email server environments. These can be found in the AWS Systems Manager console under Documents > Owned by me
      • The ExampleWindowsIISSMTPSESpasswordrotator sample provides an example for Microsoft Windows hosts using the runPowerShellScript action to update the server’s SMTP credentials.
      • The ExamplePostfixSESpasswordrotator sample provides an example for Linux hosts using the runShellScript action to update the server’s SMTP credentials.

Testing Option 1 – Fully Automated Credential Rotation

To test the Fully Automated Credential Rotation solution, have Secrets Manager perform an immediate rotation by following these steps:

  1. Open AWS Secrets Manager console
  2. Locate the secret SESSendSecret
  3. Select the Rotation tab
  4. Click the “Rotate Secret immediately” button.

You can track the progress of the rotation by locating the logs of the Lambda that is deployed to manage the rotation.

  1. In the AWS console, go to CloudFormationStack’s Resources tab
  2. Find the LogicalID = SESSecretRotationFunction
  3. Click the PhysicalID link to open the Lambda
  4. Under the Monitor Tab, select the “View CloudWatch logs” button in the top right
  5. The logs should show the rotation flow through 4 stages below (more details of each stage are available here):
    1. create_secret
    2. set_secret
    3. test_secret
    4. finish_secret

Option 2 – Partially Automated Credential Rotation:

The partially automated version uses a custom AWS Lambda function to create an SMTP password, which is stored in AWS Systems Manager Parameter Store. This solution simplifies credential rotation, where manual changes must be conducted by support staff. By wrapping the manual change process with AWS Step Functions, you can ensure a robust and auditable process to regularly rotate the SES SMTP credential.

How Option 2 works:

  1. The credential rotation AWS Step Function creates a new SES SMTP credential and updates it in AWS Systems Manager Parameter Store.
  2. It retrieves a list of servers from an Amazon DynamoDB table and launches a manual confirmation AWS Step Function execution for each server to initiate and track the manual step.
  3. The manual confirmation AWS Step Function emails the designated address, requesting support staff to arrange the rotation. The email includes a link specific to that server.
  4. The person completing the manual change confirms back to the AWS Step Function via the link that the rotation is complete.
  5. Once the rotation on a server is confirmed, the manual confirmation AWS Step Function for that server is marked as complete.
  6. After all server rotations are complete, the credential rotation AWS Step Function continues, disabling the old SES SMTP credential and deleting it after a few days.

AWS Step Function executions can last up to 365 days, providing sufficient time for the manual rotation and confirmation.

The screenshot below shows a graphical representation of the credential rotation AWS Step Function execution status, providing a real-time view of the rotation progress.

SMTP credential rotation AWS Step Function

You can also track the status of individual servers via the manual rotation step function execution list.

SMTP manual rotation step function execution list

The partially automated solution for rotating Amazon SES SMTP credentials is illustrated and detailed below:

Option 2 - partially automated solution

Refer to the image above for the option 2 workflow:

  1. EventBridge Scheduler Trigger: An EventBridge scheduler rule triggers a custom Starter Function Lambda (SF Lambda) on the last day of every 3rd month (this can be adjusted to suit your needs in the CloudFormation template).
  2. Credential Rotation Step Function: The Starter Function Lambda triggers the Credential Rotation AWS Step Function, providing a clearly defined name to facilitate auditing (“password-rotation-dd-mm-yy“).
  3. Credential Rotation Step Function Actions:
    1. Creates a new IAM (Identity and Access Management) secret access key for the SES IAM user.
    2. Triggers the SMTP Credential Generator Lambda to derive the SES SMTP password from the newly created IAM secret access key (using the algorithm provided in the SES documentation.
    3. Stores the new SES SMTP credential in AWS Systems Manager Parameter Store.
    4. Reads a list of servers that are utilizing this credential from a DynamoDB table.
  4. Manual Confirmation Step Function:
    1. For each server, a manual confirmation AWS Step Function is triggered, sending a message on the Amazon Simple Notification Service (SNS) topic.
    2. The SNS notification prompts the server administrator via email to manually rotate the SMTP credentials on the on-premises email server.
    3. The server administrator uses a link in the email to confirm the credential has been rotated and tested on the server.
    4. The link triggers the Confirmation Lambda exposed via API Gateway, which marks the ManualConfirmation step function as complete.
  5. Credential Rotation Completion: The CredentialRotation step function waits until all manual confirmation step functions have completed before proceeding.
  6. Old IAM Access Key Deletion: Once confirmation has been received for all servers, the step function deletes the old IAM access key.

Deployment

To deploy the partially automated solution in your AWS account, you will need the following prerequisites:

Prerequisites for the Partially Automated Solution

  1. AWS Account Access, typically with admin-level permission to allow for the deployment.
  2. Your preferred IDE with AWS CLI version 2 and named profile setup. Alternatively, you can use the AWS CLI from the AWS CloudShell in your browser.
  3. SES enabled, configured, and properly sending emails.
  4. External email server(s) currently configured to use SES with SMTP.
  5. Administrator email address to receive notifications.
  6. AWS Secrets Manager and AWS Systems Manager set up.
  7. AWS Systems Manager agent(s) correctly installed and configured on your target email servers as detailed in Setting up AWS Systems Manager.
  8. Amazon EC2 instance with Postfix configured to send emails through SES
  9. Target email servers must be decorated with a tag (“SSMServerTag“) and value (“SSMServerTagValue“) that will be used to identify them by the Systems Manager Document (we used “server” and “email”)
  10. AWS Parameter Store and AWS Step Functions.

Once you have the prerequisites in place, follow the instructions in the GitHub project.

Conclusion

Implementing an automated credential rotation process for Amazon SES SMTP enhances security and compliance, streamlines operations, and reduces the risk of downtime and human error. By leveraging AWS Secrets Manager and AWS Systems Manager (option 1) or AWS Systems Manager Parameter Store and Step Functions (option 2), organizations can centralize SES SMTP credential management, maintain an audit trail, and quickly update email application servers with new SMTP credentials.

Need additional guidance?

A Guide to SMS Short Codes with AWS End User Messaging

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/guide-to-sms-short-codes-with-aws-end-user-messaging/

In today’s digital age, SMS messaging remains a crucial communication channel for businesses. One of the most effective ways to leverage SMS is through the use of short codes – those brief, memorable numbers that make it easy for customers to interact with your brand. This comprehensive guide will walk you through everything you need to know about obtaining and using SMS short codes.

What Are Short Codes and Why Use Them?

While short codes aren’t required for sending SMS in most countries(not all) they are synonymous with high throughput and reliability.

They offer several advantages:

  • High throughput – They start out at 100 messages per second
  • Ability to scale to thousands of messages per second – If you need the kind of scale to send out mass alerts in a short amount of time, the best option is likely a short code
  • Higher deliverability rates – Because of the increased upfront scrutiny in the registration process they have less issues with filtering and blocking. Critical use cases such as One-Time Password(OTP)/Two-Factor Authentication(2FA) are use cases that, even if you don’t need the high throughput, you may want to consider using a short code to deliver them
    • Short codes investigate issues before blocking through proactive audits, while other registered originator types such as toll-free or 10DLC block/filter first and investigate later when issues arise
  • Easy for customers to remember and identify – Short codes are 5-6 digit numbers, which is easier for recipients to remember than 10+ and lends credibility and trust to your message

Short Codes Shortcomings

While short codes offer many advantages for SMS messaging, they also come with some things to be aware of

  • Short codes are limited to SMS/MMS functionality only, unlike other number types such as long codes, 10DLC, or toll-free numbers that can also support voice messages. This limitation may restrict your communication options with customers.
  • Carriers consider short codes a premium product, which can lead to higher costs for businesses.
  • The process of obtaining a short code can be more time-consuming and complex than other originators, requiring strict adherence to carrier requirements and a thorough application process that can take several weeks to months to complete. This is not specific to AWS, these processes are controlled by the carriers and countries in which you are applying. For example, some countries require specific supporting documents such as a Letter of Authorization (LOA) or even a copy of a passport of an executive at the company. Be ready to provide these as there are usually no exceptions to these requirements.
  • While it’s an edge case, there are some prepaid mobile plans, like those offered by T-Mobile in the US, that don’t allow their users to receive messages from short codes, potentially limiting your reach.

Do You Need a Short Code?

If you answer yes to any of the below, you might want to consider a short code

  • You need over 20 MPS
  • You need daily volumes over 400K
  • You need higher success rates
  • You want an easily recognizable number for your brand
  • The country you need to send to ONLY allows short codes
  • Ensuring maximum reliability is critical
  • You operate in a highly regulated industry (like finance)

However, keep in mind that short codes:

  • Do not support voice like long codes can
  • Require a more rigorous application process and take longer to obtain
  • Have an increased cost compared to other originator types (Long codes, Toll-Free, 10DLC, Sender ID, etc.)
  • While a small edge case, they may not be supported by some prepaid mobile plans

If you’ve decided that your use case requires a short code, you have to do some planning before you request one. The next few sections guide you through some of the requirements that must be in place in order to obtain and use a short code.

Planning Your Short Code Application

Before applying for a short code, you need to have several elements in place:

1. Understand Consent Requirements

Carriers impose their own, more strict, requirements beyond the minimum requirements of law in many countries. A non-exhaustive list of consent requirements include:

  • Explicit consent is required before sending any messages
    • It does not matter if you are messaging to your employees, sending to 6 people on an IT team, or sending millions of messages promoting your brand, there are no exceptions to this rule
  • Consent must be specific to each message type (no blanket consent)
    • You must obtain explicit consent for each distinct use case such as OTP/2FA, Marketing, and the various flavors of transactional messaging. You can find examples of the distinct use cases that US 10DLC numbers adhere to here which is a good place to start when trying to classify your use cases
  • Consent can’t be transferred between companies
    • The concept of consent lies with who owns the relationship to the recipient. Just because you have received consent for a brand within your portfolio does not mean that you can message someone for a different brand or use case.
    • If you are a SaaS or multi-tenant type customer where you are offering SMS capabilities to your customers, then proof of consent must be supplied by your customer and their information submitted for review.
    • Never sell/rent your list of opted-in customers, and never use purchased or rented lists.
  • Receiving SMS can’t be a requirement for using your service or opting out
    • If your use case requires that you verify your customer’s phone number, provide them an alternative to receiving text messages. For example, provide the option to receive a voice call or an email and opt-out via different channels as well

2. Design Compliant Opt-in Workflows

An in-depth explanation of how to design a compliant opt-in process can be found here. Your opt-in process does not have to be online. You can use verbal scripts, paper forms, or online signups but the location at which someone is opting in must include:

  • A description of message types you’ll send
  • The phrase “Message and data rates may apply”
  • Message frequency information
    • This is a statement such as:
      • “You will receive (1-10) messages per (day/week/month/other)” or “message frequency varies”
  • Links to Terms & Conditions and Privacy Policy or a printed copy if not publicly accessible
  • Opt-out information (example: “Text STOP to opt-out of future messages.”)
  • Communication options
    • If your use case is 2FA/OTP you must supply a secondary channel for receiving the codes, such as email. SMS must be optional and another option must be provided. This is mandated by Verizon in the US.
    • In all other use cases SMS must be optional. It cannot be a requirement for a subscriber to opt in to SMS in order to sign up for a service. As an example: you sign up for a rewards program at a coffee shop and it is mandatory to sign up for SMS in order to join the program. This is prohibited
  • An explicit opt-in
    • Checking a box, signing your name and date, capturing it verbally and logging it. These are all valid forms of explicit opt-in. If you pre-check boxes on your forms that is NOT considered an explicit opt-in and your registration will be denied, increasing the time it will take to get approved.

The image below is an example of an online form. This is a more complex flow but you could also have a single screen flow, as long as it contains all of the above required components. Keep in mind that you can also use verbal scripts and paper forms that include all of the required components above.

Image 1 – Complex

3. Create/Update SMS-specific Privacy Policy and Terms & Conditions

Data privacy is an important component of any SMS program and when applying for a short code the US mobile carriers set the most stringent requirements regarding specific language in your Privacy Policy and Terms & Conditions. If you comply with the below for your Privacy Policy and Terms & Conditions this should put you in compliance for other countries that you may want to apply for.

For a more in depth discussion of the topic of opt-in and compliance please visit

NOTE: You are allowed to create an SMS only section within these two documents to call out different data sharing or other terms that apply to SMS but not to other parts of your business, but these items are non-negotiable and must be present or your registration will be denied by the carriers in the US

Terms & Conditions

Below is the boilerplate language that covers minimum requirements from the US carriers who are the most stringent:

  1. {Program name}
  2. {Insert program description here; this is simply a brief description of the kinds of messages users can expect to receive when they opt-in.}
  3. You can cancel the SMS service at any time. Just text “STOP” to the short code. After you send the SMS message “STOP” to us, we will send you an SMS message to confirm that you have been unsubscribed. After this, you will no longer receive SMS messages from us. If you want to join again, just sign up as you did the first time and we will start sending SMS messages to you again.
  4. If you are experiencing issues with the messaging program you can reply with the keyword HELP for more assistance, or you can get help directly at {support email address or toll-free number}.
  5. Carriers are not liable for delayed or undelivered messages
  6. As always, message and data rates may apply for any messages sent to you from us and to us from you. You will receive {message frequency}. If you have any questions about your text plan or data plan, it is best to contact your wireless provider.
  7. If you have any questions regarding privacy, please read our privacy policy: {link to privacy policy}

Privacy Policy

One of the key items carriers look for in a Privacy Policy is the sharing of end-user information with third-parties. If your privacy policy mentions data sharing or selling to non-affiliated third parties, there is a concern that customer data will be shared with third parties for marketing purposes.

Express consent is required for SMS; therefore, sharing data is prohibited. Privacy policies must specify that this data sharing excludes SMS opt-in data and consent. Privacy policies can be updated (or draft versions provided) where the practice of sharing personal data to third parties is expressly omitted from the number registration.

Example: “The above excludes text messaging originator opt-in data and consent; this information will not be shared with any third parties.”

It can also be an option to put the privacy statement in the Call-to-action mockup if you do not want to have to put it in your privacy policy page.

4. Prepare Message Templates

When submitting your registration, you must provide examples of the messages you will be sending. This includes automated responses triggered by specific keywords from end-users such as “Help“ as well as the outbound messages you will be sending to your recipients based on your use case. While we’ll provide English examples below, note that keywords and responses should be localized based on your recipient countries. You may (and should) configure multiple keywords depending on your audience demographics. All messages must be under 160 characters and meet the specific requirements detailed below:

  • Standard Outbound Messages
    • These will be specific to your program and what your use case is. You do not need to provide all of your messages that you plan on sending but you should provide an example of each type of message that you plan on sending. If you are sending in multiple languages you should provide a version for each language.
  • Opt-in Confirmation Message
    • This is the message that must be sent whenever you opt someone into your program
  • Help
    • This message must be sent when any of the required keywords for help in the country you are registering for are sent back to you. In the US this is “help” and in Mexico this is “ayuda” for example.
  • Stop
    • The “Stop message” is the response that is required to be sent to end-users when they text the keyword “STOP” (or similar keywords). End-users are required to be opted out of further messages when they text the STOP (or equivalent) keyword to your number and you are required to confirm with them that they will no longer receive messages for the program.

Let’s review the specific requirements for each in detail

Standard Outbound Message Types:

Your short code application must include examples of all of the message TYPES that you plan to use but it does not need to include ALL of the possible examples. This is especially true with promotional messages that can have a lot more variability. You need to give the reviewers enough examples that you are illustrating how you will be using the short code.

The two main types of messages are Promotional and Transactional, let’s break each down.

Promotional: This includes any type of messaging that has content related to sales or other offers. This does not only have to be related to content that requires a purchase. This could also be marketing new features, announcing the launch of a new program, or other messaging that could be construed as marketing. Remember, there are humans reviewing these registrations so make sure that any messages that you are using will not be misconstrued as a type of message that you are not registering for.

Transactional: There are a lot of different types of messages that can be considered transactional. The simple way of thinking about it is that anything that is NOT promotional, is transactional. Some examples of transactional messages include:

  • Account Notifications
  • Status notifications about an account that the recipient is a part of or owns
  • Customer Care
  • Communications related to support or account management
  • Delivery Notifications
  • Notifications about the status of a delivery of a product or service
  • Fraud Alert Messaging
  • Notifications related to potential fraudulent activity
  • Security Alerts
  • Notifications related to a compromised software or hardware system that requires recipients to take an action
  • Two Factor Authentication(2FA) or One-Time Password(OTP)
  • Authentication, account verifications, or one-time passcode

While these two types can be mixed on a single short code we strongly recommend against this:

  • Mixing message types on a single code is not as resilient should something happen to your code or if your code is ever audited.
  • It could prevent your recipients from accessing their account if they opt out of a code delivering OTP and marketing messages and you are not self managing your opt out process.
  • It can also impacts the throughput — if, during a marketing campaign using the same short code, that campaign is exhausting the throughput of the short code, the transactional use case will be impacted by that capacity limitation.

Best practices:

  • Include your Program (brand) name in each message
  • If you have multiple templates, include an example of all of the types you are registering for.
  • Read them all and make sure that they are clearly a part of the message type/use case that you are registering for
  • If your messages will include variables, it’s fine to use either placeholder values or variables.
    • For example, both of the following are acceptable: “Hello John. Your one-time password is 654321” and “Hello [first_name]. Your one-time password is [otp code] .”
  • Make sure they are all less than 160 characters
  • Do not use unbranded link shorteners
    • If you have to use a shortener make sure that it is branded and that there are not multiple redirects. Also make sure to provide examples of the branded shortened domain so that it is on file with the carriers

Confirmation:

Provide the exact message that will be sent back to your end-users letting them know that they have successfully registered.

Example:
“Welcome to AnyCo! Reply “YES” to confirm your subscription and get special offers once a month. Msg & data rates may apply. Text ‘STOP’ to opt out.”

You must include:

  • The message has to be a minimum of 20 characters and a maximum of 160 characters
  • Brand Name
  • Opt-in confirmation messages are required for all use cases, even one-time passwords. However, for OTP-type use cases, the act of end users requesting an OTP is essentially an opt-in and associated confirmation message which means you don’t need another unique confirmation message on top of the OTP as long as the OTP message is compliant.
    • A double opt-in confirmation message flow, where the recipient will text back “YES” to confirm that they did want to register, is only required for shopping cart reminder use cases. However we do recommend it as a best practice for all use cases since it ensures you are maintaining a clean database of numbers.
  • Include “Msg & data rates may apply” as seen in the example
  • Include opt-out language as seen in the example

Help:

Provide the exact message that will be sent back to your end-users when they request “help” via keyword response.

Example:
“ExampleCorp Account Alerts: For help call 1-888-555-0142 or go to example.com. Msg&data rates may apply. Text STOP to cancel.”

You must include:

  • The message has to be a minimum of 20 characters and a maximum of 160 characters
  • The message must include:
    • Program (brand) name OR product description.
    • Additional customer care contact information.
      • It is mandatory to include a phone number and/or email for end-user support
  • Include “Msg & data rates may apply” as seen in the example

Stop:

Provide the exact message that will be sent back to your end-users when they request to be opted out of your program. You are allowed to include instructions on how to resubscribe but be sure to keep the total message length under 160 characters while still including all of the required components.

Example:
“You are unsubscribed from ExampleCorp Account Alerts. Text JOIN to resubscribe. No more messages will be sent. Reply HELP for help or call 1-888-555-0142.“

You must include:

  • The message has to be a minimum of 20 characters and a maximum of 160 characters
  • The message must include:
    • Program (brand) name OR product description
    • Confirmation that no further messages will be delivered

How to Apply for a Short Code

Step 1: Create a Case in AWS Support Center

Currently short codes are only available by opening a case. The first step to register a short code is to open a short code request case in the AWS Support Center, providing detailed information about your use case and opt-in policies. A request must be opened for each country in which you want a short code. Each country has their own registration process and requirements so having a case for each allows for much easier tracking and updating as there are communications going back and forth between you, the customer, support, and any downstream clarifications that may come back.

Step 2: Complete the Short Code Application

Each country may have different requirements for the information you need to fill out as well as supporting documents you may need to provide. Make sure that everything you submit is 100% correct to your knowledge, as any missing information or information that needs to be corrected extends the time it takes to receive your short code. The minimum information you will need to provide is:

  • Company information such as legal name and tax ID
  • Use case details
  • Opt-in workflow documentation
  • Privacy Policy and Terms of Service
  • Message templates (including CONFIRMATION, HELP, and STOP responses)

The short code application form contains all of the information that we send to the carriers to let them know about your use case. For this reason, the form must be filled in completely, and the responses must all be compliant with the requirements of the carriers. The high-level process looks like the below:

  1. Submit your request for a short code through the AWS case console
  2. AWS will respond back with the appropriate form and required supporting documentation for the country you are applying for.
  3. Fill out the document with all of the information and include any supporting documents required. Don’t leave anything blank, there are no exceptions to these forms.
  4. AWS will validate that the form is complete and supporting documentation is included. We do not review your documents, so make sure that to your knowledge they are correct.
  5. AWS will submit your form to be carefully reviewed.
  6. The registrar reviews documentation to ensure that it is compliant with all carrier and country requirements.
    1. This step may have several rounds of revisions. If you requested through an AWS support case, make sure you are CC’d to updates so you can quickly address any feedback from external reviewers as delays in responses increase the timeline.
  7. Once your documentation is considered compliant your company will be submitted for vetting. This is similar to a credit check process where your data will be validated and you will need to prove you are a member of your company through a domain validation email.
  8. Once the vetting process is completed your short code moves to “carrier review” state — this is when the timer starts. Continue to monitor your case for any needed updates.
  9. The short code numbers are confirmed and the number is provisioned to your account and billing starts. This does not mean that the number can be used however as there are configurations with carriers that need to be completed.
  10. Carriers approve and provision the SC to their network to make it active
    1. This is the final external provider phase. This process requires each individual carrier to review your registration, approve it, and then to provision the code to their networks so that it is active when handed over to you. In rare cases, an individual carrier may reject your registration and request changes or additional information before they approve.
  11. Our SC partner informs us the SC is now approved and active on carrier networks
  12. AWS updates your case informing you that the SC is ready to use

Conclusion

Obtaining and using SMS short codes requires careful planning and adherence to the strict requirements set forth by the carriers. By following the guidance provided in this comprehensive guide, businesses can navigate the application process successfully and leverage the unique advantages of short codes for their SMS messaging needs.

Key to the successful procurement and usage of a short code is the establishment of compliant opt-in workflows, SMS-specific privacy policies and terms of service, as well as the preparation of required message templates. By meticulously addressing these prerequisites, businesses can streamline the application process and avoid costly delays or rejections.

The high bar for obtaining a short code exists to protect consumers from spam and abuse, ensuring that only approved and legitimate use cases are granted access to this powerful communication channel. While the application process may be time-consuming and complex, the benefits of using a short code – including high throughput, reliability, and an easily recognizable brand identifier – make it a valuable investment for businesses that need to communicate with their customers via SMS at scale.

Ultimately, the diligence required to obtain and properly utilize a short code pays dividends in the form of a highly effective and trustworthy SMS messaging channel. Following the guidance outlined in this document will position businesses for success in leveraging the power of short codes to connect with their customers in today’s digital landscape.