Azure Communication Email

Warnings

• breaking Major breaking changes occurred around version 1.0.0, primarily shifting the `send` method to a Long-Running Operation (LRO) pattern where `client.begin_send()` returns a poller object. Direct calls to `send()` for immediate results are no longer supported. Additionally, property names like `sender` were renamed to `senderAddress`, and `email` within recipient objects to `address`.
  Fix: Update your code to use `client.begin_send()` which returns a poller. Call `poller.result()` to await the email sending outcome. Adjust property names like `sender` to `senderAddress` and `email` to `address` in your email message construction. Refer to the official changelog for specific version changes.
• gotcha For production workloads and higher email sending limits, always use a custom domain with properly configured SPF, DKIM, and DMARC records. Azure Managed Domains are primarily intended for testing purposes and have lower sending limits, which can lead to emails being throttled or marked as spam.
  Fix: Configure a custom domain in your Azure Email Communication Services resource. Ensure all required DNS records (SPF, DKIM, DMARC) are correctly set up in your domain provider. For significantly higher volumes, you may need to request a quota increase through Azure support.
• gotcha While connection strings are simple for quickstarts, Microsoft recommends using Microsoft Entra ID (Azure Active Directory) authentication with `DefaultAzureCredential` for production applications. This enhances security by avoiding hardcoded secrets.
  Fix: Install `azure-identity` (`pip install azure-identity`) and configure your environment for `DefaultAzureCredential` (e.g., Managed Identity on Azure resources, environment variables for local development). Initialize the `EmailClient` with `EmailClient(endpoint=..., credential=DefaultAzureCredential())`.
• gotcha Email sending through Azure Communication Services requires a linked Email Communication Resource with an active, verified domain. Issues often arise from misconfigured domains or attempting to send from an unverified address.
  Fix: Ensure you have an Azure Communication Services resource linked to an Azure Email Communication Services resource, which in turn has a verified domain (either Azure Managed or Custom). The `senderAddress` in your email message must match a 'MailFrom' address associated with a verified domain.

Install

• pip install azure-communication-email Install stable release

Imports

• EmailClient

  from azure.communication.email import EmailClient

  The `aio` namespace is for asynchronous clients; the synchronous client is directly under `azure.communication.email`.
• EmailContent

  from azure.communication.email import EmailContent

• EmailRecipient

  from azure.communication.email import EmailRecipient

Quickstart

This quickstart demonstrates sending a basic email using a connection string for authentication. For production scenarios, it is recommended to use Azure Active Directory authentication via `DefaultAzureCredential` from the `azure-identity` library. Ensure your Communication Services resource, Email Communication Services resource, and a verified domain are configured in Azure.

import os
from azure.communication.email import EmailClient
from azure.identity import DefaultAzureCredential

try:
    # Authenticate using a connection string from an environment variable
    # Alternatively, use DefaultAzureCredential for Azure AD authentication
    connection_string = os.environ.get("ACS_CONNECTION_STRING", "")
    if connection_string:
        email_client = EmailClient.from_connection_string(connection_string)
    else:
        # Requires azure-identity to be installed: pip install azure-identity
        # And environment variables like AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET set
        email_client = EmailClient(endpoint="https://<your-acs-resource-name>.communication.azure.com", credential=DefaultAzureCredential())

    # Replace with your actual sender and recipient addresses
    sender_address = os.environ.get("SENDER_EMAIL_ADDRESS", "donotreply@yourverifieddomain.com")
    recipient_address = os.environ.get("RECIPIENT_EMAIL_ADDRESS", "recipient@example.com")

    message = {
        "senderAddress": sender_address,
        "recipients": {
            "to": [{"address": recipient_address}],
        },
        "content": {
            "subject": "Hello from Azure Communication Email",
            "plainText": "This is the plain text body of the email.",
            "html": "<html><h1>Hello!</h1><p>This is the <b>HTML</b> body.</p></html>"
        }
    }

    print("Sending email...")
    poller = email_client.begin_send(message)
    send_result = poller.result()

    if send_result:
        print(f"Email sent successfully with ID: {send_result['id']}")
    else:
        print("Email sending failed or result is None.")

except Exception as ex:
    print(f"Error sending email: {ex}")