Edit

Share via

Office.SessionData interface

Package:
outlook

Provides methods to manage an item's session data.

Session data is specific to a single mail item. It isn't shared among multiple items even if the same add-in is used to set or retrieve data.

Remarks

[ API set: Mailbox 1.11 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Important: For each mail item, the entire SessionData object is limited to 50,000 characters per add-in.

Methods

clearAsync(options, callback)

Clears all session data key-value pairs.
clearAsync(callback)

Clears all session data key-value pairs.
getAllAsync(callback)

Gets all session data key-value pairs.
getAsync(name, callback)

Gets the session data value of the specified key.
removeAsync(name, options, callback)

Removes a session data key-value pair.
removeAsync(name, callback)

Removes a session data key-value pair.
setAsync(name, value, options, callback)

Sets a session data key-value pair.
setAsync(name, value, callback)

Sets a session data key-value pair.

Method Details

clearAsync(options, callback)

Clears all session data key-value pairs.

clearAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => 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<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.11 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/session-data-apis.yaml

Office.context.mailbox.item.sessionData.clearAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("sessionData.clearAsync succeeded");
  } else {
    console.log("Failed to clear sessionData. Error: " + JSON.stringify(asyncResult.error));
  }
});

clearAsync(callback)

Clears all session data key-value pairs.

clearAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

callback

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.11 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

getAllAsync(callback)

Gets all session data key-value pairs.

getAllAsync(callback: (asyncResult: Office.AsyncResult<object>) => void): void;

Parameters

callback

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

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.11 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/session-data-apis.yaml

Office.context.mailbox.item.sessionData.getAllAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("The sessionData is " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Failed to get all sessionData. Error: " + JSON.stringify(asyncResult.error));
  }
});

getAsync(name, callback)

Gets the session data value of the specified key.

getAsync(name: string, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

name

string

The session data key.

callback

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

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

Minimum permission level: read item

Applicable Outlook mode: Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/session-data-apis.yaml

Office.context.mailbox.item.sessionData.getAsync(
  "Date",
  function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("The sessionData value is " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Failed to get sessionData. Error: " + JSON.stringify(asyncResult.error));
  }
});

removeAsync(name, options, callback)

Removes a session data key-value pair.

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

Parameters

name

string

The session data key.

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, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.11 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/session-data-apis.yaml

Office.context.mailbox.item.sessionData.removeAsync(
  "Date",
  function callback(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("sessionData.removeAsync succeeded");
    } else {
      console.log("Failed to remove sessionData. Error: " + JSON.stringify(asyncResult.error));
    }
  }
);

removeAsync(name, callback)

Removes a session data key-value pair.

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

Parameters

name

string

The session data key.

callback

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.11 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

setAsync(name, value, options, callback)

Sets a session data key-value pair.

setAsync(name: string, value: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

name

string

The session data key.

value

string

The session data value as a string.

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

Minimum permission level: read item

Applicable Outlook mode: Compose

Important: In Outlook clients that support Mailbox 1.15 or earlier, the entire SessionData object for each mail item is limited to 50,000 characters per add-in. In classic Outlook on Windows, you can preview an increased character limit of up to 2,621,440 characters per add-in. To test the updated limit, join the Microsoft 365 Insider program, then choose the Beta Channel in the classic Outlook on Windows client. Your client must be on Version 2510 (Build 19317.20000) or later.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/session-data-apis.yaml

Office.context.mailbox.item.sessionData.setAsync(
  "Date",
  "7/24/2020",
  function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("sessionData.setAsync succeeded");
  } else {
    console.log("Failed to set sessionData. Error: " + JSON.stringify(asyncResult.error));
  }
});

setAsync(name, value, callback)

Sets a session data key-value pair.

setAsync(name: string, value: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

name

string

The session data key.

value

string

The session data value as a string.

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

Minimum permission level: read item

Applicable Outlook mode: Compose

Important: In Outlook clients that support Mailbox 1.15 or earlier, the entire SessionData object for each mail item is limited to 50,000 characters per add-in. In classic Outlook on Windows, you can preview an increased character limit of up to 2,621,440 characters per add-in. To test the updated limit, join the Microsoft 365 Insider program, then choose the Beta Channel in the classic Outlook on Windows client. Your client must be on Version 2510 (Build 19317.20000) or later.