Merge pull request #286673 from natekimball-msft/natekimball/update-documentation-for-inline-attachments

Add section in advanced sending for inline images

Author: JamesJBarnett

articles/communication-services/quickstarts/email/includes/send-email-async-sync-net.md

@@ -23,7 +23,7 @@ The following classes and interfaces handle some of the major features of the Az
 | Name                | Description                                                                                                                                          |
 | --------------------| -----------------------------------------------------------------------------------------------------------------------------------------------------|
 | EmailAddress        | This class contains an email address and an option for a display name.                                                                               |
-| EmailAttachment     | This class creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, and binary data for content.                               |
+| EmailAttachment     | This class creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, binary data for content, and an optional content ID to define it as an inline attachment.                               |
 | EmailClient         | This class is needed for all email functionality. You instantiate it with your connection string and use it to send email messages.                  |
 | EmailClientOptions  | This class can be added to the EmailClient instantiation to target a specific API version.                                                           |
 | EmailContent        | This class contains the subject and the body of the email message. You have to specify at least one of PlainText or Html content   |
@@ -46,7 +46,7 @@ EmailSendResult returns the following status on the email operation performed.
 
 ## Prerequisites
 
-- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). 
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 - The latest version [.NET Core client library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system.
 - An Azure Email Communication Services Resource created and ready with a provisioned domain [Get started with Creating Email Communication Resource](../create-email-communication-resource.md)
 - An active Communication Services resource connected with Email Domain and a Connection String. [Get started by Connecting Email Resource with a Communication Resource](../connect-email-communication-resource.md)
@@ -160,13 +160,13 @@ var emailClient = new EmailClient(endpoint, key);
 
 #### [Send Email with synchronous status polling](#tab/send-smail-and-get-status-sync)
 
-## Basic email sending 
+## Basic email sending
 
 ### Construct your email message
 
 To send an email message, you need to:
 - Define the email subject and body.
-- Define your Sender Address. Construct your email message with your Sender information you get your MailFrom address from your verified domain. 
+- Define your Sender Address. Construct your email message with your Sender information you get your MailFrom address from your verified domain.
 - Define the Recipient Address.
 - Call the SendAsync method. Add this code to the end of `Main` method in **Program.cs**:
 
@@ -184,7 +184,7 @@ var recipient = "[email protected]";
 ### Send and get the email send status
 
 To send an email message, you need to:
-- Call SendAsync method that sends the email request as an asynchronous operation. Call with Azure.WaitUntil.Completed if your method should wait to return until the long-running operation has completed on the service. Call with Azure.WaitUntil.Started if your method should return after starting the operation. 
+- Call SendAsync method that sends the email request as an asynchronous operation. Call with Azure.WaitUntil.Completed if your method should wait to return until the long-running operation has completed on the service. Call with Azure.WaitUntil.Started if your method should return after starting the operation.
 - SendAsync method returns EmailSendOperation that returns "Succeeded" EmailSendStatus if email is out for delivery and throws an exception otherwise. Add this code to the end of `Main` method in **Program.cs**:
 
 ```csharp
@@ -198,7 +198,7 @@ try
         subject,
         htmlContent);
     EmailSendResult statusMonitor = emailSendOperation.Value;
-    
+
     Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
 
     /// Get the OperationId so that it can be used for tracking the message for troubleshooting
@@ -216,8 +216,8 @@ catch (RequestFailedException ex)
 
 EmailSendOperation only returns email operation status. To get the actual email delivery status, you can subscribe to "EmailDeliveryReportReceived" event that is generated when the email delivery is completed. The event returns the following delivery state:
 
-- Delivered. 
-- Failed. 
+- Delivered.
+- Failed.
 - Quarantined.
 
 See [Handle Email Events](../handle-email-events.md) for details.

articles/communication-services/quickstarts/email/includes/send-email-java.md

@@ -23,7 +23,7 @@ The following classes and interfaces handle some of the major features of the Az
 | Name | Description |
 | ---- |-------------|
 | EmailAddress | This class contains an email address and an option for a display name. |
-| EmailAttachment | This interface creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, and a string of content bytes. |
+| EmailAttachment | This interface creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, a string of content bytes, and an optional content ID to define it as an inline attachment. |
 | EmailClient | This class is needed for all email functionality. You instantiate it with your connection string and use it to send email messages. |
 | EmailMessage | This class combines the sender, content, and recipients. Custom headers, attachments, and reply-to email addresses can optionally be added, as well. |
 | EmailSendResult | This class holds the results of the email send operation. It has an operation ID, operation status and error object (when applicable). |
@@ -193,7 +193,7 @@ For simplicity, this quickstart uses connection strings, but in production envir
 
 
 
-## Basic email sending 
+## Basic email sending
 
 An email message can be crafted using the `EmailMessage` object in the SDK.
 

articles/communication-services/quickstarts/email/includes/send-email-js.md

@@ -23,7 +23,7 @@ The following classes and interfaces handle some of the major features of the Az
 | Name | Description |
 | ---- |-------------|
 | EmailAddress | This class contains an email address and an option for a display name. |
-| EmailAttachment | This class creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, and binary data for content. |
+| EmailAttachment | This class creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, binary data for content, and an optional Content ID to define it as an inline attachment. |
 | EmailClient | This class is needed for all email functionality. You instantiate it with your connection string and use it to send email messages. |
 | EmailClientOptions | This class can be added to the EmailClient instantiation to target a specific API version. |
 | EmailContent | This class contains the subject and the body of the email message. You have to specify at least one of PlainText or Html content. |
@@ -153,7 +153,7 @@ const emailClient = new EmailClient(endpoint, key);
 
 For simplicity, this quickstart uses connection strings, but in production environments, we recommend using [service principals](../../../quickstarts/identity/service-principal.md).
 
-## Basic email sending 
+## Basic email sending
 
 ### Send an email message
 

articles/communication-services/quickstarts/email/includes/send-email-net.md

@@ -23,7 +23,7 @@ The following classes and interfaces handle some of the major features of the Az
 | Name                | Description                                                                                                                                          |
 | --------------------| -----------------------------------------------------------------------------------------------------------------------------------------------------|
 | EmailAddress        | This class contains an email address and an option for a display name.                                                                               |
-| EmailAttachment     | This class creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, and binary data for content.                               |
+| EmailAttachment     | This class creates an email attachment by accepting a unique ID, email attachment [MIME type](../../../concepts/email/email-attachment-allowed-mime-types.md) string, binary data for content, and an optional content ID to define it as an inline attachment. |
 | EmailClient         | This class is needed for all email functionality. You instantiate it with your connection string and use it to send email messages.                  |
 | EmailClientOptions  | This class can be added to the EmailClient instantiation to target a specific API version.                                                           |
 | EmailContent        | This class contains the subject and the body of the email message. You have to specify at least one of PlainText or Html content   |
@@ -46,7 +46,7 @@ EmailSendResult returns the following status on the email operation performed.
 
 ## Prerequisites
 
-- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). 
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 - The latest version [.NET Core client library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system.
 - An Azure Email Communication Services Resource created and ready with a provisioned domain [Get started with Creating Email Communication Resource](../create-email-communication-resource.md)
 - An active Communication Services resource connected with Email Domain and a Connection String. [Get started by Connecting Email Resource with a Communication Resource](../connect-email-communication-resource.md)
@@ -151,13 +151,13 @@ var emailClient = new EmailClient(endpoint, key);
 
 ---
 
-## Basic email sending 
+## Basic email sending
 
 ### Construct your email message
 
 To send an email message, you need to:
 - Define the email subject and body.
-- Define your Sender Address. Construct your email message with your Sender information you get your MailFrom address from your verified domain. 
+- Define your Sender Address. Construct your email message with your Sender information you get your MailFrom address from your verified domain.
 - Define the Recipient Address.
 - Call the SendAsync method. Add this code to the end of `Main` method in **Program.cs**:
 
@@ -175,7 +175,7 @@ var recipient = "[email protected]";
 ### Send and get the email send status
 
 To send an email message, you need to:
-- Call SendAsync method that sends the email request as an asynchronous operation. Call with Azure.WaitUntil.Completed if your method should wait to return until the long-running operation has completed on the service. Call with Azure.WaitUntil.Started if your method should return after starting the operation. 
+- Call SendAsync method that sends the email request as an asynchronous operation. Call with Azure.WaitUntil.Completed if your method should wait to return until the long-running operation has completed on the service. Call with Azure.WaitUntil.Started if your method should return after starting the operation.
 - SendAsync method returns EmailSendOperation that returns "Succeeded" EmailSendStatus if email is out for delivery and throws an exception otherwise. Add this code to the end of `Main` method in **Program.cs**:
 
 ```csharp
@@ -189,7 +189,7 @@ try
         subject,
         htmlContent);
     EmailSendResult statusMonitor = emailSendOperation.Value;
