Actionable Outlook Messages

A Complete Step by Step Guide

Published in

Digital Solutions — Retail & CPG

5 min readApr 18, 2022

Microsoft has introduced the concept of Adaptive Cards, which enables to build an UI script based on JSON and it can be easily embedded into different platforms such as outlook messages, teams, and chat bots. It provides a unique experience for the users to contribute information within the platforms instead of the traditional forms.

In this article, we will build a simple approval email, which contains an actionable message. It will store the response data in the backend SharePoint list. The key components required to build an actionable outlook message are,

Power Automate / Microsoft Flows (Sending Email, Receiving Data & Form Validation)
SharePoint Lists
Adaptive Card Editors (Adaptive Cards or Actionable Messages Designer (amdesigner.azurewebsites.net)

Step 1 — Register a new provider

Need to register a new provider in Actionable Email Developer Dashboard and use the provider id (originator id) in the forms to make it work as expected.

Login to the Microsoft Office 365 Connector dashboard — Actionable Messages (office.com)
Create a new provider

Get the base URL from the flow environment, which you will use as backend API and add the wildcard at the end.
This is to authorize the endpoint which will be used by the forms to submit the data from outlook

Example: https://prod-08.southeastasia.logic.azure.com:443/workflows/*

Provide the from address and the recipient information. Recommended to use the Test users first, so that you can avoid the tenant administrator approval

Copy and store the provider Id and it will be used in all the forms

Step 2— Design the outlook form

Use one of the Adaptive Card editors. I personally recommend this tool which is easy to use and works consistently so far.
Pick an existing template or create a blank form
Drag and drop the required content and configure the format as needed

Note: Keep this window open because the configuration is not yet complete. Submit action need to setup, which will happen in next few steps.

Include the originator Id in the form, directly editing the JSON file

“type”: “AdaptiveCard”,
“originator”: “60d0f3337–3215–435f-a41b-b3c22494855d”,
“version”: “1.0”,

Step 3— Design the Response Card

Similarly design the response card, which will be presented after the user submits the data.

Open a new window (Don’t close the earlier one)
Design the response card using the same process as above

You can test how it renders using the preview or Send feature, which will send this message to your mailbox
Don’t forget to include the originator id as mentioend in the previous steps.

Step 4— Build the backend API

Once the forms are designed, you need to create the backend API to capture the data and store the information.

Login into the Power Automate and Create a new flow.
Use the trigger (When a HTTP request is received) and create the flow
Generate the schema based on the payload. To decide the payload, finalize the number of elements to be captured from Outlook messages.

{
“FieldName1” : “Value1”,
“FieldName2” : “Value2”
}

Determince the next step / action once this payload is received from the outlook message. In this example, I’m going to store it in the SharePoint list after some processing.

Note: Example below contains multiple processing steps, but you can decide based on your specific use case. Also, the URL will be generated only upon saving the flow.

Important: Now you need to create the response after processing the data captured from the form
Set the code — 200 and copy paste the JSON form content from the Step 3

Important: Setup the Header CARD-UPDATE-IN-BODY as true to refresh the card

Step 5 — Create a Validation API (Refresh Card)

Once the user submits the data and again tries to open the email, it is appropriate to give the right message that the action is completed. Otherwise, it will lead to duplicate data at the backend

Create another flow to validate the user's data if user already submitted the data (like previous step)
Decide the input parameters that will help determine the data submission. At minimum, a person's email id and any reference to the object.

Determine whether the record already exists or not. Render the JSON file based on the condition check

Copy the store the validation API end point

Step 6 — Update Actions in the Form

Continue the configuration of the form designed in Step 1

Add the action (Action.Http) to the form
In the URL, copy paste the endpoint generated in Step 4
Important: Ensure to add the following headers in the exact format for the HTTP action (otherwise you will get 401 unauthorized error)

“headers”: [
{
“name”: “Authorization”,

“value”: “”

},
{
“name”: “Content-Type”,
“value”: “application/json”
}
]

Now include the autoInvokeAction to validate the form at the load. Ensure to include Authorization & Content- Type headers

“autoInvokeAction”: {
“method”: “POST”,
“url”: “Validation Endpoint URL”,
“body”: “{Content}”,
“type”: “Action.Http”
}

Now the forms are ready to be sent out

Step 7 — Sending Emails

Create a new flow to send the emails using manual trigger
Include compose step and copy paste the JSON from the editor (Step 1)
Include the Send Email step and configure it as needed. It can be sent only to the test users configured in the provider.