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 do following:
* Send emails to multiple types of recipients
* Query the status of a sent email message
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 `_\ :
.. code-block:: 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 `_.
.. code-block:: python
from azure.communication.email import EmailClient
connection_string = "endpoint=https://.communication.azure.com/;accessKey="
client = EmailClient.from_connection_string(connection_string);
Email clients can also be authenticated using an `AzureKeyCredential `_.
.. code-block:: python
from azure.communication.email import EmailClient
from azure.core.credentials import AzureKeyCredential
credential = AzureKeyCredential("")
endpoint = "https://.communication.azure.com/"
client = EmailClient(endpoint, credential);
Send an Email Message
^^^^^^^^^^^^^^^^^^^^^
To send an email message, call the ``send`` function from the ``EmailClient``.
.. code-block:: python
content = EmailContent(
subject="This is the subject",
plain_text="This is the body",
html= "This is the body
",
)
address = EmailAddress(email="customer@domain.com", display_name="Customer Name")
message = EmailMessage(
sender="sender@contoso.com",
content=content,
recipients=EmailRecipients(to=[address])
)
response = client.send(message)
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.
.. code-block:: python
content = EmailContent(
subject="This is the subject",
plain_text="This is the body",
html= "This is the body
",
)
recipients = EmailRecipients(
to=[
EmailAddress(email="customer@domain.com", display_name="Customer Name"),
EmailAddress(email="customer2@domain.com", display_name="Customer Name 2"),
],
cc=[
EmailAddress(email="ccCustomer@domain.com", display_name="CC Customer Name"),
EmailAddress(email="ccCustomer2@domain.com", display_name="CC Customer Name 2"),
],
bcc=[
EmailAddress(email="bccCustomer@domain.com", display_name="BCC Customer Name"),
EmailAddress(email="bccCustomer2@domain.com", display_name="BCC Customer Name 2"),
]
)
message = EmailMessage(sender="sender@contoso.com", content=content, recipients=recipients)
response = client.send(message)
Send Email with Attachments
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Azure Communication Services support sending email with attachments.
.. code-block:: python
import base64
content = EmailContent(
subject="This is the subject",
plain_text="This is the body",
html= "This is the body
",
)
address = EmailAddress(email="customer@domain.com", display_name="Customer Name")
with open("C://readme.txt", "r") as file:
file_contents = file.read()
file_bytes_b64 = base64.b64encode(bytes(file_contents, 'utf-8'))
attachment = EmailAttachment(
name="attachment.txt",
attachment_type="txt",
content_bytes_base64=file_bytes_b64.decode()
)
message = EmailMessage(
sender="sender@contoso.com",
content=content,
recipients=EmailRecipients(to=[address]),
attachments=[attachment]
)
response = client.send(message)
Get Email Message Status
^^^^^^^^^^^^^^^^^^^^^^^^
The result from the ``send`` call contains a ``message_id`` which can be used to query the status of the email.
.. code-block:: python
response = client.send(message)
status = client.get_sent_status(response.message_id)
Troubleshooting
---------------
Email operations will throw an exception if the request to the server fails. The Email client will raise exceptions defined in `Azure Core `_.
.. code-block:: 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 `_
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.
.. raw:: html
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. toctree::
:maxdepth: 5
:glob:
:caption: Developer Documentation
azure.communication.email.rst