Registry / azure / azure-communication-email

azure-communication-email

library1.1.0pypypi✓ verified 24d ago

The `azure-communication-email` Python client library is part of the Azure Communication Services SDK, enabling developers to integrate email sending capabilities into their applications. It allows sending emails to single or multiple recipients, with support for plain text and HTML content, and attachments. This library helps manage email delivery status and is currently at version 1.1.0, with ongoing development as part of the broader Azure SDK for Python.

azure communication

pip install azure-communication-email

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AZURE-COMMUNICATIO

azure-communication-email

azurepythonv1.1.0

Install

2.5s avg

Import

396ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.414s · 23.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.5s · import 0.378s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

EmailClient

✓ from azure.communication.email import EmailClient

✗ from azure.communication.email.aio 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

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}")

Debug

Known issues

breakingMajor 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.

affects: >=1.0.0

gotchaFor 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.

affects: All versions

gotchaWhile 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())`.

affects: All versions

gotchaEmail 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'azure.communication'

The 'azure-communication-email' package is not installed in the environment.

fix

Install the package using 'pip install azure-communication-email'.

ModuleNotFoundError: No module named 'azure'

The 'azure' namespace package is not installed or not properly configured.

fix

Ensure that the 'azure' package is installed using 'pip install azure'.

AttributeError: 'str' object has no attribute 'id'

An incorrect object type is being used, leading to an attempt to access a non-existent attribute.

fix

Verify that the correct object type is being used and that it has the expected attributes.

DomainNotLinked – The specified sender domain has not been linked.

Even if your custom domain is verified in the Email Communication Service, it needs to be explicitly linked to your Azure Communication Services (ACS) resource to be used for sending emails.

fix

In the Azure portal, navigate to your Azure Communication Services resource, go to the 'Email' section, click 'Domains', and then 'Connect domain' to link your verified email domain to the Communication Service resource. Ensure the data location matches for both resources.

RestError: - Please try again after 0 seconds. (status 429)

This error, with a 429 (Too Many Requests) status code, indicates that you have exceeded the rate limits for sending emails from your Azure Communication Services resource.

fix

Implement retry logic with exponential backoff in your code, or space out your email sending operations to respect the per-minute and per-hour quotas defined by Azure Communication Services. Consider using a custom domain for higher rate limits.

Upgrade

Version history

1.1.0latest on PyPI · released Oct 17, 2025

Audit

Dependencies

azure-identityoptionalRecommended for Azure AD / Managed Identity authentication in production environments.

Agent activity

50 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Azure/azure-sdk-for-python ↗

packagehttps://pypi.org/project/azure-communication-email/ ↗

homepagehttps://azure.microsoft.com/en-us/services/communication-services/ ↗