Designing Outlook Actionable Message cards with the Adaptive Card format

Outlook Actionable Messages cards are designed using the Adaptive Card format. The Adaptive Card format is a simple yet powerful declarative layout format that provides a lot of flexibility, allowing for visually rich cards. In this topic we'll cover the Outlook-specific features of the Adaptive Card format.

Actionable Message Designer

The Actionable Message Designer provides a drag-and-drop experience to quickly build and tweak adaptive cards. There you will find Adaptive Card samples that can help you get started crafting your own cards and also allows you to send those cards to your own Microsoft 365 email account to see how they look in Outlook.

A simple Adaptive Card example

The above card illustrates some of the core and most powerful capabilities of the Adaptive Card format:

• The ability to stack elements of various types in any order
• The ability to control the amount of space between those elements
• The ability to layout elements in multiple columns
• The ability to align elements horizontally and vertically

Here is how this card is crafted:

{
  "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0",
  "type": "AdaptiveCard",
  "speak": "<s>Your flight is confirmed for you and 3 other passengers from San Francisco to Amsterdam on Friday, October 10 8:30 AM</s>",
  "body": [
    {
      "type": "ColumnSet",
      "columns": [
        {
          "width": "stretch",
          "verticalContentAlignment": "center",
          "items": [
            {
              "type": "TextBlock",
              "size": "medium",
              "text": "**FLIGHT ITINERARY - CONTOSO AIR**"
            },
            {
              "type": "TextBlock",
              "spacing": "none",
              "text": "Passenger: David Claux",
              "isSubtle": true
            }
          ]
        },
        {
          "width": "auto",
          "items": [
            {
              "type": "Image",
              "width": "48px",
              "url": "http://lh3.googleusercontent.com/ik5VKcUE5U7qGSpU3XWwAwe_zeOnHU5x_79o-VXf-C_EGrFPHp4-NcKRCtblrJM5iO61=w300"
            }
          ]
        }
      ]
    },
    {
      "type": "TextBlock",
      "text": "2 Stops",
      "weight": "bolder",
      "spacing": "medium"
    },
    {
      "type": "TextBlock",
      "text": "Fri, October 10 8:30 AM",
      "weight": "bolder",
      "spacing": "none"
    },
    {
      "type": "ColumnSet",
      "separator": true,
      "columns": [
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "text": "San Francisco",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "size": "extraLarge",
              "color": "accent",
              "text": "SFO",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {
              "type": "TextBlock",
              "text": "&nbsp;"
            },
            {
              "type": "Image",
              "url": "https://messagecardplayground.azurewebsites.net/assets/airplane.png",
              "size": "small",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "text": "Amsterdam",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "size": "extraLarge",
              "color": "accent",
              "text": "AMS",
              "spacing": "none"
            }
          ]
        }
      ]
    },
    {
      "type": "TextBlock",
      "text": "Non-Stop",
      "weight": "bolder",
      "spacing": "medium"
    },
    {
      "type": "TextBlock",
      "text": "Fri, October 18 9:50 PM",
      "weight": "bolder",
      "spacing": "none"
    },
    {
      "type": "ColumnSet",
      "separator": true,
      "columns": [
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "text": "Amsterdam",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "size": "extraLarge",
              "color": "accent",
              "text": "AMS",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {
              "type": "TextBlock",
              "text": "&nbsp;"
            },
            {
              "type": "Image",
              "url": "https://messagecardplayground.azurewebsites.net/assets/airplane.png",
              "size": "small",
              "spacing": "none"
            }
          ]
        },
        {
          "type": "Column",
          "width": 1,
          "items": [
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "text": "San Francisco",
              "isSubtle": true
            },
            {
              "type": "TextBlock",
              "horizontalAlignment": "right",
              "size": "extraLarge",
              "color": "accent",
              "text": "SFO",
              "spacing": "none"
            }
          ]
        }
      ]
    }
  ]
}

Adaptive Card design tips

An Adaptive Card can be very simple or quite complex depending on the layout you wish to achieve. It is always a good idea to plan your design ahead of writing the Adaptive Card payload, using a paint tool for instance or even just pen and paper; this will make it a lot easier to translate visuals into the appropriate Adaptive Card constructs. Below are a few design tips to help you get started.

Text formatting

All TextBlock elements in a card can be formatted using Markdown. Outlook supports basic Markdown.

Design for a narrow screen

Just like when designing the HTML body of an email, you have to assume that your Adaptive Card might be displayed on both wide and narrow screens (e.g. a desktop and a mobile phone.)

Craft your images with high DPI screens in mind

Not so long ago, most screens had a somewhat low resolution (1024x768 pixels for instance) and were operating at 96 DPI (Dots Per Inch), meaning that 96 pixels would fit within an actual inch of the screen. But in the past few years, screens have grown considerably in terms of resolution and DPI, especially on mobile devices, and it is now very common for a screen to operate at 192 DPI or even more.

