Office.NotificationMessages interface

The NotificationMessages object is returned as the notificationMessages property of an item.

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Methods

addAsync(key, JSONmessage, options, callback)

Adds a notification to an item.

There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error.

Important:

  • Only one notification of type InsightMessage is allowed per add-in. (The InsightMessage type is currently in preview.) Attempting to add more will throw an error.

  • In modern Outlook on the web, you can add an InsightMessage notification only in Compose mode.

addAsync(key, JSONmessage, callback)

Adds a notification to an item.

There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error.

Important:

  • Only one notification of type InsightMessage is allowed per add-in. (The InsightMessage type is currently in preview.) Attempting to add more will throw an error.

  • In modern Outlook on the web, you can add an InsightMessage notification only in Compose mode.

getAllAsync(options, callback)

Returns all keys and messages for an item.

getAllAsync(callback)

Returns all keys and messages for an item.

removeAsync(key, options, callback)

Removes a notification message for an item.

removeAsync(key, callback)

Removes a notification message for an item.

replaceAsync(key, JSONmessage, options, callback)

Replaces a notification message that has a given key with another message.

If a notification message with the specified key doesn't exist, replaceAsync will add the notification.

replaceAsync(key, JSONmessage, callback)

Replaces a notification message that has a given key with another message.

If a notification message with the specified key doesn't exist, replaceAsync will add the notification.

Method Details

addAsync(key, JSONmessage, options, callback)

Adds a notification to an item.

There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error.

Important:

  • Only one notification of type InsightMessage is allowed per add-in. (The InsightMessage type is currently in preview.) Attempting to add more will throw an error.

  • In modern Outlook on the web, you can add an InsightMessage notification only in Compose mode.

addAsync(key: string, JSONmessage: NotificationMessageDetails, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

key

string

A developer-specified key used to reference this notification message. Developers can use it to modify this message later. It can't be longer than 32 characters.

JSONmessage
Office.NotificationMessageDetails

A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object.

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties. asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
const details =
  {
    type: "progressIndicator",
    message: "Progress indicator with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
const details =
  {
    type: "informationalMessage",
    message: "Non-persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: false
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
const details =
  {
    type: "informationalMessage",
    message: "Persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: true
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
const details =
  {
    type: "errorMessage",
    message: "Error notification message with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

addAsync(key, JSONmessage, callback)

Adds a notification to an item.

There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error.

Important:

  • Only one notification of type InsightMessage is allowed per add-in. (The InsightMessage type is currently in preview.) Attempting to add more will throw an error.

  • In modern Outlook on the web, you can add an InsightMessage notification only in Compose mode.

addAsync(key: string, JSONmessage: NotificationMessageDetails, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

key

string

A developer-specified key used to reference this notification message. Developers can use it to modify this message later. It can't be longer than 32 characters.

JSONmessage
Office.NotificationMessageDetails

A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

getAllAsync(options, callback)

Returns all keys and messages for an item.

getAllAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<NotificationMessageDetails[]>) => void): void;

Parameters

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties. asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<Office.NotificationMessageDetails[]>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The value property of the result is an array of NotificationMessageDetails objects.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Get all notifications.
Office.context.mailbox.item.notificationMessages.getAllAsync(function (asyncResult) {
    if (asyncResult.status != "failed") {
        Office.context.mailbox.item.notificationMessages.replaceAsync( "notifications", {
            type: "informationalMessage",
            message : "Found " + asyncResult.value.length + " notifications.",
            icon : "iconid",
            persistent: false
        });
    }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
Office.context.mailbox.item.notificationMessages.getAllAsync(handleResult);          

getAllAsync(callback)

Returns all keys and messages for an item.

getAllAsync(callback?: (asyncResult: Office.AsyncResult<NotificationMessageDetails[]>) => void): void;

Parameters

callback

(asyncResult: Office.AsyncResult<Office.NotificationMessageDetails[]>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The value property of the result is an array of NotificationMessageDetails objects.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

removeAsync(key, options, callback)

Removes a notification message for an item.

removeAsync(key: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

key

string

The key for the notification message to remove.

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties. asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);

removeAsync(key, callback)

Removes a notification message for an item.

removeAsync(key: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

key

string

The key for the notification message to remove.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

replaceAsync(key, JSONmessage, options, callback)

Replaces a notification message that has a given key with another message.

If a notification message with the specified key doesn't exist, replaceAsync will add the notification.

replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

key

string

The key for the notification message to replace. It can't be longer than 32 characters.

JSONmessage
Office.NotificationMessageDetails

A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object.

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties. asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Replace a notification with an informational notification.
Office.context.mailbox.item.notificationMessages.replaceAsync("progress", {
    type: "informationalMessage",
    message : "The message was processed successfully.",
    icon : "iconid",
    persistent: false
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
Office.context.mailbox.item.notificationMessages.replaceAsync(
  id,
  {
    type: "informationalMessage",
    message: "Notification message with id = " + id + " has been replaced with an informational message.",
    icon: "icon2",
    persistent: false
  },
  handleResult);

replaceAsync(key, JSONmessage, callback)

Replaces a notification message that has a given key with another message.

If a notification message with the specified key doesn't exist, replaceAsync will add the notification.

replaceAsync(key: string, JSONmessage: NotificationMessageDetails, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

key

string

The key for the notification message to replace. It can't be longer than 32 characters.

JSONmessage
Office.NotificationMessageDetails

A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read