Office.NotificationMessages interface

Reference

Package:: outlook

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Methods

addAsync(key, JSONmessage, options, callback)	Adds a notification to an item.
addAsync(key, JSONmessage, callback)	Adds a notification to an item.
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.

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:

In Outlook on the web, on Windows (new and classic), and on Mac, you can set a maximum of five notifications per message. Setting more returns a NumberOfNotificationMessagesExceeded error. In Outlook on Android and on iOS, you can only set one notification per message. Setting an additional notification replaces the previous one.
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.
In Outlook on Android and on iOS, only the ProgressIndicator, InformationalMessage, and ErrorMessage notification types are supported.
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 is always prefixed with an informational icon.
The addAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

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 = (document.getElementById("notificationId") as HTMLInputElement).value;
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 = (document.getElementById("notificationId") as HTMLInputElement).value;
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Non-persistent informational notification message with id = " + id,
    icon: "PG.Icon.16",
    persistent: false
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds a persistent information notification to the mail item.
const id = (document.getElementById("notificationId") as HTMLInputElement).value;
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Persistent informational notification message with id = " + id,
    icon: "PG.Icon.16",
    persistent: true
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds an error notification to the mail item.
const id = (document.getElementById("notificationId") as HTMLInputElement).value;
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.

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:

In Outlook on the web, on Windows (new and classic), and on Mac, you can set a maximum of five notifications per message. Setting more returns a NumberOfNotificationMessagesExceeded error. In Outlook on Android and on iOS, you can only set one notification per message. Setting an additional notification replaces the previous one.
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.
In Outlook on Android and on iOS, only the ProgressIndicator, InformationalMessage, and ErrorMessage notification types are supported.
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 is always prefixed with an informational icon.
The addAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

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

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

Important: The removeAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

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 = (document.getElementById("notificationId") as HTMLInputElement).value;
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

Important: The replaceAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

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 = (document.getElementById("notificationId") as HTMLInputElement).value;
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

Share via

Office.NotificationMessages interface

Remarks

Methods

Method Details

addAsync(key, JSONmessage, options, callback)

Parameters

Returns

Remarks

Examples

addAsync(key, JSONmessage, callback)

Parameters

Returns

Remarks

getAllAsync(options, callback)

Parameters

Returns

Remarks

Examples

getAllAsync(callback)

Parameters

Returns

Remarks

removeAsync(key, options, callback)

Parameters

Returns

Remarks

Examples

removeAsync(key, callback)

Parameters

Returns

Remarks

replaceAsync(key, JSONmessage, options, callback)

Parameters

Returns

Remarks

Examples

replaceAsync(key, JSONmessage, callback)

Parameters

Returns

Remarks

Additional resources