Edit

Send an actionable message via email in Office 365

  • Article

Important

Onboarding of new Actionable Messages providers with a Global scope is temporarily paused until Jun 30th, 2024 due to service upgrades. Existing Global scoped providers and onboarding of Organization and Test scope providers are not impacted. For more details, see Frequently asked questions for Actionable Messages.

Supported scenarios

Sending actionable messages via email is supported in the following scenarios.

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

Create an actionable message card

Let's start by creating an actionable message card. We'll start with something simple, just a basic card with an Action.Http action and an Action.OpenUrl action. We'll use the Actionable Message Designer to design the card.

Important

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

Go to the Actionable Message Designer and paste in 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. You can see the adaptive card reference for details on the available fields. Once you have a card you're happy with, you can move on to sending it.

Sending actionable messages via email

Important

You can design and test actionable messages by using the Actionable Message Designer, which allows you to send actionable messages to yourself. You can also send actionable messages to yourself using the Office 365 SMTP server. You will be unable to send actionable messages to any other user until you have registered using the actionable messages developer dashboard.

To embed an actionable message card in an email message, we need to wrap the card in a <script> tag. The <script> tag is then inserted into the <head> of the email's HTML body.

Note

Because the card JSON must be wrapped in a <script> tag, the body of the actionable message email MUST be HTML. Plain-text messages are not supported.

  1. Add the hideOriginalBody attribute to control what happens with the body of the email. In this case we'll set the attribute to true so that the body will not be 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 are 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 via SMTP with the HTML as the body.

Sending the message

For examples of sending messages, see the following.

Perform actions

For examples of performing actions, see the following.

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

Troubleshooting tools

  • Actionable Messages Debugger: an Outlook add-in that allows developers to inspect the card payload in their actionable messages and identify why the card is not rendering.