man thinking

Actionable Messages and Adaptive Cards

The Problem

You open Outlook and see you have a message that you've been putting off dealing with for a while. The expenses system has sent you an approval request:

Approval request Email

That looks fine - John did go down to London to meet the client. It seems a bit expensive, and why is it in dollars? Oh well, perhaps there will be a bit more detail when you follow the helpful link into the expenses system. You click on the link and now you're no longer in Outlook - you're in a browser window looking at a login prompt. It's the expenses system and you need to supply your credentials, so you starting looking for that sticky-note with the password, and then you log in.

But the people who wrote the expenses system didn't quite get the authentication flow right and you're now in the expenses system home page, so you'll have to go searching for John's claim. You eventually find it and see an itemised list, and it barely looks plausible, but you've already spent too much time on this so you approve it and close the browser window.

The phone rings...

Some time later you go back to Outlook and decide to clear out your inbox. You deal with a few items and then there's an expenses claim for John D... wait - did you actually approve that one or did you get interrupted? You check the browser - nothing open. Better log back in and check...

This is really inefficient with lots of context switching and no real confirmation that the problem is dealt with.

Actionable Messages

This is where Actionable Messages come in. Instead of just giving you a link to another application, an actionable message renders with a card containing controls that perform the actions. So in the example above, an actionable message would contain all the information needed to make a decision and then two buttons - Approve and Reject. When you click Approve that's it - the expense is approved and the message contents change to show that you approved the request. No need to ever leave Outlook, and if you ever open the message again you will be able to see immediately that it has been dealt with already. It seems like magic, and users love it because there is such a huge productivity boost.

Expense Approval Email

So how does it work? An email containing an Actionable Message has a block of JSON appended in the Adaptive Card format (more about this later). The JSON contains all the information that needs to be presented to the user to make a decision. The JSON also includes controls such as buttons that can invoke actions such as an HTML POST to an application end-point. That could be a web application or an Azure Function, for example. The action can also return another card such as one saying "You approved" or even a prompt for a further action. You can also invoke an Office Add-in.

Of course all this works because the Outlook client application (or the web version) knows how to interpret the special markup for the Actionable Message. It's not going to work if you use some other mail client that hasn't implemented Adaptive Cards, or an ancient version of Outlook. The support in mobile Outlook clients was also a work in progress at the time of writing. To find out what the current state of support is, see the documentation which is always kept up-to-date.

As well as approving reports you can use Actionable Messages for filling out surveys, updates, reacting to events and issues and responding to requests, in fact anywhere you need users to take quick actions without having to leave Outlook. By embedding actions in their emails or notifications there is a measurable increase in user engagement with services and much greater user productivity. For example, it was found that the expense approval process went from days to hours or even minutes using Actionable Messages, because managers didn't feel they needed to park approval requests for later - it was so easy to deal with right after opening the email. The efficiency of that quick turnaround flows through the organization because people aren't waiting.

Adaptive Cards

Outlook Actionable Messages originally used a legacy card format (Message Card) but are now able to use the newer Adaptive Card format. Adaptive Cards are much more powerful and flexible, and yet maintain a simple declarative layout in JSON (JavaScript Object Notation). You can find out more about the details of the Adaptive Card format from the documentation.

There is an Actionable Message Designer site which supports the Adaptive Card format. This includes a number of samples that will get you started designing your own cards. You can also send cards to your Office 365 email account to test them in Outlook.

Actionable Message Designer

Adaptive Cards are used throughout Microsoft 365 in addition to Outlook. There is an online designer for Adaptive Cards specifically, which allows you to see how Adaptive Cards look on different platforms and host applications.


Imagine being able to provide your users with an incredible productivity boost with almost no development effort! You can with Outlook Actionable Messages and you’ll be their developer hero! You’ll build solutions that take advantage of the latest version of Adaptive Cards that make it easy to create rich interactive emails that let users take quick actions, all without ever having to leave Outlook or switch context. You can also use Adaptive Cards in other parts of Microsoft 365, like Windows, Microsoft Teams and Cortana. Adaptive Cards allow us to create Line-of-Business applications and processes like task management and report approval, and create a large, measurable return on investment for your company.

Office and SharePoint Live!, Orlando, November, 2019

Live! 360 conference, Orlando

If you are in Orlando for Ignite, why not take an extra week's holiday and then join me on November 17th for a week of learning? I'll present my talk on Adaptive Cards and Actionable Messages and I'll also cover this and other topics in my one-day workshop on Friday 22nd November. The conference is part of Live360! which is a multi-track conference with amazing speakers on a range of topics including Visual Studio, SQL Server, AI and cloud. The Promo Code SPKLIVE3 should give you $400 off the standard pricing for both the 6-Day and 5-Day Packages if you're quick!

European SharePoint Conference, Prague, 2019

ESPC Prague, December 2019

Join me on Tuesday 3rd of December for my session “Turn Your Business Productivity Up To 11 with Actionable Messages and Adaptive Cards”

For those of you who haven’t been before, or are thinking of attending, ESPC is a really fun, welcoming event with a big focus on the topics and learning. It brings together an amazing group of speakers, sponsors and delegates, including Microsoft Leaders, Product Team members and leading community RDs, MVPs and MCMs, so we can all help each other achieve great things with SharePoint, Office 365 or Azure.

If you are planning to attend, don’t forget, you or your team can use my coupon code ESPC19SPK to receive a special €100 discount.