Office.NotificationMessages interface

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

[ API set: Mailbox 1.3 ]

Remarks

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.

[ API set: Mailbox 1.3 ]

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.

[ API set: Mailbox 1.3 ]

getAllAsync(options, callback)

Returns all keys and messages for an item.

[ API set: Mailbox 1.3 ]

getAllAsync(callback)

Returns all keys and messages for an item.

[ API set: Mailbox 1.3 ]

removeAsync(key, options, callback)

Removes a notification message for an item.

[ API set: Mailbox 1.3 ]

removeAsync(key, callback)

Removes a notification message for an item.

[ API set: Mailbox 1.3 ]

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.

[ API set: Mailbox 1.3 ]

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.

[ API set: Mailbox 1.3 ]

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.

[ API set: Mailbox 1.3 ]

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 method.

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

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
var id = $("#notificationId").val();
var 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
var id = $("#notificationId").val();
var 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
var id = $("#notificationId").val();
var 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
var id = $("#notificationId").val();
var 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.

[ API set: Mailbox 1.3 ]

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

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

getAllAsync(options, callback)

Returns all keys and messages for an item.

[ API set: Mailbox 1.3 ]

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 method.

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

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.

[ API set: Mailbox 1.3 ]

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

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

removeAsync(key, options, callback)

Removes a notification message for an item.

[ API set: Mailbox 1.3 ]

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 method.

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

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
var id = $("#notificationId").val();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);

removeAsync(key, callback)

Removes a notification message for an item.

[ API set: Mailbox 1.3 ]

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

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.

[ API set: Mailbox 1.3 ]

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 method.

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

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
var 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.

[ API set: Mailbox 1.3 ]

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

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read