When designing your Adaptive Cards, you need to make sure your images will look good on any screen regardless of its DPI.

Use of containers

Use the Container element only when necessary. The Container element makes it possible to group a set of elements together.

Use of columns

Use ColumnSet only when you need to align several elements on a single horizontal line.

Outlook-specific Adaptive Card properties and features

Outlook introduces a set of additional Adaptive Card properties and features for use in the context of Actionable Messages.

Adaptive Card features not supported with Outlook Actionable Messages

Action.Submit

The Action.Submit action type is NOT supported with Outlook Actionable Messages. If you include an Action.Submit in your card, it will not be displayed.

Input.Time

The Input.Time element type is NOT supported with Outlook Actionable Messages. If you include an Input.Time element in your card, it will not be displayed. If you need to allow users to input a time, use an Input.Text instead and validate its value server-side.

Action.Http

Outlook Actionable Messages use an HTTP-based action model via the Action.Http type. Action.Http makes it possible to make a GET or POST request to a specific target url as a result of a user taking an action in a card.

HttpHeader

Action.Http example

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Hello world!"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Click me!",
      "method": "POST",
      "url": "https://contoso.com/api/...",
      "body": "<body of the POST request>",
      "headers": [
        { "name": "Content-Type", "value": "application/json" }
      ]
    }
  ]
}

Implementing the Web API

The URL specified in the url property must conform to the following requirements.

• The endpoint must accept POST requests.
• The endpoint should accept the contents of the body property.
• The endpoint should use the JWT sent in the Authorization header to verify that requests come from Microsoft.

Input value substitution

Adaptive Cards may contain inputs, and it may be necessary to pass the values of these inputs to the target endpoint via an Action.Http action. This is done using input value substitution. Consider the following example:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "What's your name?"
    },
    {
      "type": "Input.Text",
      "id": "nameInput",
      "placeholder": "Type your name"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Say hello",
      "method": "GET",
      "url": "https://contoso.com/sayhello?name={{nameInput.value}}"
    }
  ]
}

The above card defines a text input and sets it id property to nameInput. It also defines an Action.Http action that makes a GET call to an endpoint on domain contoso.com. With the inclusion of ?name={{nameInput.value}} on the target URL, the value of the input with id nameInput will be dynamically substituted at the time the action is taken by the user. So if the user had entered the name David in the text input, the target URL after substitution would be https://contoso.com/sayhello?name=David

Input value substitution also works in the body property of an Action.Http action. For example:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "What's your name?"
    },
    {
      "type": "Input.Text",
      "id": "nameInput",
      "placeholder": "Type your name"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Say hello",
      "method": "POST",
      "url": "https://contoso.com/sayhello",
      "body": "{{nameInput.value}}"
    }
  ]
}

Reporting Action.Http execution success or failure

Your service should return an HTTP 200 status code when it successfully executes an Action.Http action. If the action execution fails, your service should return an HTTP 4xx status code, and it should also include the CARD-ACTION-STATUS HTTP header in its response to specify a custom error message. The value of that header will be displayed to the end-user in case the Action.Http fails to execute.

Refresh cards

Refresh cards are a very powerful mechanism that allow Action.Http actions to fully update the card on the fly as the action successfully completes. There are many scenarios that benefit from refresh cards:

• Approval scenario (e.g. expense report)
  • Once the request is approved or rejected, the card is refreshed to remove the approve/decline actions and update its content so it reflects the fact that it's been approved or declined.
• Task status
  • When an action is taken on a task, such as setting its due date, the card refreshes to include the updated due date in its facts.
• Survey
  • Once the question has been answered, the card is refreshed so:
    • It no longer allows the user to respond.
    • It shows updated status, like "Thanks for responding to this survey" alongside the user's actual response.
    • Potentially include a new Action.OpenUrl action that allows the user to consult the survey online.

To refresh a card as a result of an Action.Http action, a service needs to do the following:

• Include the JSON payload of the new card in the body of the response to the HTTP POST request it received.
• Add the CARD-UPDATE-IN-BODY: true HTTP header to the response, in order to let the receiving client know that it should parse the response body and extract a new card (this is to avoid unnecessary processing when no refresh card is included.)

Action.InvokeAddInCommand

The Action.InvokeAddInCommand action opens an Outlook add-in task pane. If the add-in is not installed, the user is prompted to install the add-in with a single click.

When an Action.InvokeAddInCommand action is executed, Outlook first checks if the requested add-in is installed and turned on for the user. If it is not, the user is notified that the action requires the add-in, and is able to install and enable the add-in with a single click. Outlook opens the requested task pane, making any initialization context specified by the action available to the add-in.

For more information, see Invoke an Outlook add-in from an actionable message.

Action.DisplayMessageForm

The Action.DisplayMessageForm action opens the read form of a message given that message's ID. Message IDs can be retrieved via the Outlook REST APIs.

Action.DisplayAppointmentForm

The Action.DisplayAppointmentForm action opens the read form of a calendar item given that calendar item's ID. Calendar item IDs can be retrieved via the Outlook REST APIs.

Action.ToggleVisibility

The Action.ToggleVisibility action makes it possible to show and/or hide specific elements of a card as a result of a user clicking on a button or other actionable element. Coupled with the isVisible property, Action.ToggleVisibility allows for an extra degree of interactivity within a single card.

TargetElement

Action.ToggleVisibility example

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "**Action.ToggleVisibility example**: click the button to show or hide a welcome message"
    },
    {
      "type": "TextBlock",
      "id": "helloWorld",
      "isVisible": false,
      "text": "**Hello World!**",
      "size": "extraLarge"
    }
  ],
  "actions": [
    {
      "type": "Action.ToggleVisibility",
      "title": "Click me!",
      "targetElements": [ "helloWorld" ]
    }
  ]
}

The example card renders similar to the following before the button is clicked:

The example card renders similar to the following after the button is clicked:

ActionSet element

Outlook Actionable Messages add support for the ActionSet element that makes it possible to add action buttons anywhere in a card.

Aside from the fact that ActionSet can be placed anywhere in the card, it behaves exactly like the actions property of an AdaptiveCard.

ActionSet example

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
      {
        "type": "ActionSet",
        "actions": [
          {
            "type": "Action.ToggleVisibility",
            "title": "Click me!",
            "targetElements": [ "helloWorld" ]
          }
        ]
      },
      {
        "type": "TextBlock",
        "text": "**Action.ToggleVisibility example**: click the button above to show or hide a welcome message"
      },
      {
        "type": "TextBlock",
        "id": "helloWorld",
        "isVisible": false,
        "text": "**Hello World!**",
        "size": "extraLarge"
      }
  ]
}

Additional properties on all Adaptive Card element types

Please refer to the previous example for an illustration of how to use isVisible.

Additional properties on the AdaptiveCard type

The following additional properties can be specified on an AdaptiveCard object in the context of Outlook Actionable Messages:

Additional properties on the Column type

The following additional properties can be specified on a Column object in the context of Outlook Actionable Messages:

Column width values

If width is expressed as a number, it represents the relative weight of the Column within its ColumnSet. For a weighted Column to really be useful, there should be at least one more weighted Column in the set. For example, if column A has its width set to 1 and column B has its width set to 2, then column A will use a third of the available space in the set, while column B will use the remaining two-thirds.

If width is expressed as a string, it can have the following values:

• auto: The Column will use as much of the available space as is required to fit its content.
• stretch: The Column will use whatever space remains in the set. If multiple columns have their width property set to stretch, they all share the remaining space equally.
• <number>px (ex. 50px): The column will spread across the specified number of pixels.
• <number>*, (ex. 1*): This is equivalent to specifying width as a number.

Column example

{
  "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "ColumnSet",
      "columns": [
        {
          "width": "50px",
          "items": [
            {
              "type": "Image",
              "url": "https://adaptivecards.io/content/cats/1.png",
              "size": "stretch"
            }
          ]
        },
        {
          "width": "stretch",
          "verticalContentAlignment": "center",
          "items": [
            {
              "type": "TextBlock",
              "text": "This card has two ColumnSets on top of each other. In each, the left column is explicitly sized to be 50 pixels wide.",
              "wrap": true
            }
          ]
        }
      ]
    },
    {
      "type": "ColumnSet",
      "columns": [
        {
          "width": "50px"
        },
        {
          "width": "stretch",
          "verticalContentAlignment": "center",
          "items": [
            {
              "type": "TextBlock",
              "text": "In this second ColumnSet, columns align perfectly even though there is nothing in the left column.",
              "wrap": true
            }
          ]
        }
      ]
    }
  ]
}

Additional properties on the Container type

The following additional properties can be specified on a Container object in the context of Outlook Actionable Messages:

These properties behave exactly like their counterpart on the Column type. Please refer to the above example.

Additional properties on the Image type

The following additional properties can be specified on an Image object in the context of Outlook Actionable Messages:

Image properties example

{
  "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Below, the same image is presented on top of two different background colors."
    },
    {
      "type": "Image",
      "width": "64px",
      "url": "https://messagecardplayground.azurewebsites.net/assets/circleontransparentbackground.png",
      "backgroundColor": "#FF0000"
    },
    {
      "type": "Image",
      "style": "person",
      "width": "64px",
      "url": "https://messagecardplayground.azurewebsites.net/assets/circleontransparentbackground.png",
      "backgroundColor": "#0000FF"
    }
  ]
}

See also

• Adaptive Card portal