Merge pull request #232053 from natekimball-msft/natekimball/add-mime-attachment-type-doc

Adding MIME type document and bugbash updates

Author: v-regandowner

articles/communication-services/concepts/email/email-attachment-allowed-mime-types.md

@@ -0,0 +1,115 @@
+---
+title: Allowed attachment types for sending email
+titleSuffix: An Azure Communication Services concept document
+description: Learn about how validation for attachment MIME types works for Email Communication Services.
+author: natekimball-msft
+manager: koagbakp
+services: azure-communication-services
+ms.author: natekimball
+ms.date: 03/24/2023
+ms.topic: conceptual
+ms.service: azure-communication-services
+ms.custom: private_preview, event-tier1-build-2022
+---
+
+# Allowed attachment types for sending email in Azure Communication Services Email
+
+The [Send Email operation](../../quickstarts/email/send-email.md) allows the option for the sender to add attachments to an outgoing email. Along with the content itself, the sender must include the file attachment type using the MIME standard when making a request with an attachment. Many common file types are accepted, such as Word documents, Excel spreadsheets, many image and video formats, contacts, and calendar invites. 
+
+## What is a MIME type?
+
+MIME (Multipurpose Internet Mail Extensions) types are a way of identifying the type of data that is being sent over the internet. When users send email requests with Azure Communication Services Email, they can specify the MIME type of the email content, which allows the recipient's email client to properly display and interpret the message. If an email message includes an attachment, the MIME type would be set to the appropriate file type (for example, "application/pdf" for a PDF document).
+
+Developers can ensure that the recipient's email client properly formats and interprets the email message by using MIME types, irrespective of the software or platform being used. This information helps to ensure that the email message is delivered correctly and that the recipient can access the content as intended. In addition, using MIME types can also help to improve the security of email communications, as they can be used to indicate whether an email message includes executable content or other potentially harmful elements.
+
+To sum up, MIME types are a critical component of email communication, and by using them with Azure Communication Services Email, developers can help ensure that their email messages are delivered correctly and securely.
+
+## Allowed attachment types
+
+Here's a table listing some of the most common supported file extensions and their corresponding MIME types for email attachments using Azure Communication Services Email:
+
+| File Extension | Description | MIME Type |
+| --- | --- | --- |
+| .3gp | 3GPP multimedia file | `video/3gpp` |
+| .3g2 | 3GPP2 multimedia file | `video/3gpp2` |
+| .7z | 7-Zip compressed file | `application/x-7z-compressed` |
+| .aac | AAC audio | `audio/aac` |
+| .avi | AVI video file | `video/x-msvideo` |
+| .bmp | BMP image | `image/bmp` |
+| .csv | Comma-separated values | `text/csv` |
+| .doc | Microsoft Word document (97-2003) | `application/msword` |
+| .docm | Microsoft Word macro-enabled document | `application/vnd.ms-word.document.macroEnabled.12` |
+| .docx | Microsoft Word document (2007 or later) | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
+| .eot | Embedded OpenType font | `application/vnd.ms-fontobject` |
+| .epub | EPUB ebook file | `application/epub+zip` |
+| .gif | GIF image | `image/gif` |
+| .gz | Gzip compressed file | `application/gzip` |
+| .ico | Icon file | `image/vnd.microsoft.icon` |
+| .ics | iCalendar file | `text/calendar` |
+| .jpg, .jpeg | JPEG image | `image/jpeg` |
+| .json | JSON data | `application/json` |
+| .mid, .midi | MIDI audio file | `audio/midi` |
+| .mp3 | MP3 audio file | `audio/mpeg` |
+| .mp4 | MP4 video file | `video/mp4` |
+| .mpeg | MPEG video file | `video/mpeg` |
+| .oga | Ogg audio file | `audio/ogg` |
+| .ogv | Ogg video file | `video/ogg` |
+| .ogx | Ogg file | `application/ogg` |
+| .one | Microsoft OneNote file | `application/onenote` |
+| .opus | Opus audio file | `audio/opus` |
+| .otf | OpenType font | `font/otf` |
+| .pdf | PDF document | `application/pdf` |
+| .png | PNG image | `image/png` |
+| .ppsm | PowerPoint slideshow (macro-enabled) | `application/vnd.ms-powerpoint.slideshow.macroEnabled.12` |
+| .ppsx | PowerPoint slideshow | `application/vnd.openxmlformats-officedocument.presentationml.slideshow` |
+| .ppt | PowerPoint presentation (97-2003) | `application/vnd.ms-powerpoint` |
+| .pptm | PowerPoint macro-enabled presentation | `application/vnd.ms-powerpoint.presentation.macroEnabled.12` |
+| .pptx | PowerPoint presentation (2007 or later) | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
+| .pub | Microsoft Publisher document | `application/vnd.ms-publisher` |
+| .rar | RAR compressed file | `application/x-rar-compressed` |
+| .rpmsg | Outlook email message | `application/vnd.ms-outlook` |
+| .rtf | Rich Text Format document | `application/rtf` |
+| .svg | Scalable Vector Graphics image | `image/svg+xml` |
+| .tar | Tar archive file | `application/x-tar` |
+| .tif, .tiff | Tagged Image File Format | `image/tiff` |
+| .ttf | TrueType Font | `font/ttf` |
+| .txt | Text Document | `text/plain` |
+| .vsd | Microsoft Visio Drawing | `application/vnd.visio` |
+| .wav | Waveform Audio File Format | `audio/wav` |
+| .weba | WebM Audio File | `audio/webm` |
+| .webm | WebM Video File | `video/webm` |
+| .webp | WebP Image File | `image/webp` |
+| .wma | Windows Media Audio File | `audio/x-ms-wma` |
+| .wmv | Windows Media Video File | `video/x-ms-wmv` |
+| .woff | Web Open Font Format | `font/woff` |
+| .woff2 | Web Open Font Format 2.0 | `font/woff2` |
+| .xls | Microsoft Excel Spreadsheet (97-2003) | `application/vnd.ms-excel` |
+| .xlsb | Microsoft Excel Binary Spreadsheet | `application/vnd.ms-excel.sheet.binary.macroEnabled.12` |
+| .xlsm | Microsoft Excel Macro-Enabled Spreadsheet | `application/vnd.ms-excel.sheet.macroEnabled.12` |
+| .xlsx | Microsoft Excel Spreadsheet (OpenXML) | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
+| .xml | Extensible Markup Language File | `application/xml`, `text/xml` |
+| .zip | ZIP Archive | `application/zip` |
+
+There are many other file extensions and MIME types that can be used for email attachments. However, this list includes accepted types for sending attachments in our SendMail operation. Additionally, different email clients and servers may have different limitations or restrictions on file size and types that could result in the failure of email delivery. Ensure that the recipient can accept the email attachment or refer to the documentation for the recipient's email providers.
+
+## Additional information
+
+The Internet Assigned Numbers Authority (IANA) is a department of the Internet Corporation for Assigned Names and Numbers (ICANN) responsible for the global coordination of various Internet protocols and resources, including the management and registration of MIME types.
+
+The IANA maintains a registry of standardized MIME types, which includes a unique identifier for each MIME type, a short description of its purpose, and the associated file extensions. For the most up-to-date information regarding MIME types, including the definitive list of media types, it's recommended to visit the [IANA Website](https://www.iana.org/assignments/media-types/media-types.xhtml) directly.
+
+## Next steps
+
+* [What is Email Communication Communication Service](./prepare-email-communication-resource.md)
+
+* [Email domains and sender authentication for Azure Communication Services](./email-domain-and-sender-authentication.md)
+
+* [Get started with sending email using Email Communication Service in Azure Communication Service](../../quickstarts/email/send-email.md)
+
+* [Get started by connecting Email Communication Service with a Azure Communication Service resource](../../quickstarts/email/connect-email-communication-resource.md)
+
+The following documents may be interesting to you:
+
+- Familiarize yourself with the [Email client library](../email/sdk-features.md)
+- How to send emails with custom verified domains? [Add custom domains](../../quickstarts/email/add-custom-verified-domains.md)
+- How to send emails with Azure Managed Domains? [Add Azure Managed domains](../../quickstarts/email/add-azure-managed-domains.md)

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

