Merge pull request #218426 from anmolbohra97/main

Adding ACSEvents Documentation

Author: denrea

articles/communication-services/quickstarts/email/handle-email-events.md

@@ -0,0 +1,122 @@
+---
+title: Quickstart - Handle EMAIL and delivery report events
+titleSuffix: Azure Communication Services
+description: "In this quickstart, you'll learn how to handle Azure Communication Services events. See how to create, receive, and subscribe to Email delivery report and Email engagement tracking events."
+author: anmolbohra
+manager: komivi.agbakpem
+services: azure-communication-services
+ms.author: anmolbohra
+ms.date: 07/09/2022
+ms.topic: quickstart
+ms.service: azure-communication-services
+ms.subservice: email
+---
+# Quickstart: Handle Email events
+
+Get started with Azure Communication Services by using Azure Event Grid to handle Communication Services Email events. After subscribing to Email events such as delivery reports and engagement reports, you generate and receive these events. Completing this quickstart incurs a small cost of a few USD cents or less in your Azure account.
+
+[!INCLUDE [Public Preview Notice](../../includes/public-preview-include.md)]
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+- A Communication Services resource. For detailed information, see [Create an Azure Communication Services resource](../create-communication-resource.md).
+- An Email resource with a provisioned domain. [Create an Email Resource](../email/create-email-communication-resource.md).
+
+## About Event Grid
+
+[Event Grid](../../../event-grid/overview.md) is a cloud-based eventing service. In this article, you'll learn how to subscribe to [communication service events](../../../event-grid/event-schema-communication-services.md), and trigger an event to view the result. Typically, you send events to an endpoint that processes the event data and takes actions. In this article, we'll send the events to a web app that collects and displays the messages.
+
+## Set up the environment
+
+To set up the environment that we'll use to generate and receive events, take the steps in the following sections.
+
+### Register an Event Grid resource provider
+
+If you haven't previously used Event Grid in your Azure subscription, you might need to register your Event Grid resource provider. To register the provider, follow these steps:
+
+1. Go to the Azure portal.
+1. On the left menu, select **Subscriptions**.
+1. Select the subscription that you use for Event Grid.
+1. On the left menu, under **Settings**, select **Resource providers**.
+1. Find **Microsoft.EventGrid**.
+1. If your resource provider isn't registered, select **Register**.
+
+It might take a moment for the registration to finish. Select **Refresh** to update the status. When **Registered** appears under **Status**, you're ready to continue.
+
+### Deploy the Event Grid viewer
+
+For this quickstart, we'll use an Event Grid viewer to view events in near-real time. The viewer provides the user with the experience of a real-time feed. Also, the payload of each event should be available for inspection.
+
+To set up the viewer, follow the steps in [Azure Event Grid Viewer](/samples/azure-samples/azure-event-grid-viewer/azure-event-grid-viewer/).
+
+## Subscribe to Email events by using web hooks
+
+You can subscribe to specific events to provide Event Grid with information about where to send the events that you want to track.
+
+1. In the portal, go to the Communication Services resource that you created.
+
+1. Inside the Communication Services resource, on the left menu of the **Communication Services** page, select **Events**.
+
+1. Select **Add Event Subscription**.
+
+   :::image type="content" source="./media/handle-email-events/select-events.png" alt-text="Screenshot that shows the Events page of an Azure Communication Services resource. The Event Subscription button is called out.":::
+
+1. On the **Create Event Subscription** page, enter a **name** for the event subscription.
+
+1.  Under **Event Types**, select the events that you'd like to subscribe to. For Email, you can choose `Email Delivery Report Received` and `Email Engagement Tracking Report Received`.
+
+1. If you're prompted to provide a **System Topic Name**, feel free to provide a unique string. This field has no impact on your experience and is used for internal telemetry purposes.
+
+   :::image type="content" source="./media/handle-email-events/select-events-create-eventsub.png" alt-text="Screenshot that shows the Create Event Subscription dialog. Under Event Types, Email Delivery Report Received and Email Engagement Tracking Report Received are selected.":::
+
+1. For **Endpoint type**, select **Web Hook**.
+
+   :::image type="content" source="./media/handle-email-events/select-events-create-linkwebhook.png" alt-text="Screenshot that shows a detail of the Create Event Subscription dialog. In the Endpoint Type list, Web Hook is selected.":::
+
+1. For **Endpoint**, select **Select an endpoint**, and then enter the URL of your web app.
+
+   In this case, we'll use the URL from the [Event Grid viewer](/samples/azure-samples/azure-event-grid-viewer/azure-event-grid-viewer/) that we set up earlier in the quickstart. The URL for the sample has this format: `https://{{site-name}}.azurewebsites.net/api/updates`
+
+1. Select **Confirm Selection**.
+
+   :::image type="content" source="./media/handle-email-events/select-events-create-selectwebhook-epadd.png" alt-text="Screenshot that shows the Select Web Hook dialog. The Subscriber Endpoint box contains a URL, and a Confirm Selection button is visible.":::
+
+## View Email events
+
+To generate and receive Email events, take the steps in the following sections.
+
+### Trigger Email events
+
+To view event triggers, we need to generate some events. To trigger an event, [send email](../email/send-email.md) using the Email domain resource attached to the Communication Services resource.
+
+- `Email Delivery Report Received` events are generated when the Email status is in terminal state, i.e. Delivered, Failed, FilteredSpam, Quarantined.
+- `Email Engagement Tracking Report Received` events are generated when the email sent is either opened or a link within the email is clicked. To trigger an event, you need to turn on the `User Interaction Tracking` option on the Email domain resource
+
+Check out the full list of [events that Communication Services supports](../../../event-grid/event-schema-communication-services.md).
+
+### Receive Email events
+
+After you generate an event, you'll notice that `Email Delivery Report Received` and `Email Engagement Tracking Report Received` events are sent to your endpoint. These events show up in the [Event Grid viewer](/samples/azure-samples/azure-event-grid-viewer/azure-event-grid-viewer/) that we set up at the beginning of this quickstart. Select the eye icon next to the event to see the entire payload. Events should look similar to the following data:
+
+:::image type="content" source="./media/handle-email-events/email-delivery-report-received.png" alt-text="Screenshot of the Azure Event Grid viewer that shows the Event Grid schema for an EMAIL delivery report received event.":::
+
+:::image type="content" source="./media/handle-email-events/email-engagementtracking-report-received.png" alt-text="Screenshot of the Azure Event Grid viewer that shows the Event Grid schema for an EMAIL engagement tracking report event.":::
+
+Learn more about the [event schemas and other eventing concepts](../../../event-grid/event-schema-communication-services.md).
+
+## Clean up resources
+
+If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about [cleaning up resources](../create-communication-resource.md#clean-up-resources).
+
+## Next steps
+
+In this quickstart, you learned how to consume Email events. You can receive Email events by creating an Event Grid subscription.
+
+> [!div class="nextstepaction"]
+> [Send Email](../email/send-email.md)
+
+You might also want to:
+
+ - [Learn about event handling concepts](../../../event-grid/event-schema-communication-services.md)
+ - [Learn about Event Grid](../../../event-grid/overview.md)

articles/communication-services/quickstarts/email/media/handle-email-events/email-delivery-report-received.png

@@ -45,6 +45,8 @@ items:
         href: quickstarts/email/connect-email-communication-resource.md
       - name: Send an Email
         href: quickstarts/email/send-email.md
+      - name: Handle Email events
+        href: quickstarts/email/handle-email-events.md
       - name: Send an Email in Azure Logic Apps
         href: quickstarts/email/logic-app.md            
   - name: Telephony and phone numbers

articles/communication-services/quickstarts/email/media/handle-email-events/email-engagementtracking-report-received.png

@@ -0,0 +1,76 @@
+---
+title: Azure Communication Services - Email events
+description: This article describes how to use Azure Communication Services as an Event Grid event source for Email Events.
+ms.topic: conceptual
+ms.date: 09/30/2022
+ms.author: anmolbohra
+---
+
+# Azure Communication Services - Email events
+
+This article provides the properties and schema for communication services telephony and SMS events. For an introduction to event schemas, see [Azure Event Grid event schema](event-schema.md).
+
+## Events types
+
+Azure Communication Services emits the following telephony and SMS event types:
+
+| Event type                                                  | Description                                                                                    |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Microsoft.Communication.EmailDeliveryReportReceived                         | Published when a delivery report is received for an Email sent by the Communication Service. |
+| Microsoft.Communication.EmailEngagementTrackingReportReceived           |    Published when the Email sent is either opened or the link, if applicable is clicked.  |
+
+## Event responses
+
+When an event is triggered, the Event Grid service sends data about that event to subscribing endpoints.
+
+This section contains an example of what that data would look like for each event.
+
+### Microsoft.Communication.EmailDeliveryReportReceived event
+
+```json
+[{
+  "id": "00000000-0000-0000-0000-000000000000",
+  "topic": "/subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
+  "subject": "sender/[email protected]/message/00000000-0000-0000-0000-000000000000",
+  "data": {
+    "sender": "[email protected]", 
+    "recipient": "[email protected]",
+    "messageId": "00000000-0000-0000-0000-000000000000",
+    "status": "Delivered",
+    "DeliveryStatusDetails": "No error.",
+    "ReceivedTimestamp": "2020-09-18T00:22:20.2855749Z",
+  },
+  "eventType": "Microsoft.Communication.EmailDeliveryReportReceived",
+  "dataVersion": "1.0",
+  "metadataVersion": "1",
+  "eventTime": "2020-09-18T00:22:20Z"
+}]
+```
+
+> [!NOTE]
+> Possible values for `Status` are `Delivered`, `Expanded` and `Failed`.
+
+### Microsoft.Communication.EmailEngagementTrackingReportReceived event
+
+```json
+[{
+  "id": "00000000-0000-0000-0000-000000000000",
+  "topic": "/subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
+  "subject": "sender/[email protected]/message/00000000-0000-0000-0000-000000000000",
+  "data": {
+    "sender": "[email protected]", 
+    "messageId": "00000000-0000-0000-0000-000000000000",
+    "userActionTimeStamp": "2022-09-06T22:34:52.1303595+00:00",
+    "engagementContext": "",
+    "userAgent": "",
+    "engagementType": "view"
+  },
+  "eventType": "Microsoft.Communication.EmailEngagementTrackingReportReceived",
+  "dataVersion": "1.0",
+  "metadataVersion": "1",
+  "eventTime": "2022-09-06T22:34:52.1303612Z"
+}]
+```
+
+> [!NOTE]
+> Possible values for `engagementType` are `View`, and `Click`. When the `engagementType` is `Click`, `engagementContext` is the link in the Email sent which was clicked.

articles/communication-services/quickstarts/email/media/handle-email-events/select-events-create-eventsub.png

@@ -137,6 +137,8 @@ items:
             href: communication-services-voice-video-events.md
           - name: Presence Events
             href: communication-services-presence-events.md
+          - name: Email Events
+            href: communication-services-email-events.md
         - name: Azure Container Registry
           href: event-schema-container-registry.md
         - name: Azure Event Hubs