Office.SmartAlertsEventCompletedOptions interface

Specifies the behavior of a Smart Alerts add-in when it completes processing an OnMessageSend or OnAppointmentSend event.

Remarks

[ API set: Mailbox 1.12 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Examples

// The following example checks whether a location is specified in an appointment before it's sent.
function onAppointmentSendHandler(event) {
    Office.context.mailbox.item.location.getAsync({ asyncContext: event }, asyncResult => {
        const event = asyncResult.asyncContext;
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            // If the add-in is unable to retrieve the appointment's location, the appointment isn't sent.
            event.completed({ allowEvent: false, errorMessage: "Failed to get the appointment's location." });
            return;
        }

        if (asyncResult.value === "") {
            // If no location is specified, the appointment isn't sent and the user is alerted to include a location.
            event.completed(
                {
                    allowEvent: false,
                    cancelLabel: "Add a location",
                    commandId: "msgComposeOpenPaneButton",
                    contextData: JSON.stringify({ a: "aValue", b: "bValue" }),
                    errorMessage: "Don't forget to add a meeting location.",
                    errorMessageMarkdown: `
                        Don't forget to add a meeting location.\n\n
                        **Tip**: For a list of locations,
                        see [Meeting Locations]("https://www.contoso.com/meeting-locations).`,
                    sendModeOverride: Office.MailboxEnums.SendModeOverride.PromptUser
                }
            );
        } else {
            // If a location is specified, the appointment is sent.
            event.completed({ allowEvent: true });
        }
    });
}

Properties

allowEvent

When you use the completed method to signal completion of an event handler, this value indicates if the handled event should continue execution or be canceled. For example, an add-in that handles the OnMessageSend or OnAppointmentSend event can set allowEvent to false to cancel the sending of an item. For a complete sample, see the Smart Alerts walkthrough.

cancelLabel

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property customizes the text of the Don't Send button in the Smart Alerts dialog. Custom text must be 20 characters or less.

For an example, see the Smart Alerts walkthrough.

commandId

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies the ID of the task pane or function that runs when the Don't Send button is selected from the Smart Alerts dialog.

For an example, see the Smart Alerts walkthrough.

contextData

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies any JSON data passed to the add-in for processing when the Don't Send button is selected from the Smart Alerts dialog.

errorMessage

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message displayed to the user. For an example, see the Smart Alerts walkthrough.

errorMessageMarkdown

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message displayed to the user. The error message is formatted using Markdown. For an example, see the Smart Alerts walkthrough.

sendModeOverride

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property overrides the send mode option specified in the manifest at runtime.

For an example, see the Smart Alerts walkthrough.

Property Details

allowEvent

When you use the completed method to signal completion of an event handler, this value indicates if the handled event should continue execution or be canceled. For example, an add-in that handles the OnMessageSend or OnAppointmentSend event can set allowEvent to false to cancel the sending of an item. For a complete sample, see the Smart Alerts walkthrough.

allowEvent?: boolean;

Property Value

boolean

Remarks

[ API set: Mailbox 1.12 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

cancelLabel

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property customizes the text of the Don't Send button in the Smart Alerts dialog. Custom text must be 20 characters or less.

For an example, see the Smart Alerts walkthrough.

cancelLabel?: string;

Property Value

string

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

commandId

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies the ID of the task pane or function that runs when the Don't Send button is selected from the Smart Alerts dialog.

For an example, see the Smart Alerts walkthrough.

commandId?: string;

Property Value

string

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important:

The commandId value must match the task pane or function ID specified in the manifest of your add-in. The markup depends on the type of manifest your add-in uses.

  • Add-in only manifest: The id attribute of the Control element representing the task pane or function.

  • Unified manifest for Microsoft 365: The "id" property of the task pane or function command in the "controls" array.

If you specify the contextData option in your event.completed call, you must also assign a task pane or function ID to the commandId option. Otherwise, the JSON data assigned to contextData is ignored.

contextData

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies any JSON data passed to the add-in for processing when the Don't Send button is selected from the Smart Alerts dialog.

contextData?: any;

Property Value

any

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important:

  • In Outlook on Windows, the any type is supported starting in Version 2402 (Build 17308.20000). In earlier versions of Outlook on Windows, only the string type is supported.

  • If you specify the contextData option in your event.completed call, you must also assign a task pane ID to the commandId option. Otherwise, the JSON data assigned to contextData is ignored.

  • To retrieve the value of the contextData property, you must call Office.context.mailbox.item.getInitializationContextAsync in the JavaScript implementation of your task pane. If you create a JSON string using JSON.stringify() and assign it to the contextData property, you must parse the string using JSON.parse() once you retrieve it.

errorMessage

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message displayed to the user. For an example, see the Smart Alerts walkthrough.

errorMessage?: string;

Property Value

string

Remarks

[ API set: Mailbox 1.12 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

errorMessageMarkdown

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message displayed to the user. The error message is formatted using Markdown. For an example, see the Smart Alerts walkthrough.

errorMessageMarkdown?: string;

Property Value

string

Remarks

[ API set: Mailbox preview ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important

  • The formatted error message must be 500 characters or less.

  • For guidance on supported Markdown elements, see Limitations to formatting the dialog message using Markdown.

  • If you format the dialog message using the errorMessageMarkdown property, we recommend you also add a plaintext version of the message using the errorMessage property. This ensures that the message is displayed properly in Outlook clients that don't support Markdown.

sendModeOverride

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property overrides the send mode option specified in the manifest at runtime.

For an example, see the Smart Alerts walkthrough.

sendModeOverride?: MailboxEnums.SendModeOverride | string;

Property Value

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important: Currently, sendModeOverride can only be set to the prompt user option.