Update ACS Email python SDK for inline attachments (#37069)

natekimball-msft · web-flow · commit 142916fe029b · 2024-09-20T10:20:38.000-07:00
* Initial commit for inline attachments

* Updating changelog and test recordings

* ignore spelling of myinlineimage

* Address PR feedback
diff --git a/sdk/communication/azure-communication-email/CHANGELOG.md b/sdk/communication/azure-communication-email/CHANGELOG.md
@@ -1,14 +1,11 @@
 # Release History
 
-## 1.0.1 (Unreleased)
+## 1.0.1b1 (2024-08-28)
 
 ### Features Added
 
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Consumers can now provide a value for the `contentId` property when sending emails with attachments.
+  This allows consumers to reference attachments in the email body using the `cid` scheme. The `contentId` property can be set on the `EmailAttachment` object.
 
 ## 1.0.0 (2023-03-31)
 
@@ -26,7 +23,7 @@ The public release of the Azure Communication Services SDK for Email has the fol
 
 ### 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. 
+- 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`.
diff --git a/sdk/communication/azure-communication-email/README.md b/sdk/communication/azure-communication-email/README.md
@@ -157,6 +157,48 @@ poller = email_client.begin_send(message)
 result = poller.result()
 ```
 
+### Send Email with Inline Attachments
+
+Azure Communication Services support sending inline attachments.
+Adding an optional `contentId` parameter to an attachment will make it an inline attachment.
+
+```python
+import base64
+
+with open("C://inline_image.jpg", "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>This is the body<br /><img src=\"cid:my-inline-image\" /></html>"
+    },
+    "recipients": {
+        "to": [
+            {
+                "address": "customer@domain.com",
+                "displayName": "Customer Name"
+            }
+        ]
+    },
+    "senderAddress": "sender@contoso.com",
+    "attachments": [
+        {
+            "name": "inline_image.jpg",
+            "contentType": "image/jpeg",
+            "contentInBase64": file_bytes_b64.decode(),
+            "contentId": "my-inline-image"
+        }
+    ]
+}
+
+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).
diff --git a/sdk/communication/azure-communication-email/assets.json b/sdk/communication/azure-communication-email/assets.json
@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/communication/azure-communication-email",
-  "Tag": "python/communication/azure-communication-email_b3ba97a69e"
+  "Tag": "python/communication/azure-communication-email_1fa1cede8e"
 }
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_api_versions.py b/sdk/communication/azure-communication-email/azure/communication/email/_api_versions.py
@@ -8,9 +8,8 @@
 
 
 class ApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta):
-    V2021_10_01_PREVIEW = "2021-10-01-preview"
-    V2023_01_15_PREVIEW = "2023-01-15-preview"
     V2023_03_31 = "2023-03-31"
+    V2024_07_01_PREVIEW = "2024-07-01-preview"
 
 
-DEFAULT_VERSION = ApiVersion.V2023_03_31
+DEFAULT_VERSION = ApiVersion.V2024_07_01_PREVIEW
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_email_client.py b/sdk/communication/azure-communication-email/azure/communication/email/_email_client.py
@@ -33,7 +33,7 @@ class EmailClient(object):
     :param Union[TokenCredential, AzureKeyCredential] credential:
         The credential we use to authenticate against the service.
     :keyword api_version: Azure Communication Email API version.
-        Default value is "2023-03-31".
+        Default value is "2024-07-01-preview".
         Note that overriding this default value may result in unsupported behavior.
     :paramtype api_version: str
     """
@@ -137,7 +137,9 @@ def begin_send(
                               attachment. Required.
                             "contentType": "str",  # MIME type of the content being
                               attached. Required.
-                            "name": "str"  # Name of the attachment. Required.
+                            "name": "str",  # Name of the attachment. Required.
+                            "contentId": "str"  # Optional. Unique identifier (CID) to
+                              reference an inline attachment.
                         }
                     ],
                     "userEngagementTrackingDisabled": bool,  # Optional. Indicates whether user
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_generated/_client.py b/sdk/communication/azure-communication-email/azure/communication/email/_generated/_client.py
@@ -29,8 +29,8 @@ class AzureCommunicationEmailService:  # pylint: disable=client-accepts-api-vers
     :param endpoint: The communication resource, for example
      https://my-resource.communication.azure.com. Required.
     :type endpoint: str
-    :keyword api_version: Api Version. Default value is "2023-03-31". Note that overriding this
-     default value may result in unsupported behavior.
+    :keyword api_version: Api Version. Default value is "2024-07-01-preview". Note that overriding
+     this default value may result in unsupported behavior.
     :paramtype api_version: str
     :keyword int polling_interval: Default waiting time between two polls for LRO operations if no
      Retry-After header is present.
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_generated/_configuration.py b/sdk/communication/azure-communication-email/azure/communication/email/_generated/_configuration.py
@@ -23,14 +23,14 @@ class AzureCommunicationEmailServiceConfiguration(Configuration):  # pylint: dis
     :param endpoint: The communication resource, for example
      https://my-resource.communication.azure.com. Required.
     :type endpoint: str
-    :keyword api_version: Api Version. Default value is "2023-03-31". Note that overriding this
-     default value may result in unsupported behavior.
+    :keyword api_version: Api Version. Default value is "2024-07-01-preview". Note that overriding
+     this default value may result in unsupported behavior.
     :paramtype api_version: str
     """
 
     def __init__(self, endpoint: str, **kwargs: Any) -> None:
         super(AzureCommunicationEmailServiceConfiguration, self).__init__(**kwargs)
-        api_version = kwargs.pop("api_version", "2023-03-31")  # type: str
+        api_version = kwargs.pop("api_version", "2024-07-01-preview")  # type: str
 
         if endpoint is None:
             raise ValueError("Parameter 'endpoint' must not be None.")
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_generated/aio/_client.py b/sdk/communication/azure-communication-email/azure/communication/email/_generated/aio/_client.py
@@ -29,8 +29,8 @@ class AzureCommunicationEmailService:  # pylint: disable=client-accepts-api-vers
     :param endpoint: The communication resource, for example
      https://my-resource.communication.azure.com. Required.
     :type endpoint: str
-    :keyword api_version: Api Version. Default value is "2023-03-31". Note that overriding this
-     default value may result in unsupported behavior.
+    :keyword api_version: Api Version. Default value is "2024-07-01-preview". Note that overriding
+     this default value may result in unsupported behavior.
     :paramtype api_version: str
     :keyword int polling_interval: Default waiting time between two polls for LRO operations if no
      Retry-After header is present.
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_generated/aio/_configuration.py b/sdk/communication/azure-communication-email/azure/communication/email/_generated/aio/_configuration.py
@@ -23,14 +23,14 @@ class AzureCommunicationEmailServiceConfiguration(Configuration):  # pylint: dis
     :param endpoint: The communication resource, for example
      https://my-resource.communication.azure.com. Required.
     :type endpoint: str
-    :keyword api_version: Api Version. Default value is "2023-03-31". Note that overriding this
-     default value may result in unsupported behavior.
+    :keyword api_version: Api Version. Default value is "2024-07-01-preview". Note that overriding
+     this default value may result in unsupported behavior.
     :paramtype api_version: str
     """
 
     def __init__(self, endpoint: str, **kwargs: Any) -> None:
         super(AzureCommunicationEmailServiceConfiguration, self).__init__(**kwargs)
-        api_version = kwargs.pop("api_version", "2023-03-31")  # type: str
+        api_version = kwargs.pop("api_version", "2024-07-01-preview")  # type: str
 
         if endpoint is None:
             raise ValueError("Parameter 'endpoint' must not be None.")
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_generated/aio/operations/_operations.py b/sdk/communication/azure-communication-email/azure/communication/email/_generated/aio/operations/_operations.py
@@ -271,7 +271,9 @@ async def begin_send(
                               attachment. Required.
                             "contentType": "str",  # MIME type of the content being
                               attached. Required.
-                            "name": "str"  # Name of the attachment. Required.
+                            "name": "str",  # Name of the attachment. Required.
+                            "contentId": "str"  # Optional. Unique identifier (CID) to
+                              reference an inline attachment.
                         }
                     ],
                     "headers": {
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_generated/operations/_operations.py b/sdk/communication/azure-communication-email/azure/communication/email/_generated/operations/_operations.py
@@ -43,7 +43,7 @@ def build_email_get_send_result_request(operation_id: str, **kwargs: Any) -> Htt
     _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
-    api_version = kwargs.pop("api_version", _params.pop("api-version", "2023-03-31"))  # type: str
+    api_version = kwargs.pop("api_version", _params.pop("api-version", "2024-07-01-preview"))  # type: str
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -72,7 +72,7 @@ def build_email_send_request(**kwargs: Any) -> HttpRequest:
         "client_request_id", _headers.pop("x-ms-client-request-id", None)
     )  # type: Optional[str]
     content_type = kwargs.pop("content_type", _headers.pop("Content-Type", None))  # type: Optional[str]
-    api_version = kwargs.pop("api_version", _params.pop("api-version", "2023-03-31"))  # type: str
+    api_version = kwargs.pop("api_version", _params.pop("api-version", "2024-07-01-preview"))  # type: str
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -329,7 +329,9 @@ def begin_send(
                               attachment. Required.
                             "contentType": "str",  # MIME type of the content being
                               attached. Required.
-                            "name": "str"  # Name of the attachment. Required.
+                            "name": "str",  # Name of the attachment. Required.
+                            "contentId": "str"  # Optional. Unique identifier (CID) to
+                              reference an inline attachment.
                         }
                     ],
                     "headers": {
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/_version.py b/sdk/communication/azure-communication-email/azure/communication/email/_version.py
@@ -6,6 +6,6 @@
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 
-VERSION = "1.0.1"
+VERSION = "1.0.1b1"
 
 SDK_MONIKER = "communication-email/{}".format(VERSION)  # type: str
diff --git a/sdk/communication/azure-communication-email/azure/communication/email/aio/_email_client_async.py b/sdk/communication/azure-communication-email/azure/communication/email/aio/_email_client_async.py
@@ -32,7 +32,7 @@ class EmailClient(object): # pylint: disable=client-accepts-api-version-keyword
     :param Union[AsyncTokenCredential, AzureKeyCredential] credential:
         The credential we use to authenticate against the service.
     :keyword api_version: Azure Communication Email API version.
-        Default value is "2023-03-31".
+        Default value is "2024-07-01-preview".
         Note that overriding this default value may result in unsupported behavior.
     :paramtype api_version: str
     """
@@ -136,7 +136,9 @@ async def begin_send(
                               attachment. Required.
                             "contentType": "str",  # MIME type of the content being
                               attached. Required.
-                            "name": "str"  # Name of the attachment. Required.
+                            "name": "str",  # Name of the attachment. Required.
+                            "contentId": "str"  # Optional. Unique identifier (CID) to
+                              reference an inline attachment.
                         }
                     ],
                     "userEngagementTrackingDisabled": bool,  # Optional. Indicates whether user
diff --git a/sdk/communication/azure-communication-email/samples/inline_image.gif b/sdk/communication/azure-communication-email/samples/inline_image.gif
diff --git a/sdk/communication/azure-communication-email/samples/send_email_with_inline_attachments_sample.py b/sdk/communication/azure-communication-email/samples/send_email_with_inline_attachments_sample.py
@@ -0,0 +1,86 @@
+# coding: utf-8
+
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""
+FILE: send_email_with_inline_attachments_sample.py
+DESCRIPTION:
+    This sample demonstrates sending an email with an inline attachment.
+    The Email client is authenticated using a connection string.
+USAGE:
+    python send_email_with_inline_attachments_sample.py
+    Set the environment variable with your own value before running the sample:
+    1) COMMUNICATION_CONNECTION_STRING_EMAIL - the connection string in your ACS resource
+    2) SENDER_ADDRESS - the address found in the linked domain that will send the email
+    3) RECIPIENT_ADDRESS - the address that will receive the email
+"""
+
+import base64
+import os
+import sys
+from azure.core.exceptions import HttpResponseError
+from azure.communication.email import EmailClient
+
+sys.path.append("..")
+
+class EmailWithAttachmentSample(object):
+
+    connection_string = os.getenv("COMMUNICATION_CONNECTION_STRING_EMAIL")
+    sender_address = os.getenv("SENDER_ADDRESS")
+    recipient_address = os.getenv("RECIPIENT_ADDRESS")
+
+    def send_email_with_attachment(self):
+        # creating the email client
+        email_client = EmailClient.from_connection_string(self.connection_string)
+
+        # creating the email message
+        attachment_path = os.path.join(
+            os.path.dirname(os.path.realpath(__file__)),
+            "inline_image.gif")
+
+        with open(attachment_path, "rb") as file:
+            file_bytes = file.read()
+
+        file_bytes_b64 = base64.b64encode(file_bytes)
+
+        message = {
+            "content": {
+                "subject": "This is the subject",
+                "plainText": "This is the body",
+                "html": "<html>This is the body<br /><img src=\"cid:my-inline-image\" /></html>"
+            },
+            "recipients": {
+                "to": [
+                    {
+                        "address": self.recipient_address,
+                        "displayName": "Customer Name"
+                    }
+                ]
+            },
+            "senderAddress": self.sender_address,
+            "attachments": [
+                {
+                    "name": "inline_image.gif",
+                    "contentType": "image/gif",
+                    "contentInBase64": file_bytes_b64.decode(),
+                    "contentId": "my-inline-image"
+                }
+            ]
+        }
+
+        try:
+            # sending the email message
+            poller = email_client.begin_send(message)
+            response = poller.result()
+            print("Operation ID: " + response['id'])
+        except HttpResponseError as ex:
+            print(ex)
+            pass
+
+if __name__ == '__main__':
+    sample = EmailWithAttachmentSample()
+    sample.send_email_with_attachment()
diff --git a/sdk/communication/azure-communication-email/samples/send_email_with_inline_attachments_sample_async.py b/sdk/communication/azure-communication-email/samples/send_email_with_inline_attachments_sample_async.py
diff --git a/sdk/communication/azure-communication-email/swagger/SWAGGER.md b/sdk/communication/azure-communication-email/swagger/SWAGGER.md
diff --git a/sdk/communication/azure-communication-email/tests/conftest.py b/sdk/communication/azure-communication-email/tests/conftest.py
diff --git a/sdk/communication/azure-communication-email/tests/test_email_client_e2e.py b/sdk/communication/azure-communication-email/tests/test_email_client_e2e.py
diff --git a/sdk/communication/azure-communication-email/tests/test_email_client_e2e_async.py b/sdk/communication/azure-communication-email/tests/test_email_client_e2e_async.py

Original file line number	Diff line number	Diff line change
`@@ -2,5 +2,5 @@`
`2`	`2`	`"AssetsRepo": "Azure/azure-sdk-assets",`
`3`	`3`	`"AssetsRepoPrefixPath": "python",`
`4`	`4`	`"TagPrefix": "python/communication/azure-communication-email",`
`5`		`- "Tag": "python/communication/azure-communication-email_b3ba97a69e"`
	`5`	`+ "Tag": "python/communication/azure-communication-email_1fa1cede8e"`
`6`	`6`	`}`