Edit

Get started with actionable messages in Office 365

Important

Actionable Messages are transitioning from legacy (EAT) authentication to Entra ID–based token authentication. The phase-out of legacy authentication is in progress and will be completed by June 8, 2026. After this date, integrations relying on legacy tokens will no longer function.

To ensure uninterrupted service, partners should implement support for Entra ID tokens as soon as possible. For guidance on updating your integration, please refer to Enable Microsoft Entra ID token for Actionable Messages.

Important

The Actionable Messages provider portal moved to a new location. Visit the new portal.

Supported scenarios

You can send actionable messages through email in the following scenarios.

  • The recipient must be an individual, not a group.
  • The recipient must be visible on the message. Don't put the recipient in the BCC field.
  • The recipient must have a mailbox on Outlook.com or Exchange Online in Office 365.

Note

Office 365 administrators can disable actionable messages by using the Set-OrganizationConfig cmdlet. If actionable messages don't render, check with your administrator to make sure the feature is enabled in your organization.

Create an actionable message card

Let's start with something simple - a basic card with an Action.Http action and an Action.OpenUrl action. Use the Actionable Message Designer to design the card.

Important

The sample card markup in this topic omits the originator property. This omission works in a testing scenario, where the recipient is the same as the sender. When sending actionable messages to anyone else, set the originator property to a valid provider ID generated by the Actionable Email Developer Dashboard. If you leave this property empty when sending to others, the card is removed.

Go to the Actionable Message Designer and paste the following JSON:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Visit the Outlook Dev Portal",
      "size": "large"
    },
    {
        "type": "TextBlock",
        "text": "Click **Learn More** to learn more about Actionable Messages!"
    },
    {
      "type": "Input.Text",
      "id": "feedbackText",
      "placeholder": "Let us know what you think about Actionable Messages"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Send Feedback",
      "method": "POST",
      "url": "https://...",
      "body": "{{feedbackText.value}}"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Learn More",
      "url": "https://learn.microsoft.com/outlook/actionable-messages"
    }
  ]
}

Feel free to experiment with this simple example in the Designer. For details on the available fields, see the adaptive card reference. When you have a card you're happy with, you can move on to sending it.

Sending actionable messages through email

Important

To design and test actionable messages, use the Actionable Message Designer. It sends actionable messages to you. You can also use the Office 365 SMTP server to send actionable messages to yourself. You can't send actionable messages to other users until you register through the actionable messages developer dashboard.

To embed an actionable message card in an email message, wrap the card in a <script> tag. Insert the <script> tag into the <head> of the email's HTML body.

Note

Because you must wrap the card JSON in a <script> tag, the body of the actionable message email must be HTML. Plain-text messages aren't supported.

  1. Add the hideOriginalBody attribute to control what happens with the body of the email. Set the attribute to true so that the body isn't shown.

    {
  "type": "AdaptiveCard",
  "version": "1.0",
  "hideOriginalBody": true,
  "body": [
    {
      "type": "TextBlock",
      "text": "Visit the Outlook Dev Portal",
      "size": "large"
    },
    {
        "type": "TextBlock",
        "text": "Click **Learn More** to learn more about Actionable Messages!"
    },
    {
      "type": "Input.Text",
      "id": "feedbackText",
      "placeholder": "Let us know what you think about Actionable Messages"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Send Feedback",
      "method": "POST",
      "url": "https://...",
      "body": "{{feedbackText.value}}"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Learn More",
      "url": "https://learn.microsoft.com/outlook/actionable-messages"
    }
  ]
}

  2. Wrap the resulting JSON in a <script> tag of type application/adaptivecard+json.

    Note

    If you're using the legacy message card format rather than the Adaptive Card format, the <script> tag type must be application/ld+json.

    <script type="application/adaptivecard+json">{
  "type": "AdaptiveCard",
  "version": "1.0",
  "hideOriginalBody": true,
  "body": [
    {
      "type": "TextBlock",
      "text": "Visit the Outlook Dev Portal",
      "size": "large"
    },
    {
        "type": "TextBlock",
        "text": "Click **Learn More** to learn more about Actionable Messages!"
    },
    {
      "type": "Input.Text",
      "id": "feedbackText",
      "placeholder": "Let us know what you think about Actionable Messages"
    }
  ],
  "actions": [
    {
      "type": "Action.Http",
      "title": "Send Feedback",
      "method": "POST",
      "url": "https://...",
      "body": "{{feedbackText.value}}"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Learn More",
      "url": "https://learn.microsoft.com/outlook/actionable-messages"
    }
  ]
}
</script>

  3. Generate an HTML document to represent the email body and include the <script> tag in the <head>.

    <html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <script type="application/adaptivecard+json">{
    "type": "AdaptiveCard",
    "version": "1.0",
    "hideOriginalBody": true,
    "body": [
      {
        "type": "TextBlock",
        "text": "Visit the Outlook Dev Portal",
        "size": "large"
      },
      {
        "type": "TextBlock",
        "text": "Click **Learn More** to learn more about Actionable Messages!"
      },
      {
        "type": "Input.Text",
        "id": "feedbackText",
        "placeholder": "Let us know what you think about Actionable Messages"
      }
    ],
    "actions": [
      {
        "type": "Action.Http",
        "title": "Send Feedback",
        "method": "POST",
        "url": "https://...",
        "body": "{{feedbackText.value}}"
      },
      {
        "type": "Action.OpenUrl",
        "title": "Learn More",
        "url": "https://learn.microsoft.com/outlook/actionable-messages"
      }
    ]
  }
  </script>
</head>
<body>
Visit the <a href="https://learn.microsoft.com/outlook/actionable-messages">Outlook Dev Portal</a> to learn more about Actionable Messages.
</body>
</html>

  4. Send a message through SMTP with the HTML as the body.

Sending the message

For examples of sending messages, see the following resources:

Perform actions

For examples of performing actions, see the following resources:

  • Hello Actionable Messages: A sample project with one-click Azure deployment. This sample is a simple end-to-end actionable message solution that you can set up and start using within 10 minutes. It serves as a reference for building a production action endpoint.

Troubleshooting tools

  • Actionable Messages Debugger: An Outlook add-in that developers use to inspect the card payload in their actionable messages and identify why the card isn't rendering.
  • Last updated on