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

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

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