-    
+
     Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
 
     /// Get the OperationId so that it can be used for tracking the message for troubleshooting
@@ -207,8 +207,8 @@ catch (RequestFailedException ex)
 
 EmailSendOperation only returns email operation status. To get the actual email delivery status, you can subscribe to "EmailDeliveryReportReceived" event that is generated when the email delivery is completed. The event returns the following delivery state:
 
-- Delivered. 
-- Failed. 
+- Delivered.
+- Failed.
 - Quarantined.
 
 See [Handle Email Events](../handle-email-events.md) for details.

articles/communication-services/quickstarts/email/send-email-advanced/includes/inline-attachments-java.md

@@ -0,0 +1,62 @@
+---
+title: include file
+description: Inline Attachments Java SDK include file
+author: natekimball-msft
+manager: koagbakp
+services: azure-communication-services
+ms.author: natekimball
+ms.date: 04/07/2023
+ms.topic: include
+ms.service: azure-communication-services
+---
+
+## Send an email message with inline attachments
+
+We can add an inline attachment by defining one or more EmailAttachment objects, defining a unique `ContentId` for each, and adding them to our EmailMessage object. Read the attachment file and encode it using Base64.
+
+```java
+byte[] jpgContent = Files.readAllBytes(new File("./inline-attachment.jpg").toPath());
+byte[] jpgEncodedContent = Base64.getEncoder().encodeToString(jpgContent).getBytes();
+EmailAttachment jpgInlineAttachment = new EmailAttachment(
+    "inline-attachment.jpg",
+    "image/jpeg",
+    BinaryData.fromBytes(jpgEncodedContent)
+).setContentId("my-inline-attachment-1");
+
+byte[] pngContent = Files.readAllBytes(new File("./inline-attachment.png").toPath());
+byte[] pngEncodedContent = Base64.getEncoder().encodeToString(pngContent).getBytes();
+EmailAttachment pngInlineAttachment = new EmailAttachment(
+    "inline-attachment.png",
+    "image/png",
+    BinaryData.fromBytes(pngEncodedContent)
+).setContentId("my-inline-attachment-2");
+```
+
+Within the HTML body of the message, we can then embed an image by referencing its `ContentId` within the source of an `<img>` tag.
+
+```java
+EmailMessage message = new EmailMessage()
+    .setSenderAddress(senderAddress)
+    .setToRecipients(recipientAddress)
+    .setSubject("Welcome to Azure Communication Services Email")
+    .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");
+    .setBodyHtml("<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>")
+    .setAttachments(jpgInlineAttachmentContent, pngInlineAttachmentContent);
+
+SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);
+PollResponse<EmailSendResult> response = poller.waitForCompletion();
+
+System.out.println("Operation Id: " + response.getValue().getId());
+```
+
+> [!NOTE]
+> Regular attachments can be combined with inline attachments, as well. Defining a `ContentId` will treat an attachment as inline, while an attachment without a `ContentId` will be treated as a regular attachment.
+
+### Allowed MIME types
+
+Although most modern clients support inline attachments, the rendering behavior of an inline attachment is largely dependent on the recipient's email client. For this reason, it is suggested to use more common image formats inline whenever possible, such as .png, .jpg, or .gif. For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
+
+### Sample code
+
+You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/send-email-advanced/send-email-inline-attachments)
+

