Azure Communication Email客户端库 for Python

本软件包包含Azure Communication Services for Email的Python SDK。

关键概念

Azure Communication Email软件包用于向多种类型的收件人发送电子邮件。

入门

先决条件

您需要一个Azure订阅，一个通信服务资源，以及一个带有活动电子邮件通信资源和域。

要创建这些资源，您可以使用Azure门户、Azure PowerShell或.NET管理客户端库。

安装

使用pip安装Azure Communication Email Python客户端库。

pip install azure-communication-email

示例

EmailClient提供发送电子邮件消息的功能。

身份验证

可以使用从Azure门户获取的Azure Communication Resource的连接字符串来验证电子邮件客户端。

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);

或者，您也可以使用DefaultAzureCredential通过Active Directory进行身份验证。

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())

电子邮件客户端还可以使用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);

发送电子邮件消息

要发送电子邮件消息，请从EmailClient中调用begin_send函数。这将返回一个轮询器。您可以使用轮询器来检查操作状态，并在完成后检索结果。

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()

向多个收件人发送电子邮件消息

要向多个收件人发送电子邮件消息，为每种收件人类型添加一个对象，并为每个收件人添加一个对象。

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()

带有附件发送电子邮件

Azure Communication Services支持发送带附件的电子邮件。

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()

故障排除

如果服务器请求失败，电子邮件操作将抛出异常。电子邮件客户端将引发在Azure Core中定义的异常。

from azure.core.exceptions import HttpResponseError

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

下一步

• 了解更多关于Azure Communication Services中的电子邮件信息

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

此项目采用了Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题解答或联系opencode@microsoft.com，如有任何其他问题或评论。

发布历史

1.0.0 (2023-03-31)

新增功能

Azure Communication Services电子邮件SDK的公共版本具有以下功能：

• 发送具有各种选项的电子邮件（多个收件人、附件等）
• 轮询发送的电子邮件状态以跟踪其进度

1.0.0b2 (2023-03-01)

新增功能

• 添加了对AAD令牌身份验证的支持
• 添加了通过可选的api_version关键字参数指定API版本的功能。

重大变更

• SDK现在是无模型的。对象现在使用字典而不是模型来构建。
• 重新设计了SDK以遵循LRO（长时间运行操作）方法。'begin_send'方法返回一个轮询器，可用于检查发送电子邮件的状态并检索结果。返回对象已调整以适应此方法。
• 已删除get_send_status方法。
• sender属性已更改为senderAddress。
• 收件人对象下的email属性已更改为address。
• 在attachments下的attachmentType属性已更改为'contentType'。现在它接受附件MIME类型。
• 在attachments下的contentBytesBase64属性已更改为contentInBase64
• 邮件消息中的自定义头现在为键值对。
• 已删除重要性属性。现在可以通过自定义头 x-priority 或 x-msmail-priority 来指定电子邮件的重要性。

其他更改

不再支持 Python 3.6。请使用 3.7 或更高版本的 Python。有关更多详细信息，请参阅我们的Azure SDK for Python 版本支持策略页面。

1.0.0b1 (2022-08-09)

Azure 通信电子邮件客户端的第一个预览版具有以下功能

• 发送带附件的多收件人邮件
• 获取已发送消息的状态