Create notifications for your Outlook add-in

Implement notification messages for your Outlook add-in to keep your users informed about important events, feedback, or errors with minimal disruption to their workflow.

Supported Outlook surfaces and modes

Notification messages are supported on messages and appointments in both read and compose modes. They're displayed above the body of the mail item.

To manage a notification on a mail item, call Office.context.mailbox.item.notificationMessages in your add-in's JavaScript code. This property returns a NotificationMessages object with methods to add, remove, get, or replace notifications. The following code shows how to use these methods to manage your add-in's notifications.

const notificationMessages = Office.context.mailbox.item.notificationMessages;

// Sample informational message.
const notificationDetails = {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "This is a sample notification message.",
    icon: "icon-16",
    persistent: false
};

const notificationKey = "notification_01";

// Add a notification to the mail item.
notificationMessages.addAsync(notificationKey, notificationDetails, (result) => {
    console.log("Added an informational notification.");
});

// Get all the notifications of the mail item.
notificationMessages.getAllAsync((result) => {
    console.log(JSON.stringify(result.value));
});

// Replace a notification.
const newNotification = {
    type: Office.MailboxEnums.ItemNotificationMessageType.ErrorMessage,
    message: "This is a sample error message."
};

notificationMessages.replaceAsync(notificationKey, newNotification, (result) => {
    console.log("Replaced the existing notification.");
});

// Remove a notification.
notificationMessages.removeAsync(notificationKey, (result) => {
    console.log("Removed the notification.");
});

Types of notifications

A notification consists of a unique identifier, an icon, and a message. Depending on the type, it could also include a Dismiss action or a custom action. There are different types of notifications you can display to the user to fit your particular scenario.

• ErrorMessage
• InformationalMessage
• InsightMessage
• ProgressIndicator

The following sections describe each notification type, including its properties and supported platforms.

ErrorMessage

InformationalMessage

InsightMessage

ProgressIndicator

Feature behaviors

When creating and managing notifications for your add-in, be mindful of the following behaviors, limitations, and best practices.

Maximum number of notifications per mail item

In Outlook on the web, on Windows (new and classic), and on Mac, you can add a maximum of five notifications per message. In Outlook on mobile devices, only one notification can be added to a message. Setting an additional notification replaces the existing one.

InsightMessage limitations

Only one InsightMessage notification is allowed per add-in on a mail item. In Outlook on the web and new Outlook on Windows, the InsightMessage type is only supported in compose mode.

Notification icons and unified manifest for Microsoft 365

If your add-in uses the unified manifest for Microsoft 365, you can't customize the icon of an InformationalMessage or InsightMessage notification. The notification uses the first image specified in the "icons" array of the first extensions.ribbons.tabs.groups.controls object of the manifest. Although this is the case, you must still specify a string in the icon property of your NotificationMessageDetails object (for example, "icon-16").

Notification icons in Outlook on mobile devices

In compose mode, while the style of each notification type varies on other Outlook clients, notifications in Outlook on Android and on iOS all use the same style. The notification message always uses an information icon.

Notifications for multiple selected messages

When managing notifications for multiple selected messages, only the getAllAsync method is supported. To learn more, see Activate your Outlook add-in on multiple messages.

Best practices for ProgressIndicator notifications

When implementing a ProgressIndicator notification in your add-in, once the applicable operation or action completes, replace the progress notification with another notification type. This is a best practice to ensure that your users always get the latest status of an operation.

Try the code example in Script Lab

Learn how you can use notifications in your add-in by trying out the Work with notification messages sample in Script Lab for Outlook. For more information on Script Lab, see Explore Office JavaScript API using Script Lab.

See also

• Use the Office dialog API in Office Add-ins
• Configure your Outlook add-in for event-based activation