Azure Communication Services technical documentation table of contents update
Technical documentation is like a map for using a platform—whether you're building services, solving problems, or learning new features, great documentation shows you the way to the solution you need. But what good is a map if it’s hard to read or confusing to follow? That’s why easy-to-navigate documentation is so important. It saves time, reduces frustration, and helps users focus on what they want to achieve. Azure Communication Services is a powerful platform, and powerful platforms require great documentation for both new and experienced developers. Our customers tell us consistently that our docs are a crucial part of their experience of using our platform. Some studies suggest that documentation and samples are the most important elements of a great developer experience. In this update, we’re excited to share how we’ve improved our technical documentation’s navigation to make it quicker and simpler than ever to find the information you need when you need it. Why did we change? In order for our content to be useful to you, it first needs to be findable. When we launched Azure Communication Services, the small number of articles on our site made it easy to navigate and find relevant content. As we’ve grown, though, our content became harder to find for users due to the quantity of articles they need to navigate. To refresh your memory, the table of contents on our docs site used to be structured with these base categories: Overview Quickstart Tutorials Samples Concepts Resources References These directory names describ e the type of content they contain. This structure is a very useful model for products with a clearly-defined set of use cases, where typically a customer’s job-to-be-done is more constrained, but it breaks down when used for complex, powerful platforms that support a broad range of use cases in the way that Azure Communication Services does. We tried a number of small-scale changes to address the problems people were having on our site, such as having certain directories default to open on page load, but as the site grew, we became concerned that our site navigation model was becoming confusing to users and having a negative impact on their experience with our product. We decided to test that hypothesis and consider different structures that might serve our content and our customers better. Our user research team interviewed 18 customers with varying levels of experience on our platform. The research uncovered several problems that customers were having with the way our docs navigation was structured. From confusing folder titles, to related topics being far away from each other in the nav model, to general confusion around what folder titles meant, to problems finding some of the most basic information about using our platform, and a host of other issues, our user research made it clear to us that we had a problem that we needed to fix for our users. What did we change in this release? To help address these issues, we made a few key changes to make our table of contents simpler and easier to navigate. The changes we made were strictly to site navigation, not page content, and they include: We've restructured the root-level navigation to be focused on communication modality and feature type, rather than content type, to better model our customers' jobs-to-be-done. Topics include All supported communication channels Horizontal features that span more than one channel Topics of special interest to our customers, like AI Basic needs, like troubleshooting and support This will allow customers to more easily find the content they need by focusing on the job they need to do, rather than on the content type. We've simplified the overview and fundamentals sections to make the site less overwhelming on first load. We've surfaced features that customers told us were difficult to find, such as UI Library, Teams interop, and Job router. We've organized the content within each directory to roughly follow a beginner->expert path to make content more linear, and to make it easier for a user to find the next step in completing their task. We've removed unnecessary layers in our nav, making content easier to find. We've added a link to pricing information to each primitive to address a common customer complaint, that pricing information is difficult to find and understand. We've combined quickstarts, samples, and tutorials into one directory per primitive, called "Samples and tutorials", to address a customer complaint that our category names were confusing. We added a directory to each primitive for Resources, to keep important information close by. We added root-level directories for Common Scenarios, Troubleshooting, and Help and support. We did a full pass across all TOC entries to ensure correct casing, and edited entries for readability and consistency with page content, as well as for length to adhere to Microsoft guidelines and improve readability. These changes have led us to a structure that we feel less taxing for the reader, especially on first visit, maps more closely to the customer’s mental model of the information by focusing on the job-to-be-done rather than content type, helps lead them through the content from easiest to hardest, helps make it easier for them to find the information they need when they need it, and helps remind them of all the different features we support. Here’s what the table of contents looks like on page load as of Feb 6: These changes are live now. You can see them on the Azure Communication Services Technical documentation site. What’s next: In the coming weeks we will continue to make refinements based on customer feedback and our assessment of usage metrics. Our content team will begin updating article content to improve readability and enhance learning. We will be monitoring our changes and seeking your feedback. How will we monitor the effectiveness of our changes? To track the effectiveness of our changes and to be sure we haven’t regressed, we’ll be tracking a few key metrics Bounce rates: We’ll be on the lookout for an increase in bounce rates, which would indicate that customers are frequently landing on pages that don’t meet their expectations. Page Views: We’ll be tracking the number of page views for our most-visited pages across different features. A decrease in page views for these pages will be an indicator that customers are not able to find pages that had previously been popular. Customer Interviews: We will be reaching out to some of you to get your impressions of the new structure of our content over the coming weeks. Customer Surveys: We've created a survey that you can use to give us your feedback. We'll also be adding this link to select pages to allow you to tell us what you think of our changes while you're using them! So, give our new site navigation a try, and please don’t hesitate to share your feedback either by filling out our survey or by sending an email to acs-docs-feedback@microsoft.com. We look forward to hearing from you! AGuest Post: Send emails with PowerShell and managed identity using Azure Communication Services
Today, we’re featuring a guest author, Luke Murray, a Microsoft Most Valuable Professional (MVP) for Azure. He’s written an article we’re sharing below, focused on Azure Communication Services Email and PowerShell. We’ll turn it over to Luke to share more! Azure Communication Services brings rich communication APIs to all your apps across any device on any platform, using the same reliable and secure infrastructure that powers Microsoft Teams. Please follow these steps to set up Azure Communication Services resources in the Azure portal as pre-requisites for sending an email. 1. Create Azure Communication Services resource. 2.Create Email Communication Service. 3. Connect them, you can use a free Azure supplied domain name, or bring in your own custom domain. Today, we will explore using Email as part of Azure Communication Services, using their REST API and PowerShell to send an email. In this example, I will access a token from Azure Communication Services. I will make a GET request to the identity endpoint of Azure Communication Services using the OAuth identity from the system-managed identity. This will return a token we can use to authenticate against the REST API. Here's a step-by-step explanation of the script: The script first defines the subject and body of the email. The body is an HTML string that contains the email content. It checks if the email body is not empty. If the email body is not empty, it gets an access token from Azure Communication Services. This is done by making a GET request to the identity endpoint of Azure Communication Services. The access token is then printed to the console. If there's an error retrieving the access token, the script catches the exception and prints the error message and response details on the console. The script then constructs the URI for the email-sending endpoint and defines the headers for the REST API call. The headers include the content type and the access token that was obtained in the authorization header. The script defines the body for the REST API call. This includes the sender address, the email content (subject and body), the recipients, the reply-to address, and a flag to disable user engagement tracking. The script then converts the PowerShell object to JSON and attempts to send the email by making a POST request to the email-sending endpoint. The request and response details are logged to the console. If the email is sent incorrectly, the script catches the exception and logs the error message and stack trace to the console. Further information on the authentication process: The script first defines the resource ID for Azure Communication Services and the communication endpoint URL. It then constructs the URI for the identity endpoint. This URI includes the environment variable IDENTITY_ENDPOINT (automatically set by Azure when using Managed Identity) and the resource ID. The script then attempts to get an access token from the identity endpoint. It does this by sending a GET request to the identity endpoint with a header that includes Metadata: true. This tells the identity endpoint that the request is coming from within Azure. If the request is successful, the response will include an access token, which is then extracted from it. This access token can then be used to authenticate requests to Azure Communication Services. The token tells Azure Communication Services that the request comes from an authenticated source (in this case, the Managed Identity) and should be allowed. (This authentication was initially written to be used in an Azure Automation Runbook, with the System Managed Identity assigned Contributor rights to the Azure Communication Services resource (not the Email Communication Services) Here is the PowerShell script to send an email using Azure Communication Services using the System Managed identity of an Azure Automation account: $emailSubject = "Important: Server Maintenance Notification" $EmailRecipient = "ituser@contoso.com" $emailBody = @" <html> <body> <p>Dear User,</p> <p>This is to inform you that a <b><i>server maintenance is scheduled for the next week</i></b>.</p> <p>The servers will be down from 10:00 PM to 2:00 AM.</p> <p>Please save your work and log off during this period to avoid any data loss.</p> <p>If you have any questions or concerns, please contact our IT Support team.</p> <p>Thank you for your understanding and cooperation.</p> <p>Best Regards,</p> <p>IT Support Team</p> </body> </html> "@ if ($emailBody -ne "") { Write-Output $emailBody # Define the resource ID for Azure Communication Services $ResourceID = 'https://communication.azure.com' # Define the communication endpoint URL $communicationendpointurl = "azcomm-contoso.australia.communication.azure.com" # Update with your communication endpoint URL # Construct the URI for the identity endpoint $Uri = "$($env:IDENTITY_ENDPOINT)?api-version=2018-02-01&resource=$ResourceID" # Debug output # Print the constructed URI and headers Write-Output "URI: $Uri" Write-Output "Headers: @{ Metadata = 'true' }" # Try to get the access token try { # Invoke a GET request to the identity endpoint to get the access token $AzToken = Invoke-WebRequest -Uri $Uri -Method GET -Headers @{ Metadata = "true" } -UseBasicParsing | Select-Object -ExpandProperty Content | ConvertFrom-Json | Select-Object -ExpandProperty access_token # Print the obtained access token Write-Output "Access Token: $AzToken" } catch { # If there's an error, print the error message and response details Write-Error "Failed to get access token: $_" Write-Output "Response Status Code: $($_.Exception.Response.StatusCode.Value__)" Write-Output "Response Status Description: $($_.Exception.Response.StatusDescription)" Write-Output "Response Content: $($_.Exception.Response.GetResponseStream() | %{ $_.ReadToEnd() })" } # Construct the URI for the email sending endpoint $uri = "https://$communicationendpointurl/emails:send?api-version=2023-03-31" # Define the headers for the REST API call # Include the content type and the obtained access token in the Authorization header $headers = @{ "Content-Type" = "application/json" "Authorization" = "Bearer $AzToken" } # Define the body for the REST API call $apiResponse = @{ headers = @{ id = (New-Guid).Guid } senderAddress = 'DoNotReply@7647475b-a51b-4901-8674-917e6abea743.azurecomm.net' content = @{ subject = $emailSubject html = $emailBody } recipients = @{ to = @( @{ address = $EmailRecipient displayName = $EmailRecipient } ) } replyTo = @( @{ address = "example@contoso.com" displayName = "Contoso" } ) userEngagementTrackingDisabled = $true } # Convert the PowerShell object to JSON $body = $apiResponse | ConvertTo-Json -Depth 10 # Send the email try { # Log the request details Write-Output "Sending email..." Write-Output "URI: $uri" Write-Output "Headers: $headers" Write-Output "Body: $body" # Make the request $response = Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body -UseBasicParsing # Log the response Write-Output "Response: $response" # Return the response $response } catch { # Log the error Write-Error "Failed to send email: $_" Write-Output "Exception Message: $($_.Exception.Message)" Write-Output "Exception StackTrace: $($_.Exception.StackTrace)" } } You can run this script in an Azure Automation Runbook (and theoretically in an Azure Function) to send an email using Azure Communication Services and the System Managed Identity—and there is no need to maintain or store client secrets! I did a previous article: Deploying and Testing Azure Email Communication Services that uses Azure Service Principal for authentication. In this blog, we use OAuth using a System Assigned Managed Identity.ACS Email now Generally Available in Azure Government
Microsoft today announced the General Availability (GA) of its Email Communication Service within Azure Government, a milestone that marks a significant advancement in secure and compliant digital communication for U.S. federal, state, and local government agencies. This release also includes FedRAMP High authorization, aligning the service with the most rigorous standards for cloud security and data protection. The Email Communication Service, part of Azure Communication Services (ACS), enables government customers to reliably send high-scale, programmatic email communications -- whether transactional, informational, promotional, or mission-critical -- while ensuring compliance with federal mandates and cybersecurity frameworks. Key Benefits for Government Customers: FedRAMP High Authorization: Provides assurance for handling Controlled Unclassified Information (CUI) and other sensitive government data. Built for Mission-Critical Communication: Enables reliable email delivery for scenarios like citizen engagement, emergency notifications, program updates, and case management. Scalable, Secure, and Compliant: Leverages the resiliency and compliance of Azure Government infrastructure, including FIPS 140-2 encryption, data residency, and advanced DDoS protection. Integration Ready: Seamlessly integrates with existing systems, applications, and services through REST APIs and SDKs, enabling faster modernization of legacy communication workflows. For more information, detailed guidance, or to get started, government customers are encouraged to explore Azure Communication Services documentation for additional support.Build an AI Email Responder with OpenAI and Azure Communication Services
Customer support is vital but often bogged down by repetitive queries like password resets, billing issues, and basic troubleshooting. Automating these common responses frees up valuable time, allowing your team to focus on more complex tasks. In this tutorial, we'll build an AI-Powered Email Responder that leverages OpenAI’s GPT models to craft intelligent replies and Azure Communication Services to handle email delivery seamlessly. How It Works Here's how our AI-powered responder works: Input Query: Enter the recipient’s email, subject, and customer query. Generate Response: GPT quickly drafts a detailed reply. Review & Edit: You can adjust the response as needed. Send Email: Azure Communication Services dispatches the message instantly. Prefer a walkthrough? Watch the full video demo to see the app in action with live code explanations. Tools We’re Using This project is ideal for developers, solution architects, or anyone exploring practical AI integrations with minimal setup. We will utilize the following services: Azure OpenAI Service: Provides state-of-the-art GPT models capable of intelligent text generation and conversational responses. Azure Communication Services: Delivers reliable, scalable, and secure email capabilities suitable for enterprise-level applications. Azure Environment Setup Follow these steps to configure your Azure environment: 1. Azure OpenAI Service Go to Azure Portal and create an "Azure OpenAI" resource (see how: docs). In Azure AI Studio, deploy your selected GPT model (such as GPT-4o). Retrieve your API Key, Endpoint URL, and Deployment ID. 2. Azure Communication Services In Azure Portal, create "Communication Services" and "Email Communication Services" resources (see how: docs or video). Provision a free Azure subdomain and obtain your verified sender email address. Copy your Connection String from your Communication Services resource for later use. Coding the Application You can view the full project on GitHub to access the complete, ready-to-use code, and skip the manual steps — or follow the highlights below to understand how everything works. Create two files; an .env file and app.py file in your preferred IDE. 3. Environment Variables (.env file): Replace OpenAI and Azure Communication Services configurations with your credentials obtained in the above steps. Store sensitive credentials securely: # OpenAI Configuration OPENAI_API_KEY=your_azure_openai_key OPENAI_ENDPOINT=https://your-openai-resource.openai.azure.com/ # Azure Communication Services Configuration ACS_CONNECTION_STRING=endpoint=https://your-resource.communication.azure.com/;accesskey=your_key ACS_SENDER_EMAIL=DoNotReply@your-resource.communication.azure.com RECIPIENT_EMAIL=someone@example.com 4. Python Application (app.py): The app.py file provided uses Streamlit to create an intuitive and interactive user interface. Users input recipient details and customer queries directly through the web-based form. Behind the scenes, the app makes API calls to Azure OpenAI, sending the customer's query to generate a contextually relevant reply using the GPT model. It also leverages Azure Communication Services API to dispatch the finalized email instantly to the specified recipient. You can access the full detailed code and in-depth explanations in the GitHub repository. Below is the breakdown of the app’s core functionality, highlighting how each user action maps to backend logic for generating, editing, and sending AI-crafted responses. 🧠 Generate Response We send the user’s query to Azure OpenAI with a prompt like: "You are a support agent. Respond only with the email body. Be concise, helpful, and use numbered steps if needed." 💬 Preview and Edit The AI-generated response is displayed in a text area, allowing human review and manual editing. ✉️ Send via Azure Communication Services Email We use the EmailClient from the azure.communication.email package to send the final message. Ideas for Extension The app provides a strong foundation for exploring AI automation using large language models and email APIs, and it can easily be extended with additional capabilities such as: RAG (Retrieval-Augmented Generation): Integrate with internal knowledge bases for more tailored answers. Ticketing Integration: Connect directly with your existing support or ticketing system to fetch queries and update responses automatically. Role-based Prompts: Fine-tune the AI’s tone based on use case (e.g., sales vs. tech support). Analytics & Logs: Track usage and monitor AI-generated replies for compliance and quality. Final Thoughts This project shows how easy it is to bring real AI capabilities into customer workflows using Azure. You get powerful language understanding via OpenAI and production-grade email delivery through Azure Communication Services—all in a minimal Python app. Whether you're prototyping a support bot or building internal tools, this project offers a practical entry point into real-world AI automation. Get started by exploring the GitHub repository.
Moving Email Traffic from Exchange to Azure Communication Services
This article describes the important steps and considerations for transitioning from Exchange Online or other on-premises solutions to the Azure Communication Services email platform. It is also relevant for customers migrating from other mail solutions, whether on-premises or hybrid, to Azure Communication Services.Get more from your Email logs with Azure Communication Services
If you're sending emails with Azure Communication Services, you already know how powerful the platform is for delivering messages at scale. But what happens after you hit send? In our latest video, we walk through how to unlock insights from your email activity using logs and telemetry in the Azure portal. Whether you're tracking delivery success, debugging failures, or analyzing engagement, this guide helps you get started with the tools that matter. Why email telemetry matters Understanding how your emails perform is critical—especially when you're running campaigns, monitoring sender reputation, or troubleshooting delivery issues. With Azure Communication Services, you can tap into Log Analytics for real-time visibility into: Delivery and failure rates Suppression reasons User engagement (opens, clicks) Correlation IDs for tracing specific messages While this video focuses on email, the same logging and telemetry setup applies to other Azure Communication Services like SMS, voice, and chat—so once you’ve got the hang of it, you can reuse the same approach across channels. Step 1: Set up your log analytics workspace Before you can start querying logs, you’ll need a place to store them. In the Azure portal: Create a Log Analytics workspace. Choose your subscription and resource group. Name your workspace and click Review + Create. This workspace acts as the central hub for all your telemetry data. A GIF of a user creating a Log Analytics Workspace in the Azure Portal. Step 2: Configure diagnostic settings Next, connect your Azure Communication Services resource to the workspace: Navigate to your Communication Services resource. Under Monitoring, select Diagnostic settings. Add a new setting and choose the email-related log categories: Send mail logs Delivery status updates User engagement logs Point them to your Log Analytics workspace and save. Now your logs will start to flow into the workspace automatically. Step 3: Explore insights in the portal With logs enabled, you can start exploring your data: Use the Insights tab for a high-level overview of delivery and engagement. Filter by sender address or time range. View metrics like delivery success, failures, and clicks. This is great for quick checks—but for deeper analysis, you can write custom queries. delivered,failed, and suppressed. Step 4: Run custom queries with KQL In the Logs section of your workspace, use Kusto Query Language (KQL) to dig into the details: Find suppressed or bounced emails Trace delivery failures with correlation IDs Identify which links were clicked in a campaign Export results to CSV, Power BI, or Excel The video walks through several examples, including how to change sample queries and build your own. . It shows a sample query looking for logs that have a specific RecipientId and UserAgent Bonus: Reuse this setup across Azure Communication Services channels While this walkthrough focuses on email, the same telemetry setup works for other Azure Communication Services channels. Whether you're building with SMS, voice, or chat, you can use Log Analytics to monitor performance, debug issues, and improve user experience. Watch the full walkthrough Want to see it in action? Watch the preceding full video above for a step-by-step demo of everything covered here. And if you’re already using logs in creative ways—or have questions about telemetry for other Azure Communication Services features—drop us a comment. We’d love to hear how you use it!
The U.S. Small Business Administration integrates Azure Communication Services, sending critical information to millions of Americans more quickly
At the U.S. Small Business Administration (SBA), we faced significant challenges with our existing mass communications solution. Our organization is the only cabinet-level federal agency fully dedicated to small business counseling, capital, and contracting expertise. We also offer disaster assistance for homeowners, renters, nonprofits, and businesses of all sizes affected by disaster recovery-related assistance, so we needed a scalable platform that could efficiently send critical information to millions of Americans, especially during times of disaster recovery and urgent business support. We also required a platform that could do this quickly and was cost-effective, while also allowing us to further centralize operational capabilities within Dynamics 365, which would help teams internally. Centralizing capabilities means finding ways to consolidate information in one system, creating a single-pane-of-glass experience, so people here don't have to leave Dynamics 365 and can have everything they need without jumping from one system to another to get their work done. How the U.S. SBA implemented Azure Communication Services into their existing systems After evaluating various options, we decided to implement Microsoft Azure Communication Services for email mass communications. It was an easy decision for us because Azure Communication Services meets our needs in the following ways: Speed: We can send out one million emails in under 20 minutes. Cost: Azure Comms is significantly more affordable than competing solutions. Integration: Azure Comms seamlessly integrates into Dynamics 365 as a complementary feature. How SBA implemented Microsoft Azure Communication Services into Dynamics 365 To implement Azure Communication Services, we worked closely with the product group to integrate it into Dynamics 365, which we use to handle large campaigns. Dynamics 365 also centralizes knowledge base reference materials for agents and customer service representatives. With the Azure Comms integration into Dynamics 365, we focused on refining the system’s outbound email velocity over the course of several months. Within 30 days, we successfully transitioned over 50 campaign teams to Dynamics 365 while collaborating with Microsoft to integrate Azure Communications Services into the platform. Some challenges arose, but we collaborated with the product group to incorporate improvements and refine its capabilities over time. We are also leveraging AI for sentiment analysis and process automation to meet various internal and external requirements. We recently implemented Copilot in Dynamics 365, for example, which is safe, secure, and free within our D365 licensing. We've done so much work in bringing people’s knowledge base materials into the platform that employees have been able to immediately see the benefits of using Copilot: Ask feature on Copilot makes it easy to submit a prompt and get help with a specific task. Automatic summarization of a specific case, which helps our agents and service representatives get up to speed immediately and be more responsive. Email drafting is now much easier and faster with Copilot because it allows anyone to write an email from scratch in a fraction of the time. Language translation via Copilot allows us to toggle on the fly between different languages and translate a different language into English--and vice versa. A crucial skill set in our organization is language proficiency, particularly in Spanish. Historically, we've had to either hire representatives with Spanish language skills or rely on contracted services to meet this need. If we receive an email in Spanish, an English-speaking team member can translate it into English and respond in Spanish, helping to reduce our reliance on individuals with specialized language skills. "It’s difficult to predict when we’ll receive an email in a different language. But now, we can translate messages instantly and respond in the sender’s native language—removing barriers and streamlining communication like never before. It’s an incredible advantage—one that doesn’t get nearly enough attention. Microsoft Dynamics 365 Copilot’s translation capability isn’t just convenient; it’s a game-changer."" The results of implementing ACS into Dynamics 365 There are many benefits to using Azure Communication Services and integrating it into Dynamics 365. ACS has empowered our campaign teams to address time-sensitive requests efficiently, enabling us to send out critical communications within minutes or a few hours—rather than days. We have sent over 300 million emails through Azure Comms since its implementation in March 2023. Looking ahead We plan to extend the functionality of Azure Communication Services to support internal-facing communications in the near future, including: Exploring additional communication methods (e.g., SMS, phone) to provide omnichannel, preference-oriented campaigns. Leveraging virtual appointment options to enhance service delivery. Developing more refined metrics, such as open and click rates, for better insights into the impact of our mass communication efforts. Azure Communication Services has transformed our ability to respond promptly to diverse mass communication needs, even with minimal notice. Our journey with Azure Comms showcases the power of cloud-based communication solutions in enhancing organizational efficiency and effectiveness. The more people grasp the features of Dynamics 365 and its ease of integration with systems like Azure Communication Services, the better they understand its quantifiable benefits and true value. A common misconception is that adopting Dynamics 365 means being restricted to Microsoft-only systems—but that’s not the case. You can integrate a different phone system, leverage various databases, and customize the platform to suit your needs. Whether it's delivering crucial information to frontline workers or enabling responsive services, Dynamics 365 is far more than just a customer relationship management (CRM) system—it's a versatile, customizable solution designed to support a wide range of business requirements and operational needs.
