{"id":7031,"library":"azure-communication-sms","title":"Azure Communication SMS Client Library for Python","description":"The Azure Communication SMS client library for Python allows developers to integrate SMS messaging capabilities into their applications. It provides functionalities to send 1:1 and 1:N SMS messages via Azure Communication Services. The library is currently at version 1.1.0 and is part of the Azure SDK for Python, which typically sees regular updates, including new features and bug fixes, often on a monthly or bi-monthly cadence, alongside public preview releases for upcoming functionalities.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python","tags":["azure","communication","sms","messaging","cloud"],"install":[{"cmd":"pip install azure-communication-sms","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.8 or later.","package":"Python","optional":false},{"reason":"Required for Azure Active Directory (AAD) authentication (e.g., DefaultAzureCredential).","package":"azure-identity","optional":true},{"reason":"Core Azure SDK functionalities.","package":"azure-core","optional":false}],"imports":[{"symbol":"SmsClient","correct":"from azure.communication.sms import SmsClient"},{"note":"Required for Azure Active Directory (AAD) authentication.","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"}],"quickstart":{"code":"import os\nfrom azure.communication.sms import SmsClient\n\n# Retrieve the connection string from an environment variable\n# AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING is typically\n# 'endpoint=https://<your-resource-name>.communication.azure.com/;accesskey=<your-access-key>'\nconnection_string = os.environ.get('AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING', 'YOUR_CONNECTION_STRING')\n\n# Replace with your SMS enabled phone numbers\nfrom_phone_number = os.environ.get('AZURE_COMMUNICATION_SERVICE_FROM_PHONE_NUMBER', '+1XXXXXXXXX') # E.164 format\nto_phone_number = os.environ.get('AZURE_COMMUNICATION_SERVICE_TO_PHONE_NUMBER', '+1YYYYYYYYY')   # E.164 format\n\nif connection_string == 'YOUR_CONNECTION_STRING':\n    raise ValueError(\"Please set the AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING environment variable.\")\n\nif from_phone_number == '+1XXXXXXXXX':\n    raise ValueError(\"Please set the AZURE_COMMUNICATION_SERVICE_FROM_PHONE_NUMBER environment variable.\")\n\nif to_phone_number == '+1YYYYYYYYY':\n    raise ValueError(\"Please set the AZURE_COMMUNICATION_SERVICE_TO_PHONE_NUMBER environment variable.\")\n\ntry:\n    # Initialize the SmsClient with your connection string\n    sms_client = SmsClient.from_connection_string(connection_string)\n\n    # Send a 1:1 SMS message\n    send_result = sms_client.send(\n        from_=from_phone_number,\n        to=[to_phone_number],\n        message=\"Hello from Azure Communication Services!\",\n        enable_delivery_report=True\n    )\n\n    print(f\"SMS message sent. Results: {send_result}\")\n    for result in send_result:\n        if result.successful:\n            print(f\"  Message ID: {result.message_id}, To: {result.to}, Status: {result.http_status_code}\")\n        else:\n            print(f\"  Failed to send to {result.to}. Error: {result.error_message}, Status: {result.http_status_code}\")\n\nexcept Exception as ex:\n    print(f\"An error occurred: {ex}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `SmsClient` using a connection string and send a single SMS message. It is crucial to replace placeholder environment variables with your actual Azure Communication Services connection string, and SMS-enabled phone numbers in E.164 format. The `enable_delivery_report` flag is set to `True` to allow tracking message delivery status."},"warnings":[{"fix":"Ensure all phone numbers adhere strictly to the E.164 format, including the '+' prefix.","message":"Phone numbers must be provided in the E.164 international standard format (e.g., +14255550123) for both `from_` and `to` parameters. Incorrect formats will lead to delivery failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify SMS enablement and phone number status in the Azure Portal under your Communication Services resource. For toll-free numbers, ensure verification is complete.","message":"The Azure Communication Services resource and the associated phone number must be properly configured for SMS capabilities and verified. Toll-free numbers, in particular, require verification to avoid messages being blocked by carriers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement retry logic with exponential backoff, send messages in batches, monitor ACS quotas, and validate phone numbers before sending to reduce delivery failures.","message":"Sending large volumes of SMS messages may encounter carrier throttling or Azure Communication Services throughput limits, resulting in delivery failures (e.g., '5000 Message failed to deliver').","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-check the connection string for accuracy, ensure required AAD environment variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) are set if using `DefaultAzureCredential`, and verify that the principal has the 'Azure Communication Services Contributor' role or equivalent permissions.","message":"Authentication failures (e.g., `401 Unauthorized`, `403 Forbidden`) are common if the connection string is incorrect, environment variables for Azure Active Directory are missing, or the principal lacks sufficient permissions on the Communication Services resource.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that the `AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING` environment variable is correctly set and matches your Communication Services resource. If using AAD, ensure `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET` are correct and the service principal has the 'Azure Communication Services Contributor' role.","cause":"The connection string or Azure Active Directory credentials provided are invalid, expired, or lack necessary permissions.","error":"azure.core.exceptions.HttpResponseError: (Unauthorized) The request couldn't be authenticated."},{"fix":"Grant the appropriate permissions, such as 'Azure Communication Services Contributor', to the identity being used for authentication on your Azure Communication Services resource.","cause":"The authenticated identity does not have the necessary role-based access control (RBAC) permissions to send SMS messages.","error":"azure.core.exceptions.HttpResponseError: (Forbidden) The request was authorized, but has insufficient permissions to carry out this operation."},{"fix":"Ensure all phone numbers are in E.164 format (e.g., `+14255550123`). Trim and normalize all input strings to remove any invisible or non-printable characters.","cause":"Typically caused by incorrect phone number formatting (not E.164) or unexpected/hidden characters in `from_`, `to`, or `message` fields.","error":"azure.core.exceptions.HttpResponseError: (InvalidInput) The request received couldn't be understood by the service. Double check the documentation and ensure you're sending everything required and in the correct format."},{"fix":"Review best practices: implement retry logic with exponential backoff, send messages in batches, monitor ACS quotas, and ensure `from_` and `to` numbers are valid, mobile, and SMS-capable. Check if the recipient has opted out.","cause":"A generic SMS delivery failure, often due to carrier throttling, Azure Communication Services throughput limits, temporary network issues, or sending to an invalid/inactive phone number.","error":"SmsSendResult.successful is False, SmsSendResult.error_message contains '5000 Message failed to deliver'"}]}