# 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][azure_sub], a [Communication Service Resource][communication_resource_docs], and an [Email Communication Resource][email_resource_docs] with an active [Domain][domain_overview].
To create these resource, you can use the [Azure Portal][communication_resource_create_portal], the [Azure PowerShell][communication_resource_create_power_shell], or the [.NET management client library][communication_resource_create_net].
### Installing
Install the Azure Communication Email client library for Python with [pip](https://pypi.org/project/pip/):
```bash
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][azure_portal].
```python
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.
```python
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][azure-key-credential].
```python
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.
```python
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.
```python
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.
```python
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](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md).
```python
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][nextsteps]
## 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][cla].
This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
<!-- LINKS -->
[azure_sub]: https://azure.microsoft.com/free/dotnet/
[azure_portal]: https://portal.azure.com
[azure-key-credential]: https://aka.ms/azsdk-python-core-azurekeycredential
[cla]: https://cla.microsoft.com
[coc]: https://opensource.microsoft.com/codeofconduct/
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
[coc_contact]: mailto:opencode@microsoft.com
[communication_resource_docs]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp
[email_resource_docs]: https://aka.ms/acsemail/createemailresource
[communication_resource_create_portal]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp
[communication_resource_create_power_shell]: https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice
[communication_resource_create_net]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-net
[package]: https://www.nuget.org/packages/Azure.Communication.Common/
[product_docs]: https://aka.ms/acsemail/overview
[nextsteps]: https://aka.ms/acsemail/overview
[nuget]: https://www.nuget.org/
[source]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/communication
[domain_overview]: https://aka.ms/acsemail/domainsoverview
# 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](https://github.com/Azure/azure-sdk-for-python/wiki/Azure-SDKs-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
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python",
"name": "azure-communication-email",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "azure,azure sdk",
"author": "Microsoft Corporation",
"author_email": "azpysdkhelp@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/4c/fc/45a122a7d6b2cc4652aa9c5ce3a151161433447361af98f15e82cae63727/azure-communication-email-1.0.0.zip",
"platform": null,
"description": "# Azure Communication Email client library for Python\n\nThis package contains a Python SDK for Azure Communication Services for Email.\n\n## Key concepts\n\nThe Azure Communication Email package is used to send emails to multiple types of recipients.\n\n## Getting started\n\n### Prerequisites\n\nYou need an [Azure subscription][azure_sub], a [Communication Service Resource][communication_resource_docs], and an [Email Communication Resource][email_resource_docs] with an active [Domain][domain_overview].\n\nTo create these resource, you can use the [Azure Portal][communication_resource_create_portal], the [Azure PowerShell][communication_resource_create_power_shell], or the [.NET management client library][communication_resource_create_net].\n\n### Installing\n\nInstall the Azure Communication Email client library for Python with [pip](https://pypi.org/project/pip/):\n\n```bash\npip install azure-communication-email\n```\n\n## Examples\n\n`EmailClient` provides the functionality to send email messages.\n\n## Authentication\n\nEmail clients can be authenticated using the connection string acquired from an Azure Communication Resource in the [Azure Portal][azure_portal].\n\n```python\nfrom azure.communication.email import EmailClient\n\nconnection_string = \"endpoint=https://<resource-name>.communication.azure.com/;accessKey=<Base64-Encoded-Key>\"\nclient = EmailClient.from_connection_string(connection_string);\n```\n\nAlternatively, you can also use Active Directory authentication using DefaultAzureCredential.\n\n```python\nfrom azure.communication.email import EmailClient\nfrom azure.identity import DefaultAzureCredential\n\n# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.\nendpoint = \"https://<resource-name>.communication.azure.com\"\nclient = EmailClient(endpoint, DefaultAzureCredential())\n```\n\nEmail clients can also be authenticated using an [AzureKeyCredential][azure-key-credential].\n\n```python\nfrom azure.communication.email import EmailClient\nfrom azure.core.credentials import AzureKeyCredential\n\ncredential = AzureKeyCredential(\"<api_key>\")\nendpoint = \"https://<resource-name>.communication.azure.com/\"\nclient = EmailClient(endpoint, credential);\n```\n\n### Send an Email Message\n\nTo 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.\n\n```python\nmessage = {\n \"content\": {\n \"subject\": \"This is the subject\",\n \"plainText\": \"This is the body\",\n \"html\": \"html><h1>This is the body</h1></html>\"\n },\n \"recipients\": {\n \"to\": [\n {\n \"address\": \"customer@domain.com\",\n \"displayName\": \"Customer Name\"\n }\n ]\n },\n \"senderAddress\": \"sender@contoso.com\"\n}\n\npoller = email_client.begin_send(message)\nresult = poller.result()\n```\n\n### Send an Email Message to Multiple Recipients\n\nTo send an email message to multiple recipients, add a object for each recipient type and an object for each recipient.\n\n```python\nmessage = {\n \"content\": {\n \"subject\": \"This is the subject\",\n \"plainText\": \"This is the body\",\n \"html\": \"html><h1>This is the body</h1></html>\"\n },\n \"recipients\": {\n \"to\": [\n {\"address\": \"customer@domain.com\", \"displayName\": \"Customer Name\"},\n {\"address\": \"customer2@domain.com\", \"displayName\": \"Customer Name 2\"}\n ],\n \"cc\": [\n {\"address\": \"ccCustomer@domain.com\", \"displayName\": \"CC Customer Name\"},\n {\"address\": \"ccCustomer2@domain.com\", \"displayName\": \"CC Customer Name 2\"}\n ],\n \"bcc\": [\n {\"address\": \"bccCustomer@domain.com\", \"displayName\": \"BCC Customer Name\"},\n {\"address\": \"bccCustomer2@domain.com\", \"displayName\": \"BCC Customer Name 2\"}\n ]\n },\n \"senderAddress\": \"sender@contoso.com\"\n}\n\npoller = email_client.begin_send(message)\nresult = poller.result()\n```\n\n### Send Email with Attachments\n\nAzure Communication Services support sending email with attachments.\n\n```python\nimport base64\n\nwith open(\"C://readme.txt\", \"r\") as file:\n file_contents = file.read()\n\nfile_bytes_b64 = base64.b64encode(bytes(file_contents, 'utf-8'))\n\nmessage = {\n \"content\": {\n \"subject\": \"This is the subject\",\n \"plainText\": \"This is the body\",\n \"html\": \"html><h1>This is the body</h1></html>\"\n },\n \"recipients\": {\n \"to\": [\n {\n \"address\": \"customer@domain.com\",\n \"displayName\": \"Customer Name\"\n }\n ]\n },\n \"senderAddress\": \"sender@contoso.com\",\n \"attachments\": [\n {\n \"name\": \"attachment.txt\",\n \"attachmentType\": \"text/plain\",\n \"contentInBase64\": file_bytes_b64.decode()\n }\n ]\n}\n\npoller = email_client.begin_send(message)\nresult = poller.result()\n```\n\n## Troubleshooting\n\nEmail operations will throw an exception if the request to the server fails. The Email client will raise exceptions defined in [Azure Core](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md).\n\n```python\nfrom azure.core.exceptions import HttpResponseError\n\ntry:\n response = email_client.send(message)\nexcept HttpResponseError as ex:\n print('Exception:')\n print(ex)\n```\n\n## Next steps\n\n- [Read more about Email in Azure Communication Services][nextsteps]\n\n## Contributing\n\nThis 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][cla].\n\nThis project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.\n\n<!-- LINKS -->\n\n[azure_sub]: https://azure.microsoft.com/free/dotnet/\n[azure_portal]: https://portal.azure.com\n[azure-key-credential]: https://aka.ms/azsdk-python-core-azurekeycredential\n[cla]: https://cla.microsoft.com\n[coc]: https://opensource.microsoft.com/codeofconduct/\n[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/\n[coc_contact]: mailto:opencode@microsoft.com\n[communication_resource_docs]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp\n[email_resource_docs]: https://aka.ms/acsemail/createemailresource\n[communication_resource_create_portal]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp\n[communication_resource_create_power_shell]: https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice\n[communication_resource_create_net]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-net\n[package]: https://www.nuget.org/packages/Azure.Communication.Common/\n[product_docs]: https://aka.ms/acsemail/overview\n[nextsteps]: https://aka.ms/acsemail/overview\n[nuget]: https://www.nuget.org/\n[source]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/communication\n[domain_overview]: https://aka.ms/acsemail/domainsoverview\n\n\n# Release History\n\n## 1.0.0 (2023-03-31)\n\n### Features Added\nThe public release of the Azure Communication Services SDK for Email has the following features:\n\n- send emails with a variety of options (multiple recipients, attachments, etc.)\n- poll for the status of the email that was sent to track its progress\n\n## 1.0.0b2 (2023-03-01)\n\n### Features Added\n- Adding support for AAD token authentication\n- Added the ability to specify the API version by an optional `api_version` keyword parameter.\n\n### Breaking Changes\n- Made the SDK Model-less. Objects are now constructed using a dictionary instead of a model.\n- 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. \n- The `get_send_status` method has been removed.\n- The `sender` property has been changed to `senderAddress`.\n- The `email` property under the recipient object has been changed to `address`.\n- The `attachmentType` property under `attachments` has been changed to 'contentType'. This now accepts the attachment mime type.\n- The `contentBytesBase64` property under `attachments` has been changed to `contentInBase64`\n- Custom headers in the email message are now key/value pairs.\n- The importance property was removed. Email importance can now be specified through either the `x-priority` or `x-msmail-priority` custom headers.\n\n### Other Changes\nPython 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](https://github.com/Azure/azure-sdk-for-python/wiki/Azure-SDKs-Python-version-support-policy).\n\n## 1.0.0b1 (2022-08-09)\n\nThe first preview of the Azure Communication Email Client has the following features:\n\n- send emails to multiple recipients with attachments\n- get the status of a sent message\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure MyService Management Client Library for Python",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/Azure/azure-sdk-for-python"
},
"split_keywords": [
"azure",
"azure sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "436e0d73cadbcc572db66284fea3ca6a84caf5799740bdb54454175e68fc65a4",
"md5": "d8a7f0d0f1c5eec80ff6d8ffef59907a",
"sha256": "b580ccfc9f1372d0b65f235334e569f3909894316bc3203bd9deb5760612693a"
},
"downloads": -1,
"filename": "azure_communication_email-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8a7f0d0f1c5eec80ff6d8ffef59907a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 59145,
"upload_time": "2023-03-31T21:14:39",
"upload_time_iso_8601": "2023-03-31T21:14:39.185792Z",
"url": "https://files.pythonhosted.org/packages/43/6e/0d73cadbcc572db66284fea3ca6a84caf5799740bdb54454175e68fc65a4/azure_communication_email-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4cfc45a122a7d6b2cc4652aa9c5ce3a151161433447361af98f15e82cae63727",
"md5": "1d627ca493b9a52dfbc6a6afc8bee44b",
"sha256": "5df96b8b4389696244982ffc3740722f1948abb289f19af00ce2e1c534450095"
},
"downloads": -1,
"filename": "azure-communication-email-1.0.0.zip",
"has_sig": false,
"md5_digest": "1d627ca493b9a52dfbc6a6afc8bee44b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 90888,
"upload_time": "2023-03-31T21:14:41",
"upload_time_iso_8601": "2023-03-31T21:14:41.775177Z",
"url": "https://files.pythonhosted.org/packages/4c/fc/45a122a7d6b2cc4652aa9c5ce3a151161433447361af98f15e82cae63727/azure-communication-email-1.0.0.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-31 21:14:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-communication-email"
}
JSON
