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
Minimum permission level: read item
Applicable Outlook mode: Compose
Important: The internet headers API is supported in Outlook on Android and on iOS starting in Version 4.2405.0. To learn more about features supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.
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.).
Methods
| get |
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 |
| get |
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 |
| remove |
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 |
| remove |
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 |
| set |
Sets the specified internet headers to the specified values. The Note: This method is intended to set the values of your custom headers. |
| set |
Sets the specified internet headers to the specified values. The Note: This method is intended to set the values of your custom headers. |
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
Minimum permission level: read item
Applicable Outlook mode: Compose
Important: The internet headers API is supported in Outlook on Android and on iOS starting in Version 4.2405.0. To learn more about features supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.
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
Minimum permission level: read item
Applicable Outlook mode: Compose
Important: The internet headers API is supported in Outlook on Android and on iOS starting in Version 4.2405.0. To learn more about features supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.
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
Minimum permission level: read/write item
Applicable Outlook mode: Compose
Important: The internet headers API is supported in Outlook on Android and on iOS starting in Version 4.2405.0. To learn more about features supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.
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
Minimum permission level: read/write item
Applicable Outlook mode: Compose
Important: The internet headers API is supported in Outlook on Android and on iOS starting in Version 4.2405.0. To learn more about features supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.
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.
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
Minimum permission level: read/write item
Applicable Outlook mode: Compose
Important:
The internet headers API is supported in Outlook on Android and on iOS starting in Version 4.2405.0. To learn more about features supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.
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.
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.
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
Minimum permission level: read/write item
Applicable Outlook mode: Compose
Important:
The internet headers API is supported in Outlook on Android and on iOS starting in Version 4.2405.0. To learn more about features supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.
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.
Office Add-ins