@@ -5,7 +5,7 @@ author: natekimball-msft
 manager: koagbakp
 services: azure-communication-services
 ms.author: natekimball
-ms.date: 03/03/2023
+ms.date: 03/24/2023
 ms.topic: include
 ms.service: azure-communication-services
 ms.custom: mode-other
@@ -20,7 +20,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 type, 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, and a string of content bytes. |
 | 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). |
@@ -119,7 +119,7 @@ EmailClient emailClient = new EmailClientBuilder()
 
 ### Option 2: Authenticate using Azure Active Directory
 
-A `DefaultAzureCredential` object must be passed to the `EmailClientBuilder` via the `credential()` method. An endpoint must also be set via the `endpoint()` method.
+A [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/identity/azure-identity#defaultazurecredential) object must be passed to the `EmailClientBuilder` via the `credential()` method. An endpoint must also be set via the `endpoint()` method.
 
 The `AZURE_CLIENT_SECRET`, `AZURE_CLIENT_ID`, and `AZURE_TENANT_ID` environment variables are needed to create a `DefaultAzureCredential` object.
 
@@ -158,10 +158,43 @@ EmailMessage message = new EmailMessage()
     .setSubject("Welcome to Azure Communication Services Email")
     .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");
 
-SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);
-PollResponse<EmailSendResult> response = poller.waitForCompletion();
-
-System.out.println("Operation Id: " + response.getValue().getId());
+try
+{
+    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);
+
+    PollResponse<EmailSendResult> pollResponse = null;
+
+    Duration timeElapsed = Duration.ofSeconds(0);
+
+        while (pollResponse == null
+                || pollResponse.getStatus() == LongRunningOperationStatus.NOT_STARTED
+                || pollResponse.getStatus() == LongRunningOperationStatus.IN_PROGRESS)
+        {
+            pollResponse = poller.poll();
+            System.out.println("Email send poller status: " + pollResponse.getStatus());
+
+            Thread.sleep(POLLER_WAIT_TIME.toMillis());
+            timeElapsed = timeElapsed.plus(POLLER_WAIT_TIME);
+
+            if (timeElapsed.compareTo(POLLER_WAIT_TIME.multipliedBy(18)) >= 0)
+            {
+                throw new RuntimeException("Polling timed out.");
+            }
+        }
+
+        if (poller.getFinalResult().getStatus() == EmailSendStatus.SUCCEEDED)
+        {
+            System.out.printf("Successfully sent the email (operation id: %s)", poller.getFinalResult().getId());
+        }
+        else
+        {
+            throw new RuntimeException(poller.getFinalResult().getError().getMessage());
+        }
+}
+catch (Exception exception)
+{
+    System.out.println(exception.getMessage());
+}
 ```
 
 Make these replacements in the code:
@@ -227,15 +260,17 @@ EmailMessage message = new EmailMessage()
     .setSenderAddress("<[email protected]>")
     .setSubject("Welcome to Azure Communication Services Email")
     .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.")
-    .setToRecipients(toAddress1, toAddress2);
+    .setToRecipients(toAddress1, toAddress2)
+    .setCcRecipients(toAddress1, toAddress2)
+    .setBccRecipients(toAddress1, toAddress2)
 
 SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);
 PollResponse<EmailSendResult> response = poller.waitForCompletion();
 
 System.out.println("Operation Id: " + response.getValue().getId());
 ```
 