articles/communication-services/quickstarts/email/send-email-advanced/includes/inline-attachments-js.md

@@ -0,0 +1,71 @@
+---
+title: include file
+description: Inline Attachments JS SDK include file
+author: natekimball-msft
+manager: koagbakp
+services: azure-communication-services
+ms.author: natekimball
+ms.date: 04/07/2023
+ms.topic: include
+ms.service: azure-communication-services
+---
+
+## Send an email message with inline attachments
+
+We can add an inline attachment by defining one or more attachment objects, making sure to include a unique `contentId` for each, and adding them to our message. Read the attachment file and encode it using Base64.
+
+```javascript
+const jpgFilePath = "./inline-attachment.jpg";
+const pngFilePath = "./inline-attachment.png";
+
+const inlineAttachments = [
+    {
+        name: path.basename(jpgFilePath),
+        contentId: "my-inline-attachment-1"
+        contentType: "image/jpeg",
+        contentInBase64: readFileSync(jpgFilePath, "base64"),
+    },
+    {
+        name: path.basename(pngFilePath),
+        contentId: "my-inline-attachment-2"
+        contentType: "image/png",
+        contentInBase64: readFileSync(pngFilePath, "base64"),
+    }
+];
+```
+
+Within the HTML body of the message, we can then embed an image by referencing its `contentId` within the source of an `<img>` tag.
+
+```javascript
+const message = {
+  sender: "<[email protected]>",
+  content: {
+    subject: "Welcome to Azure Communication Services Email",
+    plainText: "This email message is sent from Azure Communication Services Email using the Javascript SDK.",
+    html: "<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>"
+  },
+  recipients: {
+    to: [
+      {
+        address: "<[email protected]>",
+        displayName: "Customer Name",
+      }
+    ]
+  },
+  attachments: inlineAttachments
+};
+
+const poller = await emailClient.beginSend(message);
+const response = await poller.pollUntilDone();
+```
+
+> [!NOTE]
+> Regular attachments can be combined with inline attachments, as well. Defining a `contentId` will treat an attachment as inline, while an attachment without a `contentId` will be treated as a regular attachment.
+
+### Allowed MIME types
+
+Although most modern clients support inline attachments, the rendering behavior of an inline attachment is largely dependent on the recipient's email client. For this reason, it is suggested to use more common image formats inline whenever possible, such as .png, .jpg, or .gif. For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
+
+### Sample code
+
+You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-javascript-quickstarts/tree/main/send-email-advanced/send-email-inline-attachments)