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.
- An Azure account with an active subscription. Create an account for free.
- A Communication Services resource. For detailed information, see Create an Azure Communication Services resource.
- An Email resource with a provisioned domain. Create an Email Resource.
About Event Grid
Event Grid is a cloud-based eventing service. In this article, you'll learn how to subscribe to communication service events, 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:
- Go to the Azure portal.
- On the left menu, select Subscriptions.
- Select the subscription that you use for Event Grid.
- On the left menu, under Settings, select Resource providers.
- Find Microsoft.EventGrid.
- 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.
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.
In the portal, go to the Communication Services resource that you created.
Inside the Communication Services resource, on the left menu of the Communication Services page, select Events.
Select Add Event Subscription.
On the Create Event Subscription page, enter a name for the event subscription.
Under Event Types, select the events that you'd like to subscribe to. For Email, you can choose
Email Delivery Report Receivedand
Email Engagement Tracking Report Received.
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.
For Endpoint type, select Web Hook.
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 that we set up earlier in the quickstart. The URL for the sample has this format:
Select Confirm Selection.
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 using the Email domain resource attached to the Communication Services resource.
Email Delivery Report Receivedevents are generated when the Email status is in terminal state, i.e. Delivered, Failed, FilteredSpam, Quarantined.
Email Engagement Tracking Report Receivedevents 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 Trackingoption on the Email domain resource
Check out the full list of events that Communication Services supports.
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 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:
EngagementContextrefers to the link clicked when the engagementType is
UserAgentrefers to the User-Agent from which this email engagement event originated. Eg. If the user interacted on Edge using a Win10 machine: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246
EngagementTyperefers to the type of engagement, possible values are 'View' or 'Click'.
Learn more about the event schemas and other eventing concepts.
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.
In this quickstart, you learned how to consume Email events. You can receive Email events by creating an Event Grid subscription.
For schema information and example events, see Azure Communication Services - Email events.
You might also want to see the following articles: