Office.InternetHeaders interface

The InternetHeaders object represents custom internet headers that are preserved after the message item leaves Exchange and is converted to a MIME message.

Internet headers are stored as string key-value pairs on a per-item basis.

Note: This object is intended for you to set and get your custom headers on a message item. To learn more, see Get and set internet headers on a message in an Outlook add-in.

Remarks

[ API set: Mailbox 1.8 ]

Recommended practices

Currently, internet headers are a finite resource on a user's mailbox. When the quota is exhausted, you can't create any more internet headers on that mailbox, which can result in unexpected behavior from clients that rely on this to function.

Apply the following guidelines when you create internet headers in your add-in.

  • Create the minimum number of headers required. The header quota is based on the total size of headers applied to a message. In Exchange Online, the header limit is capped at 256 KB, while in an Exchange on-premises environment, the limit is determined by your organization's administrator. For further information on header limits, see Exchange Online message limits and Exchange Server message limits.

  • Name headers so that you can reuse and update their values later. As such, avoid naming headers in a variable manner (for example, based on user input, timestamp, etc.).

Minimum permission level: read item

Applicable Outlook mode: Compose

Methods

getAsync(names, options, callback)

Given an array of internet header names, this method returns a record containing those internet headers and their values. If the add-in requests a header that isn't available, that header won't be returned in the results.

Note: This method is intended to return the values of the custom headers you set using the setAsync method.

getAsync(names, callback)

Given an array of internet header names, this method returns a record containing those internet headers and their values. If the add-in requests a header that isn't available, that header won't be returned in the results.

Note: This method is intended to return the values of the custom headers you set using the setAsync method.

removeAsync(names, options, callback)

Given an array of internet header names, this method removes the specified headers from the internet header collection.

Note: This method is intended to remove the custom headers you set using the setAsync method.

removeAsync(names, callback)

Given an array of internet header names, this method removes the specified headers from the internet header collection.

Note: This method is intended to remove the custom headers you set using the setAsync method.

setAsync(headers, options, callback)

Sets the specified internet headers to the specified values.

The setAsync method creates a new header if the specified header doesn't already exist; otherwise, the existing value is replaced with the new value.

Note: This method is intended to set the values of your custom headers.

Important: The header quota is based on the total size of headers applied to a message. In Exchange Online, the header limit is capped at 256 KB, while in an Exchange on-premises environment, the limit is determined by your organization's administrator. For further information on header limits, see Exchange Online message limits and Exchange Server message limits.

setAsync(headers, callback)

Sets the specified internet headers to the specified values.

The setAsync method creates a new header if the specified header doesn't already exist; otherwise, the existing value is replaced with the new value.

Note: This method is intended to set the values of your custom headers.

Important: The header quota is based on the total size of headers applied to a message. In Exchange Online, the header limit is capped at 256 KB, while in an Exchange on-premises environment, the limit is determined by your organization's administrator. For further information on header limits, see Exchange Online message limits and Exchange Server message limits.

Method Details

getAsync(names, options, callback)

Given an array of internet header names, this method returns a record containing those internet headers and their values. If the add-in requests a header that isn't available, that header won't be returned in the results.

Note: This method is intended to return the values of the custom headers you set using the setAsync method.

getAsync(names: string[], options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<Record<string, string>>) => void): void;

Parameters

names

string[]

The names of the internet headers to be returned.

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<Record<string, string>>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, of type Office.AsyncResult. The string key-value pairs of internet headers are returned in the asyncResult.value property. Any errors encountered are provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

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/70-mime-headers/manage-custom-internet-headers-message-compose.yaml

Office.context.mailbox.item.internetHeaders.getAsync(
  ["preferred-fruit", "preferred-vegetable", "best-vegetable", "nonexistent-header"],
  function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("Selected headers: " + JSON.stringify(asyncResult.value));
    } else {
      console.log("Error getting selected headers: " + JSON.stringify(asyncResult.error));
    }
  }
);

getAsync(names, callback)

Given an array of internet header names, this method returns a record containing those internet headers and their values. If the add-in requests a header that isn't available, that header won't be returned in the results.

Note: This method is intended to return the values of the custom headers you set using the setAsync method.

getAsync(names: string[], callback: (asyncResult: Office.AsyncResult<Record<string, string>>) => void): void;

Parameters

names

string[]

The names of the internet headers to be returned.

callback

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

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, of type Office.AsyncResult. The string key-value pairs of internet headers are returned in the asyncResult.value property. Any errors encountered are provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

removeAsync(names, options, callback)

Given an array of internet header names, this method removes the specified headers from the internet header collection.

Note: This method is intended to remove the custom headers you set using the setAsync method.

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

Parameters

names

string[]

The names of the internet headers to be removed.

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, of type Office.AsyncResult. Any errors encountered are provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

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/70-mime-headers/manage-custom-internet-headers-message-compose.yaml

Office.context.mailbox.item.internetHeaders.removeAsync(
  ["best-vegetable", "nonexistent-header"],
  function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("Successfully removed selected headers");
    } else {
      console.log("Error removing selected headers: " + JSON.stringify(asyncResult.error));
    }
  }
);

removeAsync(names, callback)

Given an array of internet header names, this method removes the specified headers from the internet header collection.

Note: This method is intended to remove the custom headers you set using the setAsync method.

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

Parameters

names

string[]

The names of the internet headers to be removed.

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, of type Office.AsyncResult. Any errors encountered are provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

setAsync(headers, options, callback)

Sets the specified internet headers to the specified values.

The setAsync method creates a new header if the specified header doesn't already exist; otherwise, the existing value is replaced with the new value.

Note: This method is intended to set the values of your custom headers.

Important: The header quota is based on the total size of headers applied to a message. In Exchange Online, the header limit is capped at 256 KB, while in an Exchange on-premises environment, the limit is determined by your organization's administrator. For further information on header limits, see Exchange Online message limits and Exchange Server message limits.

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

Parameters

headers

Record<string, string>

The names and corresponding values of the headers to be set. This should be a record object with its keys being internet header names and values being the corresponding header value strings.

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, of type Office.AsyncResult. Any errors encountered are provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

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/70-mime-headers/manage-custom-internet-headers-message-compose.yaml

Office.context.mailbox.item.internetHeaders.setAsync(
  { "preferred-fruit": "orange", "preferred-vegetable": "broccoli", "best-vegetable": "spinach" },
  function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("Successfully set headers");
    } else {
      console.log("Error setting headers: " + JSON.stringify(asyncResult.error));
    }
  }

);

setAsync(headers, callback)

Sets the specified internet headers to the specified values.

The setAsync method creates a new header if the specified header doesn't already exist; otherwise, the existing value is replaced with the new value.

Note: This method is intended to set the values of your custom headers.

Important: The header quota is based on the total size of headers applied to a message. In Exchange Online, the header limit is capped at 256 KB, while in an Exchange on-premises environment, the limit is determined by your organization's administrator. For further information on header limits, see Exchange Online message limits and Exchange Server message limits.

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

Parameters

headers

Record<string, string>

The names and corresponding values of the headers to be set. This should be a record object with its keys being internet header names and values being the corresponding header value strings.

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, of type Office.AsyncResult. Any errors encountered are provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose