Office.NotificationMessages interface

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

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

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.

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.

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.

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: read item

Applicable Outlook mode: Compose or Read

Important:

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

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

  • Only the InformationalMessage type is supported in Outlook on Android and on iOS.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml

// Adds a progress indicator to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
    message: "Progress indicator with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds an informational notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Non-persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: false
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds a persistent information notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: true
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds an error notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.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.

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: read item

Applicable Outlook mode: Compose or Read

Important:

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

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

  • Only the InformationalMessage type is supported in Outlook on Android and on iOS.

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: read item

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

// Gets all the notification messages and their keys for the current mail item.
Office.context.mailbox.item.notificationMessages.getAllAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  console.log(asyncResult.value);
});

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: read item

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: read item

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

// Removes a notification message from the current mail item.
const id = $("#notificationId").val().toString();
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: read item

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: read item

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

// Replaces a notification message of a given key with another message.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.replaceAsync(
  id,
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.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: read item

Applicable Outlook mode: Compose or Read