-You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/send-email)
+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 an email message with attachments
 
@@ -262,4 +297,6 @@ PollResponse<EmailSendResult> response = poller.waitForCompletion();
 System.out.println("Operation Id: " + response.getValue().getId());
 ```
 
-You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/send-email)
+For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
+
+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)

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

@@ -5,7 +5,7 @@ author: natekimball-msft
 manager: koagbakp
 services: azure-communication-services
 ms.author: natekimball
-ms.date: 04/15/2022
+ms.date: 03/24/2023
 ms.topic: include
 ms.service: azure-communication-services
 ms.custom: mode-other
@@ -20,7 +20,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 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, and binary data for content. |
 | 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. |
@@ -172,7 +172,30 @@ async function main() {
     };
 
     const poller = await emailClient.beginSend(message);
-    const response = await poller.pollUntilDone();
+
+    if (!poller.getOperationState().isStarted) {
+      throw "Poller was not started."
+    }
+
+    let timeElapsed = 0;
+    while(!poller.isDone()) {
+      poller.poll();
+      console.log("Email send polling in progress");
+
+      await new Promise(resolve => setTimeout(resolve, POLLER_WAIT_TIME * 1000));
+      timeElapsed += 10;
+
+      if(timeElapsed > 18 * POLLER_WAIT_TIME) {
+        throw "Polling timed out.";
+      }
+    }
+
+    if(poller.getResult().status === KnownEmailSendStatus.Succeeded) {
+      console.log(`Successfully sent the email (operation id: ${poller.getResult().id})`);
+    }
+    else {
+      throw poller.getResult().error;
+    }
   } catch (e) {
     console.log(e);
   }
@@ -273,7 +296,7 @@ const message = {
   attachments: [
     {
       name: path.basename(filePath),
-      contentType: "text/plain",
+      contentType: "<mime-type-for-your-file>",
       contentInBase64: readFileSync(filePath, "base64"),
     }
   ]
@@ -282,4 +305,6 @@ const message = {
 const response = await emailClient.send(message);
 ```
 
+For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
+
 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-attachments)