diff --git a/docs/actionable-messages/actionable-messages-faq.md b/docs/actionable-messages/actionable-messages-faq.md index f4db057b..7d75f8aa 100644 --- a/docs/actionable-messages/actionable-messages-faq.md +++ b/docs/actionable-messages/actionable-messages-faq.md @@ -5,95 +5,88 @@ author: avijityadav ms.topic: reference ms.service: outlook ms.subservice: o365-connectors -ms.date: 04/08/2023 -ms.author: avyad +ms.date: 06/10/2026 +ms.author: vermaanimesh ms.localizationpriority: high --- + # Frequently asked questions for Actionable Messages -This section contains the frequently asked questions for Actionable Messages and the answers. +Find answers to common questions about Actionable Messages. ## Registration process -### I am unable to open the AM Developer Dashboard . How can I proceed? +### I can't open the AM Developer Dashboard. How can I proceed? -If you are facing errors when opening the [AM Developer Dashboard](https://outlook.office.com/connectors/oam/publish) then please follow the below steps to mitigate. +If you encounter errors when opening the [AM Developer Dashboard](https://aka.ms/ActionableMessagesPortal), follow these steps to resolve the issue. -1. Open [Outlook Web Email](https://outlook.office.com/mail/) -2. In the next tab open the [AM Developer Dashboard](https://outlook.office.com/connectors/oam/publish) +1. Open [Outlook Web Email](https://outlook.office.com/mail/). +1. In the next tab, open the [AM Developer Dashboard](https://aka.ms/ActionableMessagesPortal). -*This is a known issue and is being fixed* +*This is a known issue and is being fixed.* -### I am trying to fill in the registration form but getting error while submitting. How can I proceed? +### I try to fill in the registration form but get an error while submitting. How can I proceed? -This might happen if there are some fields that contain unexpected values. +This error might happen if some fields contain unexpected values. -1. Please recheck all the fields again. -1. Try to use smaller size payload and check that HTML tags are not used. -1. In case you do not find any discrepancy, please remove the card payload json and submit again. If the form is submitted, please send the card payload separately to [onboardoam@microsoft.com](mailto:onboardoam@microsoft.com) along with your originator ID. +1. Check all the fields again. +1. Try using a smaller payload and confirm that HTML tags aren't used. +1. If you don't find any discrepancy, remove the card payload JSON and submit again. If the form submits successfully, send the card payload separately to [onboardoam@microsoft.com](mailto:onboardoam@microsoft.com) along with your originator ID. -### I have submitted a registration request with organization scope. Who will approve my registration? +### I submitted a registration request with organization scope. Who approves my registration? -For an organization scope registration of Actionable Messages, the approval of the registration depends on the policies of your organization. Typically, the person or team responsible for managing the M365 tenant will need to approve the registration of Actionable Messages. This could be an IT administrator, a security team, or another group within the organization that is responsible for managing Office 365. +For an organization scope registration of Actionable Messages, the approval process depends on your organization's policies. Typically, the person or team responsible for managing the M365 tenant needs to approve the registration of Actionable Messages. This role could be an IT administrator, a security team, or another group within the organization that's responsible for managing Office 365. -To check who are your organization IT admins, follow the following steps : +To check who your organization's IT admins are, follow these steps: 1. Go to [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). -1. Make a GET request using `https://graph.microsoft.com/v1.0/directoryRoles` request URL. This will show the list of roles in your tenant. -1. In the response you can search for **Exchange Administrator** and **Global Administrator**. -1. In some tenants **Exchange Administrator** might not be present. If the **Exchange Administrator** role is not listed then you can use the `id` from the **Global Administrator** role to fetch the list of tenant admins. +1. Make a GET request with `https://graph.microsoft.com/v1.0/directoryRoles` as the request URL. This request returns the list of roles in your tenant. +1. In the response, search for **Exchange Administrator** and **Global Administrator**. +1. In some tenants, **Exchange Administrator** might not be present. If the **Exchange Administrator** role isn't listed, use the `id` from the **Global Administrator** role to fetch the list of tenant admins. -### How can I update details for an approved global scoped Actionable message registration? +### How can I update details for an approved globally scoped Actionable Message registration? -To update details for an approved global scoped Actionable Message provider, you can reach out to [onboardoam@microsoft.com](mailto:onboardoam@microsoft.com) with updated details. Our team will acknowledge and update it in backend. Please note that any update will take 2 weeks after the team acknowledges your update. +To update details for an approved globally scoped Actionable Message provider, contact [onboardoam@microsoft.com](mailto:onboardoam@microsoft.com) with the updated details. The team acknowledges your request and updates it in the backend. Any update takes two weeks after the team acknowledges your request. ## Actionable Message Rendering -### Actionable card does not show up in Outlook desktop but works fine in Outlook on the web. +### Actionable card doesn't show up in Outlook desktop but works fine in Outlook on the web. -If you don't see the Actionable Message in Outlook desktop, please confirm the following: +If you don't see the Actionable Message in Outlook desktop, confirm the following conditions: -1. Your download preferences are set to "Download full items". It should look like the following image. +1. Your download preferences are set to **Download full items**. It should look like the following image. :::image type="content" source="images/download-preference.png" alt-text="Download preferences to see actionable messages"::: -1. You are not using any screen reader. -1. Please also check if the following registry key is set to 0 - `HKEY_CURRENT_USER\Control Panel\Accessibility\Blind Access\On`. +1. You're not using any screen reader. +1. The following registry key is set to 0 - `HKEY_CURRENT_USER\Control Panel\Accessibility\Blind Access\On`. -### Actionable messages work as expected with user mailboxes but not with Group or shared mailboxes. +### Actionable messages work as expected with user mailboxes but not with group or shared mailboxes -This is the expected behavior. Actionable Messages are only supported with single user mailboxes. Group and shared mailboxes are not supported. +This behavior is expected. Actionable Messages only support single user mailboxes. Group and shared mailboxes aren't supported. -### Users from my organization are not able to use Actionable Messages and the action redirects them to webpage. +### Users from my organization can't use Actionable Messages and the action redirects them to a webpage -Please check if the organization uses Mimecast or other similar services. Mimecast changes emails in ways that prevent Actionable Messages workflow. +Check if your organization uses Mimecast or other similar services. Mimecast changes emails in ways that prevent Actionable Messages workflow. To verify that this is the cause: -1. Disable Mimecast temporarily and send a new Actionable Message. -1. Add "schema.org" domain or `http://schema.org/extensions` to Mimecast exception list. +1. Temporarily disable Mimecast and send a new Actionable Message. +1. Add the "schema.org" domain or `http://schema.org/extensions` to the Mimecast exception list. -### Is there a limit to number of Actionable messages that can be opened in Outlook at one time? +### Is there a limit to the number of Actionable Messages that can be opened in Outlook at one time? -To maintain optimal performance, we allow a maximum of 10 actionable messages emails to be opened at one time. Trying to open more than that at the same time will shown an error. +To maintain optimal performance, you can open up to 10 actionable message emails at one time. If you try to open more than that number at the same time, an error appears. -### Is there a time limit before which actions can be taken on Actionable messages? +### Is there a time limit on taking actions on Actionable Messages? -Actionable messages are typically designed for quick actions on emails. Hence, you cannot take actions of an Actionable messages that is more than a month old. +Actionable Messages are typically designed for quick actions on emails. As a result, you can't take actions on an Actionable Message that is more than a month old. -## Upgrading to Adaptive Card 1.4 and above +## Upgrading to Adaptive Card 1.4 and later -### I have upgraded the Adaptive card version from 1.0 to 1.4, and my Action buttons have disappeared. +### I upgraded the Adaptive Card version from 1.0 to 1.4, and my action buttons disappeared -Action execution paradigm has changed in Adaptive card version 1.4. We have started supporting [Action.Execute](https://adaptivecards.io/explorer/Action.Execute.html) in place of `Action.Http`. For more information, see [code sample using Adaptive cards 1.4+](./adaptive-card-expense-approval-sample.md). - -## Actionable Message onboarding paused till June 15, 2024 - -### I have submitted a Global scoped registration but it's not yet approved. - -Due to a service upgrade, onboarding for **Global** scoped registrations is temporarily paused until June 30, 2024. Registrations for Actionable Messages with **Organization** and **Test** scopes remain unaffected and will continue to operate as expected during this period. - -For those affected by the pause in **Global** scope onboarding, please prepare your services and await the resumption of the process. For any queries or assistance during this period, please reach out to the Actionable Messages team through the usual channels. +The action execution paradigm changed in Adaptive Card version 1.4. The platform now supports [Action.Execute](https://adaptivecards.io/explorer/Action.Execute.html) in place of `Action.Http`. For more information, see [code sample using Adaptive cards 1.4+](./adaptive-card-expense-approval-sample.md). diff --git a/docs/actionable-messages/adaptive-card-expense-approval-sample.md b/docs/actionable-messages/adaptive-card-expense-approval-sample.md index ab815bf2..402690c0 100644 --- a/docs/actionable-messages/adaptive-card-expense-approval-sample.md +++ b/docs/actionable-messages/adaptive-card-expense-approval-sample.md @@ -17,7 +17,7 @@ This sample illustrates the Universal Action Model implementation available for ## Prerequisites - Outlook/OWA client is available and you have an account. -- A valid Azure subsciption. +- A valid Azure subscription. - Understanding of [Azure Bot Framework](/azure/bot-service/bot-builder-basics). ## Setup for bot @@ -28,7 +28,7 @@ This sample illustrates the Universal Action Model implementation available for - Open the **Channels** pane. - Select the **Outlook** channel in *Available Channels* section. - Under the **Actionable Messages** tab, Click **Apply** followed by **please register here**. - - Fill out the registration form to request access. See [Register your service with the actionable email developer dashboard](./email-dev-dashboard.md) for more information. + - Fill out the registration form to request access. See [Register your service with the actionable email developer dashboard](https://aka.ms/ActionableMessagesPortal) for more information. - Create your bot with the Bot Framework SDK, following the instruction [here](/azure/bot-service/bot-service-quickstart-create-bot). ## Step 1: Ensure your adaptive card payloads are ready diff --git a/docs/actionable-messages/adaptive-card-project-management-sample.md b/docs/actionable-messages/adaptive-card-project-management-sample.md index 8b8a7378..ed184c05 100644 --- a/docs/actionable-messages/adaptive-card-project-management-sample.md +++ b/docs/actionable-messages/adaptive-card-project-management-sample.md @@ -5,35 +5,37 @@ author: avijityadav ms.topic: sample ms.service: outlook ms.subservice: o365-connectors -ms.date: 04/08/2023 -ms.author: avyad +ms.date: 06/10/2026 +ms.author: vermaanimesh ms.localizationpriority: high --- + + # Universal Actions Model code sample - Project Management This sample illustrates the Universal Action Model implementation available for adaptive cards version 1.4 or higher. ## Prerequisites -- Outlook/OWA client is available and you have an account. +- Outlook or OWA client is available and you have an account. - A valid Azure subscription. - Understanding of [Azure Bot Framework](/azure/bot-service/bot-builder-basics). ## Setup for bot -- Register a bot with Azure Bot Service, following the instructions [here](/azure/bot-service/bot-service-quickstart-registration). -- Ensure that you've [enabled the Outlook Channel](/azure/bot-service/bot-service-channel-connect-actionable-email). +- Register a bot with Azure Bot Service, following the instructions in [Register a bot with Azure](/azure/bot-service/bot-service-quickstart-registration). +- Ensure that you [enabled the Outlook Channel](/azure/bot-service/bot-service-channel-connect-actionable-email). - Open your bot resource in the [Azure portal](https://ms.portal.azure.com/). - Open the **Channels** pane. - Select the **Outlook** channel in *Available Channels* section. - - Under the **Actionable Messages** tab, Click **Apply** followed by **please register here**. + - Under the **Actionable Messages** tab, select **Apply** followed by **please register here**. - Fill out the registration form to request access. See [Register your service with the actionable email developer dashboard](./email-dev-dashboard.md) for more information. -- Create your bot with the Bot Framework SDK, following the instruction [here](/azure/bot-service/bot-service-quickstart-create-bot). +- Create your bot with the Bot Framework SDK, following the instructions in [Create a bot with the Bot Framework SDK](/azure/bot-service/bot-service-quickstart-create-bot). ## Step 1: Ensure your adaptive card payloads are ready -For the Project management scenario, you can find the [JSON payload here](https://github.com/OfficeDev/outlook-dev-docs/blob/main/files/actionable-messages/samples/ProjectManagement.json). Below, You can see the payload rendering in mobile and desktop screens. +For the Project management scenario, you can find the [JSON payload here](https://github.com/OfficeDev/outlook-dev-docs/blob/main/files/actionable-messages/samples/ProjectManagement.json). In the following section, you can see the payload rendering in mobile and desktop screens. ### [Mobile](#tab/mobile) @@ -78,7 +80,7 @@ protected override async Task OnAdaptiveCardInvokeAs else if (invokeValue.Action.Verb == "projectSubmitComment") { // This function can contain your business logic - // to submit the comment and show the refresh car + // to submit the comment and show the refresh card return await ProcessProjectSubmitComment(); } else diff --git a/docs/actionable-messages/auto-invoke.md b/docs/actionable-messages/auto-invoke.md index 1f5749b0..553ece46 100644 --- a/docs/actionable-messages/auto-invoke.md +++ b/docs/actionable-messages/auto-invoke.md @@ -19,7 +19,7 @@ Actionable messages allow users to take quick actions on an email message, often ## Registration requirements -Actionable Messages services registered in the [developer dashboard](email-dev-dashboard.md) with the **Test Users** or **Organization** scope can use this feature as soon as they are approved. If your service is registered with the **Global** scope, you must contact [onboardoam@microsoft.com](mailto:onboardoam@microsoft.com) to enable this feature. +Actionable Messages services registered in the [developer dashboard](https://aka.ms/ActionableMessagesPortal) with the **Test Users** or **Organization** scope can use this feature as soon as they are approved. If your service is registered with the **Global** scope, you must contact [onboardoam@microsoft.com](mailto:onboardoam@microsoft.com) to enable this feature. ## Using autoInvokeAction diff --git a/docs/actionable-messages/email-dev-dashboard.md b/docs/actionable-messages/email-dev-dashboard.md index b1a752d1..1e8bbcf0 100644 --- a/docs/actionable-messages/email-dev-dashboard.md +++ b/docs/actionable-messages/email-dev-dashboard.md @@ -4,43 +4,45 @@ description: The developer dashboard helps you submit and track status of your s author: jasonjoh ms.topic: article ms.service: outlook -ms.date: 05/27/2026 -ms.author: jasonjoh +ms.date: 06/10/2026 +ms.author: vermaanimesh ms.localizationpriority: high ms.subservice: o365-connectors --- + + # Register your service with the actionable email developer dashboard [!INCLUDE [legacy-token-deprecation](../includes/actionable-messages/legacy-token-deprecation.md)] -To test and publish actionable messages from your service, you need to provide certain information to Microsoft to enable this functionality for emails from your service. The [developer dashboard](https://aka.ms/publishoam) helps you submit and track status of your submission via the web portal. +To test and publish actionable messages from your service, provide certain information to Microsoft to enable this functionality for emails from your service. The [developer dashboard](https://aka.ms/ActionableMessagesPortal) helps you submit and track the status of your submission through the web portal. > [!NOTE] -> You can easily try out actionable messages via email by sending email to yourself with the required markup without any intervention from Microsoft. This would typically be the first step you try out as you dip your toes into this capability. +> You can easily try out actionable messages via email by sending an email to yourself with the required markup without any intervention from Microsoft. This step is typically the first step you try as you dip your toes into this capability. > Check out [these samples](send-via-email.md#sending-the-message) to send an actionable message to your mailbox, or use the [Actionable Message Designer](https://amdesigner.azurewebsites.net/) to send an actionable message to yourself. -If you are a developer working with actionable messages via email, you will use the portal for the following cases: +If you're a developer working with actionable messages via email, use the portal for the following cases: -- To test actionable messages from your service to your own mail box -- To publish actionable message from your service so any email user within your organization using Office 365 can receive these specially formatted message (this is typically used for enabling actionable messages from a service that is specific to your organization, like a line-of-business app) -- To publish actionable messages from your service so any email user in Office 365 using your service can receive these specially formatted messages +- To test actionable messages from your service to your own mailbox +- To publish actionable messages from your service so any email user within your organization using Microsoft 365 can receive these specially formatted messages. This option typically enables actionable messages from a service that is specific to your organization, like a line-of-business app. +- To publish actionable messages from your service so any email user in Microsoft 365 using your service can receive these specially formatted messages -For all the above cases, you will be submitting certain details to Microsoft, which after being reviewed and approved, will enable actionable messages for your service. +For all these cases, submit details to Microsoft. After review and approval, Microsoft enables actionable messages for your service. ## Dashboard sections -The developer dashboard is divided into a few logical sections you need to fill out based on the scope you'd like to request Microsoft to enable actionable message from your service. +The developer dashboard is divided into a few logical sections you need to fill out based on the scope you'd like to request Microsoft to enable actionable messages from your service. ### Details of your provider -In this section, you need to supply key details that will allow Office 365 to accept emails with markup from your service as well as URLs that can be invoked via the action buttons from those emails. +In this section, provide key details that allow Microsoft 365 to accept emails with markup from your service, as well as URLs that the action buttons in those emails can invoke. The key fields are: -- **Sender email address**: This is one or more static email addresses corresponding to the service that will send out emails with action markup. Example: `myservice@contoso.com`. -- **Target URLs**: This is one or more domains corresponding to URLs that will process the actions. Your target URL can correspond to the top level domain or the sub-domain of the TLD. They need to be https enabled URLs. Example. `https://api.myservice.com`. -- **Public Key**: If you plan to send actionable messages as Signed Card, then you need to specify the public key corresponding to the private key you will use for signing the card. The format for this field is an [RSAKeyValue element](https://www.w3.org/TR/xmldsig-core/#sec-RSAKeyValue). +- **Sender email address**: Enter one or more static email addresses that correspond to the service that sends emails with action markup. For example, `myservice@contoso.com`. +- **Target URLs**: Enter one or more domains that correspond to URLs that process the actions. Your target URL can correspond to the top-level domain or the subdomain of the TLD. They need to be HTTPS-enabled URLs. For example, `https://api.myservice.com`. +- **Public Key**: If you plan to send actionable messages as Signed Card, specify the public key that corresponds to the private key you use for signing the card. The format for this field is an [RSAKeyValue element](https://www.w3.org/TR/xmldsig-core/#sec-RSAKeyValue). ```xml @@ -49,7 +51,7 @@ The key fields are: ``` -A RSA key pair can be generated and exported in the correct format using PowerShell (7.3 or later): +You can generate and export an RSA key pair in the correct format by using PowerShell (7.3 or later). ``` powershell # Generate a key pair: @@ -62,10 +64,10 @@ $rsa.ToXmlString($true) $rsa.ToXmlString($false) ``` -For an example of how to get public key XML from a .cert file, see [PublicKey class](/dotnet/api/system.security.cryptography.x509certificates.publickey#examples). +For an example of how to get public key XML from a .cert file, see [PublicKey class](/dotnet/api/system.security.cryptography.x509certificates.publickey#examples). > [!NOTE] -> Once your submission is approved, it may take some time to take effect. If you encounter the error below when sending signed cards, and you're sure that your payload is correct, please try again after a few hours. +> After your submission is approved, it might take some time for the changes to take effect. If you encounter the following error when sending signed cards, and you're sure that your payload is correct, try again after a few hours. > > ```text > Adaptive card signature validation failed - Failed to validate signature @@ -73,35 +75,33 @@ For an example of how to get public key XML from a .cert file, see [PublicKey c ### Scope of your submission -In this section, you need to specify at what scope you want to enable actionable message for your service. The applicable scopes are: +Specify the scope where you want to enable actionable message for your service. The applicable scopes are: -- **Test Users**: This enables actionable emails from your service to some of the O365 email users in your organization. This scope is generally used for testing actionable messages integration with few test users that you have specified. -- **Organization**: This enables actionable message from your service to any Microsoft 365 email user within your organization. This scope is typically used for enabling actionable messages from a service that is specific to your organization, like a line- of-business application internal to your organization. -- **Global**: This enables actionable message from your service for any email user in Office 365. +- **Test Users**: This scope enables actionable emails from your service to some of the Microsoft 365 email users in your organization. Use this scope to test actionable messages integration with a few test users that you specify. +- **Organization**: This scope enables actionable message from your service to any Microsoft 365 email user within your organization. Use this scope to enable actionable messages from a service that is specific to your organization, like a line-of-business application. +- **Global**: This scope enables actionable message from your service for any email user in Microsoft 365. -Each of the above are independent steps. i.e. you can pick only one scope for each submission and will be subject to the approval process by Microsoft. +Each scope is independent. You can submit only one scope per request and must obtain Microsoft approval. > [!NOTE] -> Remember, you can easily try out actionable messages by sending an email to yourself with the required markup without any intervention from Microsoft. You can use the [Actionable Message Designer](https://amdesigner.azurewebsites.net/) to send to yourself without writing any code. This would typically be the first step to try out actionable messages. +> You can easily try out actionable messages by sending an email to yourself with the required markup without any intervention from Microsoft. Use the [Actionable Message Designer](https://amdesigner.azurewebsites.net/) to send to yourself without writing any code. This step typically is the first step to try out actionable messages. #### Self-service registration -Self-service of registrations is available for registrations that use the following scopes. - -- **Test Users**: The registration request is auto-approved for your test users you specify. This will enable actionable emails from your service sent to test users. -- **Organization**: This registration request will be sent to your organization's administrators with **Exchange administrator** permissions. Any administrator with those permissions receive an email with submission details and will be able to review and approve your request. If no users have the **Exchange administrator** role assigned, users with the **Global administrator** role will receive this email instead. +Self-service registration is available for the following scopes. -Once the submission is approved, whether auto-approved or by your administrator, it will take up to 24 hours for the registration to take effect. +- **Test Users**: The registration request auto-approves for your test users you specify. This registration enables actionable emails from your service sent to test users. +- **Organization**: This registration request routes to your organization's [Exchange or Global administrator](/microsoft-365/admin/add-users/about-admin-roles) for review and approval. -For **My organization** registrations, the administrator accounts will receive an email and the submitter will also be copied on those emails. This will allow you to reach out to your administrator if you need to provide further clarifications or details. Once the request is approved, the submitter and the administrators will be notified with another email. +Once the submission is approved, whether auto-approved or by your administrator, it can take up to 24 hours for the registration to take effect. -After 24 hours have passed, you can verify if the registration has taken into effect by sending an actionable message from your service to your mailbox or specified test users (for **Test Users** scope), or any user mailbox in your organization (for **Organization** scope). If 24 hours have passed and the registration is still not in effect, please contact us by using the feedback link at the top the registration dashboard labeled **Registration not working?**. +After 24 hours, verify the registration is active by sending an actionable message from your service to your mailbox or specified test users (for **Test Users** scope), or any user in your organization (for **Organization** scope). If 24 hours have passed and the registration is still not active, contact us by using the feedback link at the top of the registration dashboard labeled **Registration not working?**. ### Test user email addresses This section is only applicable when your scope of submission to enable actionable messages is **Test Users**. -In this section provide a list of Microsoft 365 email users in your organization, separated by a semi-colon (`;`). This will help you to test your actionable messages integration on a few users, before creating an **Organization** or **Global** scope submission. +Provide a list of Microsoft 365 email users in your organization, separated by a semicolon (`;`). This list helps you test your actionable messages integration with a few users before creating an **Organization** or **Global** scope submission. ### Contact info @@ -119,7 +119,7 @@ In this section, you need to provide details about your service that will be sen This section is only applicable when your scope of submission to enable actionable messages is **Global**. -In this section, you need to provide details on the scenario for which users will consume actionable messages from your service and other relevant details. This is to help Microsoft determine that validity and usefulness of the solution provided by your service. +In this section, you need to provide details about the scenario in which users will use actionable messages from your service. This helps Microsoft determine the validity and usefulness of your solution. ### Verification details @@ -127,36 +127,36 @@ This section is only applicable when your scope of submission to enable actionab In this section, you need to provide details for Microsoft to verify the actionable message and the corresponding actions that are invoked from the email sent by your provider/service. -Additionally, send a valid email coming from your production servers (or a server with similar DKIM/SPF/From:/Return-Path: headers) including the markup to onboardoam@microsoft.com. This procedure will enable Microsoft to determine that the solution complies with all the guidelines and requirements listed in Registration Criteria. +Additionally, send a valid email coming from your production servers (or a server with similar DKIM/SPF/From:/Return-Path: headers) including the markup to [onboardoam@microsoft.com](mailto:onboardoam@microsoft.com). This procedure will enable Microsoft to determine that the solution complies with all the guidelines and requirements listed in Registration Criteria. - Make sure that the markup is correct prior to sending the email. -- Office 365 removes all markup when forwarding an email. Do not forward the email but send it directly. +- Microsoft 365 removes all markup when forwarding an email. Do not forward the email but send it directly. ## Registration criteria -There are some things you need to keep in mind when you submit your solution for approval for **Global** scope since it can have broad impact to users in Office 365. +Keep these criteria in mind when you submit your solution for approval for **Global** scope, since it can have a broad impact on users in Microsoft 365. ### Email sender quality guidelines -- Emails must be authenticated via DKIM or SPF. -- The top-level domain (TLD) of the SPF check or DKIM signature must match the TLD of your `From:` email address. For example, if you use `From: myservice@contoso.com` the DKIM or SPF must be for `contoso.com` or `-.contoso.com`. -- Emails must come from a static email address, e.g. `myservice@contoso.com`. -- Emails must follow the email sender guidelines. - - See [Sending mail to Office 365](/office365/SecurityCompliance/sending-mail-to-office-365) for Office 365. - - See [Policies, Practices, and Guidelines](https://sendersupport.olc.protection.outlook.com/pm/policies.aspx) for Outlook.com. - - See [M3AAWG Sender Best Practices](https://www.m3aawg.org/sites/default/files/doc_files/M3AAWG_Senders_BCP_Ver3-2015-02.pdf) and [ReturnPath Sending Best Practices](https://help.returnpath.com/hc/articles/221634867-Sending-Best-Practices-PDF-) for industry guidelines. -- Consistent history of sending a high volume of mail from your domain (order of hundred emails a day minimum to Office 365) for a few weeks at least. -- A very low rate of spam complaints from users. -- High-fidelity, routine and simple actions available for your service should be used. For more complex interactions, `OpenURI` actions can be used. -- Actions should be used for transactional mail where a high interaction rate is expected. They should not be used on promotional bulk mail. +- Authenticate emails through DKIM or SPF. +- The top-level domain (TLD) of the SPF check or DKIM signature must match the TLD of your `From:` email address. For example, if you use `From: myservice@contoso.com`, the DKIM or SPF must be for `contoso.com` or `-.contoso.com`. +- Send emails from a static email address, such as `myservice@contoso.com`. +- Follow the email sender guidelines. + - For Microsoft 365, see [Microsoft 365 services for external email senders](/defender-office-365/external-senders-microsoft-365-services). + - For Outlook.com, see [Policies, Practices, and Guidelines](https://sendersupport.olc.protection.outlook.com/pm/policies.aspx). + - For industry guidelines, see [M3AAWG Sender Best Practices](https://www.m3aawg.org/sites/default/files/doc_files/M3AAWG_Senders_BCP_Ver3-2015-02.pdf) and [ReturnPath Sending Best Practices](https://help.returnpath.com/hc/articles/221634867-Sending-Best-Practices-PDF-). +- Maintain a consistent history of sending a high volume of mail from your domain (an order of hundred emails a day minimum to Microsoft 365) for at least a few weeks. +- Maintain a very low rate of spam complaints from users. +- Use high-fidelity, routine, and simple actions for your service. For more complex interactions, use `Action.OpenUrl` actions. +- Use actions for transactional mail where a high interaction rate is expected. Don't use them on promotional bulk mail. ### Actions guidelines -- Label of the button needs to reflect clear action to be taken. -- `Action.OpenUrl` action must deep link into the specific page associated with the entity/information presented in the actionable message. -- Low failure rate and fast response for services handling action requests. -- Please see [Designing Outlook actionable message cards with the Adaptive Card format](adaptive-card.md) for additional guidelines on designing actionable messages. +- The label of the button needs to clearly reflect the action to take. +- `Action.OpenUrl` action must deep link into the specific page associated with the entity or information presented in the actionable message. +- Maintain a low failure rate and fast response for services handling action requests. +- For additional guidelines on designing actionable messages, see [Designing Outlook actionable message cards with the Adaptive Card format](adaptive-card.md). ## Approval of your submission -We will notify you on the email address you provided during your submission, so please ensure you provide the right contact information. +You'll receive a notification at the email address you provide during your submission, so make sure you provide the right contact information. diff --git a/docs/actionable-messages/enable-entra-token-for-actionable-messages.md b/docs/actionable-messages/enable-entra-token-for-actionable-messages.md index f278fddf..feb70cd5 100644 --- a/docs/actionable-messages/enable-entra-token-for-actionable-messages.md +++ b/docs/actionable-messages/enable-entra-token-for-actionable-messages.md @@ -5,7 +5,7 @@ author: vermaanimesh ms.topic: how-to ms.service: outlook ms.subservice: o365-connectors -ms.date: 05/27/2026 +ms.date: 06/10/2026 ms.author: vermaanimesh ms.localizationpriority: high --- @@ -16,29 +16,22 @@ ms.localizationpriority: high [!INCLUDE [legacy-token-deprecation](../includes/actionable-messages/legacy-token-deprecation.md)] -## Admin Guide: View providers with Auth type +## Admin guide: View providers with Auth type Admins can download the list of all approved providers in their organization along with the token type being used. The data is exported in a .csv format for easy analysis and reporting. ### How to download the provider list -1. Navigate to the Actionable Email Developer Dashboard (Admin Portal). -1. Use the **Status** filter and select **Approved**. -1. Select **Search** to load the approved providers. +1. Go to the [Actionable Email Developer Dashboard](https://aka.ms/ActionableMessagesPortal). +1. In the upper-right corner, select the **Export Approved Providers** button to export the list of approved providers in .csv format. - :::image type="content" source="images/enabling-entra-token-for-actionable-messages/get-provider-search.png" alt-text="A screenshot of the Actionable Email Developer Dashboard showing the position of the Search button"::: +:::image type="content" source="images/enabling-entra-token-for-actionable-messages/get-provider.png" alt-text="A screenshot of the Actionable Email Developer Dashboard showing the position of the Get Provider List button"::: -1. Once the approved providers are displayed, the **Get Provider List** button will become visible. +#### Important notes - :::image type="content" source="images/enabling-entra-token-for-actionable-messages/get-provider.png" alt-text="A screenshot of the Actionable Email Developer Dashboard showing the position of the Get Provider List button"::: - -1. Select **Get Provider List** to export the list in .csv format. - -#### Important Notes - -- The download button is visible only after filtering by Approved providers. +- You see the download button only after filtering by approved providers. - The downloaded file contains provider details along with their token type. -- In case of a timeout error, the error message is displayed on the UI and disappears automatically after 5 seconds. +- If a timeout error occurs, the error message is displayed in the UI and disappears automatically after 5 seconds. ## Register an app in Azure @@ -46,7 +39,7 @@ Admins can download the list of all approved providers in their organization alo > If you already have an app registration in Azure, skip to the next step. 1. Sign in to the Microsoft Entra admin center. -1. If you have access to multiple tenants, use the Settings icon to switch to the desired tenant via **Directories + subscriptions**. +1. If you have access to multiple tenants, use the **Settings** icon to switch to the desired tenant via **Directories + subscriptions**. 1. Go to **Identity** > **Applications** > **App registrations** and select **New registration**. 1. Enter a display name for your application. 1. Specify who can use the application in the **Supported account types** section: @@ -67,32 +60,30 @@ Admins can download the list of all approved providers in their organization alo - Approval and onboarding of the AM registration remain unchanged. > [!TIP] -> Use this new registration to test the AAD token scenario end-to-end. Gradually move traffic to the new registration once validated. +> Use this new registration to test the Microsoft Entra ID token scenario end-to-end. Gradually move traffic to the new registration once validated. -## Expose an API and pre-authorize the Actions app +## Expose an API and preauthorize the Actions app -1. Select the **Expose an API** option from left navigation pane of the registered app -1. Add URI under the **Application ID URI** option. Use the **AppIdUri** generated in the provider registration. Example format: +1. Select **Expose an API** from the left navigation pane of the registered app. +1. Add a URI under **Application ID URI**. Use the **AppIdUri** generated in the provider registration. Example format: `api://auth-am-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` - :::image type="content" source="images/enabling-entra-token-for-actionable-messages/expose-an-api.jpg" alt-text="A screenshot of the 'Expose an API' form in the Entra admin portal"::: - -1. Add the scope for this app under **Add a scope section** (e.g., Global.Test). +1. Add the scope for this app under **Add a scope section** (for example, Global.Test). 1. Choose a value for **Who can consent?**. - **Admins and users:** Consent from either works. - **Admins only (Recommended):** Only admin approval works. - Once the Admin has authorized, consent is for the whole tenant and won't be prompted again. + Once an admin authorizes, consent applies to the whole tenant and users aren't prompted again. -1. Go to **Add a client application** and authorize Action app ID `48af08dc-f6d2-435f-b2a7-069abd99c086` to the scopes created above. +1. Go to **Add a client application** and authorize Action app ID `48af08dc-f6d2-435f-b2a7-069abd99c086` to the scopes you created. -## Validate the AAD token +## Validate the Microsoft Entra ID token -Upon receiving the token in the request from Actions service, partners should perform validation. For details on validating tokens, see [Access tokens in the Microsoft identity platform](/entra/identity-platform/access-tokens). +When your service receives the token in the request from the Actions service, validate it. For details on validating tokens, see [Access tokens in the Microsoft identity platform](/entra/identity-platform/access-tokens). -There are also [code samples for Microsoft identity platform authentication and authorization](/entra/identity-platform/sample-v2-code?tabs=framework) for validation in your preferred language/framework. +There are also [code samples for Microsoft identity platform authentication and authorization](/entra/identity-platform/sample-v2-code?tabs=framework) for validation in your preferred language or framework. ### Sample token @@ -128,29 +119,28 @@ There are also [code samples for Microsoft identity platform authentication and ## Get approval from admins -For a Global scope actionable message registration to work in any tenant, the tenant admin must consent to the app hosting the target URL. Admins can grant consent using the [Actionable Email Developer Dashboard](https://outlook.office.com/connectors/oam/admin) page. +For a Global scope actionable message registration to work in any tenant, the tenant admin must consent to the app hosting the target URL. Admins can grant consent by using the [Actionable Email Developer Dashboard](https://aka.ms/ActionableMessagesPortal). -1. Go to the Actionable Email Developer Dashboard and select the **Consent 3P Apps** button (top right). +1. Go to the Actionable Email Developer Dashboard and select the **AAD Consent** button (left side panel). - :::image type="content" source="images/enabling-entra-token-for-actionable-messages/consent-third-party-apps.png" alt-text="A screenshot of the Actionable Email Developer Dashboard showing the 'Consent 3P Apps' button"::: + :::image type="content" source="images/enabling-entra-token-for-actionable-messages/aad-consent.png" alt-text="A screenshot of the Actionable Email Developer Dashboard showing the Consent 3P Apps button"::: -1. The Admin Consent Dashboard will open, listing all 3P providers. Apps that need consent show an **Approve** button. +1. The Admin Consent Dashboard opens, listing all third-party providers. Apps that need consent show a **Grant Consent** button. :::image type="content" source="images/enabling-entra-token-for-actionable-messages/actionable-message-dashboard.png" alt-text="AM Email Dashboard"::: -1. Select a provider row to review details. -1. Select **Approve** to trigger the consent flow. Sign in and review the requested permissions. +1. Select **Grant Consent** to start the consent flow. Sign in and review the requested permissions. 1. Ensure **Consent on behalf of your organization** is selected for tenant-wide consent. -1. Select **Accept** to grant consent. The Microsoft Entra app is now authorized in your tenant. The browser redirects back to the dashboard where the app status is **Approved**. +1. Select **Accept** to grant consent. The Microsoft Entra app is now authorized in your tenant. The browser redirects back to the dashboard where the app status is **Consented**. :::image type="content" source="images/enabling-entra-token-for-actionable-messages/permission.png" alt-text="User permission screen"::: -1. If status remains **Approving**, use the **Refresh** button to update. +1. If status remains **Consenting**, use the **Refresh Consent Status** button to update. 1. Use the search bar to find a provider by **Name, Provider ID,** or **Microsoft Entra ID**. :::image type="content" source="images/enabling-entra-token-for-actionable-messages/search-bar.png" alt-text="Search bar in AM portal"::: -1. To remove consent, open Azure Portal and select **Enterprise Applications**. Search for the app's service principal, and delete it in **Properties**. +1. To remove consent, open the Azure portal and select **Enterprise Applications**. Search for the app's service principal and delete it in **Properties**. :::image type="content" source="images/enabling-entra-token-for-actionable-messages/service-principal-azure-portal.png" alt-text="Azure portal screen"::: diff --git a/docs/actionable-messages/get-started.md b/docs/actionable-messages/get-started.md index 5127868f..d04e08b1 100644 --- a/docs/actionable-messages/get-started.md +++ b/docs/actionable-messages/get-started.md @@ -4,35 +4,40 @@ description: Learn how to create an actionable message card and send it via Outl author: jasonjoh ms.topic: article ms.service: outlook -ms.date: 05/27/2026 -ms.author: jasonjoh +ms.date: 06/10/2026 +ms.author: vermaanimesh ms.localizationpriority: high ms.subservice: o365-connectors --- + + # Get started with actionable messages in Office 365 [!INCLUDE [legacy-token-deprecation](../includes/actionable-messages/legacy-token-deprecation.md)] +> [!IMPORTANT] +> The Actionable Messages provider portal moved to a new location. [Visit the new portal](https://aka.ms/ActionableMessagesPortal). + ## Supported scenarios -Sending actionable messages via email is supported in the following 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. Do not put the recipient in the BCC field. +- 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 via the [Set-OrganizationConfig cmdlet](/powershell/module/exchange/organization/set-organizationconfig). If actionable messages do not render, check with your administrator to make sure the feature is enabled in your organization. +> Office 365 administrators can disable actionable messages by using the [Set-OrganizationConfig cmdlet](/powershell/module/exchange/organization/set-organizationconfig). 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 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](https://amdesigner.azurewebsites.net/) to design the 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](https://amdesigner.azurewebsites.net/) 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](email-dev-dashboard.md). Leaving this property empty when sending to others results in the card being removed. +> 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](https://aka.ms/ActionableMessagesPortal). If you leave this property empty when sending to others, the card is removed. -Go to the Actionable Message Designer and paste in the following JSON: +Go to the Actionable Message Designer and paste the following JSON: ```json { @@ -71,19 +76,19 @@ Go to the Actionable Message Designer and paste in the following JSON: } ``` -Feel free to experiment with this simple example in the Designer. You can see the [adaptive card reference](adaptive-card.md) for details on the available fields. Once you have a card you're happy with, you can move on to sending it. +Feel free to experiment with this simple example in the Designer. For details on the available fields, see the [adaptive card reference](adaptive-card.md). When you have a card you're happy with, you can move on to sending it. -## Sending actionable messages via email +## Sending actionable messages through email > [!IMPORTANT] -> You can design and test actionable messages by using the [Actionable Message Designer](https://amdesigner.azurewebsites.net/), which allows you to send actionable messages to yourself. You can also send actionable messages to yourself using the [Office 365 SMTP server](https://support.office.com/article/pop-and-imap-email-settings-for-outlook-8361e398-8af4-4e97-b147-6c6c4ac95353). You will be unable to send actionable messages to any other user until you have registered using the [actionable messages developer dashboard](https://aka.ms/publishoam). +> To design and test actionable messages, use the [Actionable Message Designer](https://amdesigner.azurewebsites.net/). It sends actionable messages to you. You can also use the [Office 365 SMTP server](https://support.office.com/article/pop-and-imap-email-settings-for-outlook-8361e398-8af4-4e97-b147-6c6c4ac95353) to send actionable messages to yourself. You can't send actionable messages to other users until you register through the [actionable messages developer dashboard](https://aka.ms/ActionableMessagesPortal). -To embed an actionable message card in an email message, we need to wrap the card in a `