Azure Communication Email client library for Python

This package contains a Python SDK for Azure Communication Services for Email.

Key concepts

The Azure Communication Email package is used to send emails to multiple types of recipients.

Getting started

Prerequisites

You need an Azure subscription, a Communication Service Resource, and an Email Communication Resource with an active Domain.

To create these resource, you can use the Azure Portal, the Azure PowerShell, or the .NET management client library.

Installing

Install the Azure Communication Email client library for Python with pip:

pip install azure-communication-email

Examples

EmailClient provides the functionality to send email messages.

Authentication

Email clients can be authenticated using the connection string acquired from an Azure Communication Resource in the Azure Portal.

from azure.communication.email import EmailClient

connection_string = "endpoint=https://<resource-name>.communication.azure.com/;accessKey=<Base64-Encoded-Key>"
client = EmailClient.from_connection_string(connection_string);

Alternatively, you can also use Active Directory authentication using DefaultAzureCredential.

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

# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
endpoint = "https://<resource-name>.communication.azure.com"
client = EmailClient(endpoint, DefaultAzureCredential())

Email clients can also be authenticated using an AzureKeyCredential.

from azure.communication.email import EmailClient
from azure.core.credentials import AzureKeyCredential

credential = AzureKeyCredential("<api_key>")
endpoint = "https://<resource-name>.communication.azure.com/"
client = EmailClient(endpoint, credential);

Send an Email Message

To send an email message, call the begin_send function from the EmailClient. This will return a poller. You can use this poller to check on the status of the operation and retrieve the result once it's finished.

message = {
    "content": {
        "subject": "This is the subject",
        "plainText": "This is the body",
        "html": "html><h1>This is the body</h1></html>"
    },
    "recipients": {
        "to": [
            {
                "address": "customer@domain.com",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "sender@contoso.com"
}

poller = email_client.begin_send(message)
result = poller.result()

Send an Email Message to Multiple Recipients

To send an email message to multiple recipients, add a object for each recipient type and an object for each recipient.

message = {
    "content": {
        "subject": "This is the subject",
        "plainText": "This is the body",
        "html": "html><h1>This is the body</h1></html>"
    },
    "recipients": {
        "to": [
            {"address": "customer@domain.com", "displayName": "Customer Name"},
            {"address": "customer2@domain.com", "displayName": "Customer Name 2"}
        ],
        "cc": [
            {"address": "ccCustomer@domain.com", "displayName": "CC Customer Name"},
            {"address": "ccCustomer2@domain.com", "displayName": "CC Customer Name 2"}
        ],
        "bcc": [
            {"address": "bccCustomer@domain.com", "displayName": "BCC Customer Name"},
            {"address": "bccCustomer2@domain.com", "displayName": "BCC Customer Name 2"}
        ]
    },
    "senderAddress": "sender@contoso.com"
}

poller = email_client.begin_send(message)
result = poller.result()

Send Email with Attachments

Azure Communication Services support sending email with attachments.

import base64

with open("C://readme.txt", "r") as file:
    file_contents = file.read()

file_bytes_b64 = base64.b64encode(bytes(file_contents, 'utf-8'))

message = {
    "content": {
        "subject": "This is the subject",
        "plainText": "This is the body",
        "html": "html><h1>This is the body</h1></html>"
    },
    "recipients": {
        "to": [
            {
                "address": "customer@domain.com",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "sender@contoso.com",
    "attachments": [
        {
            "name": "attachment.txt",
            "attachmentType": "text/plain",
            "contentInBase64": file_bytes_b64.decode()
        }
    ]
}

poller = email_client.begin_send(message)
result = poller.result()

Troubleshooting

Email operations will throw an exception if the request to the server fails. The Email client will raise exceptions defined in Azure Core.

from azure.core.exceptions import HttpResponseError

try:
    response = email_client.send(message)
except HttpResponseError as ex:
    print('Exception:')
    print(ex)

Next steps

• Read more about Email in Azure Communication Services

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Release History

1.0.0 (2023-03-31)

Features Added

The public release of the Azure Communication Services SDK for Email has the following features:

• send emails with a variety of options (multiple recipients, attachments, etc.)
• poll for the status of the email that was sent to track its progress

1.0.0b2 (2023-03-01)

Features Added

• Adding support for AAD token authentication
• Added the ability to specify the API version by an optional api_version keyword parameter.

Breaking Changes

• Made the SDK Model-less. Objects are now constructed using a dictionary instead of a model.
• Reworked the SDK to follow the LRO (long running operation) approach. The 'begin_send' method returns a poller that can be used to check for the status of sending the email and retrieve the result. The return object has been adjusted to fit this approach.
• The get_send_status method has been removed.
• The sender property has been changed to senderAddress.
• The email property under the recipient object has been changed to address.
• The attachmentType property under attachments has been changed to 'contentType'. This now accepts the attachment mime type.
• The contentBytesBase64 property under attachments has been changed to contentInBase64
• Custom headers in the email message are now key/value pairs.
• The importance property was removed. Email importance can now be specified through either the x-priority or x-msmail-priority custom headers.

Other Changes

Python 3.6 is no longer supported. Please use Python version 3.7 or later. For more details, please read our page on Azure SDK for Python version support policy.

1.0.0b1 (2022-08-09)

The first preview of the Azure Communication Email Client has the following features:

• send emails to multiple recipients with attachments
• get the status of a sent message