From 9b31f5b577b453c4aa0f1a3db0a5549fa5ac7ad9 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Tue, 29 May 2018 15:36:19 -0700 Subject: [PATCH 1/7] Adding class and method descriptions for Exchange API --- types/office-js/index.d.ts | 2980 +++++++++++++++++++++++++++++------- 1 file changed, 2401 insertions(+), 579 deletions(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index a6d4375fb2..3f3d653fca 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -4315,6 +4315,14 @@ declare namespace Office { declare namespace Office { namespace MailboxEnums { + /** + * Specifies an attachment's type. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ export enum AttachmentType { /** * The attachment is a file @@ -4323,38 +4331,58 @@ declare namespace Office { /** * The attachment is an Exchange item */ - Item + Item, + /** + * The attachment is stored in a cloud location, such as OneDrive. The id property of the attachment contains a URL to the file. + */ + Cloud } + /** + * Specifies an entity's type. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ export enum EntityType { /** - * Specifies that the entity is a meeting suggestion + * Specifies that the entity is a meeting suggestion. */ MeetingSuggestion, /** - * Specifies that the entity is a task suggestion + * Specifies that the entity is a task suggestion. */ TaskSuggestion, /** - * Specifies that the entity is a postal address + * Specifies that the entity is a postal address. */ Address, /** - * Specifies that the entity is SMTP email address + * Specifies that the entity is a SMTP email address. */ EmailAddress, /** - * Specifies that the entity is an Internet URL + * Specifies that the entity is an Internet URL. */ Url, /** - * Specifies that the entity is US phone number + * Specifies that the entity is a US phone number. */ PhoneNumber, /** - * Specifies that the entity is a contact + * Specifies that the entity is a contact. */ Contact } + /** + * Specifies the notification message type for an appointment or message. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ export enum ItemNotificationMessageType { /** * The notificationMessage is a progress indicator. @@ -4369,59 +4397,100 @@ declare namespace Office { */ ErrorMessage } + /** + * Specifies an item's type. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ export enum ItemType { /** - * An email, meeting request, meeting response, or meeting cancellation + * An email, meeting request, meeting response, or meeting cancellation. */ Message, /** - * An appointment item + * An appointment item. */ Appointment } - export enum ResponseType { - /** - * There has been no response from the attendee - */ - None, - /** - * The attendee is the meeting organizer - */ - Organizer, - /** - * The meeting request was tentatively accepted by the attendee - */ - Tentative, - /** - * The meeting request was accepted by the attendee - */ - Accepted, - /** - * The meeting request was declined by the attendee - */ - Declined - } + /** + * Specifies the type of recipient for an appointment. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ export enum RecipientType { /** - * Specifies that the recipient is a distribution list containing a list of email addresses + * Specifies that the recipient is a distribution list containing a list of email addresses. */ DistributionList, /** - * Specifies that the recipient is an SMTP email address that is on the Exchange server + * Specifies that the recipient is an SMTP email address that is on the Exchange server. */ User, /** - * Specifies that the recipient is an SMTP email address that is not on the Exchange server + * Specifies that the recipient is an SMTP email address that is not on the Exchange server. */ ExternalUser, /** - * Specifies that the recipient is not one of the other recipient types + * Specifies that the recipient is not one of the other recipient types. */ Other } + /** + * Specifies the type of response to a meeting invitation. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ + export enum ResponseType { + /** + * There has been no response from the attendee. + */ + None, + /** + * The attendee is the meeting organizer. + */ + Organizer, + /** + * The meeting request was tentatively accepted by the attendee. + */ + Tentative, + /** + * The meeting request was accepted by the attendee. + */ + Accepted, + /** + * The meeting request was declined by the attendee. + */ + Declined + } + /** + * Specifies the version of the REST API that corresponds to a REST-formatted item ID. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ export enum RestVersion { + /** + * Version 1.0. + */ v1_0, + /** + * Version 2.0. + */ v2_0, + /** + * Beta. + */ Beta } } @@ -4441,24 +4510,6 @@ declare namespace Office { */ Subject } - export interface Appointment extends Item { - } - export interface AppointmentCompose extends Appointment, ItemCompose { - end: Time; - location: Location; - optionalAttendees: Recipients; - requiredAttendees: Recipients; - start: Time; - } - export interface AppointmentRead extends Appointment, ItemRead { - end: Date; - location: string; - optionalAttendees: Array; - organizer: EmailAddressDetails; - requiredAttendees: Array; - resources: EmailAddressDetails; - start: Date; - } export interface AppointmentForm { requiredAttendees: Array | Array; optionalAttendees: Array | Array; @@ -4469,253 +4520,982 @@ declare namespace Office { subject: string; body: string; } + /** + * Represents an attachment on an item from the server. Read mode only. + * + * An array of AttachmentDetail objects is returned as the attachments property of an Appointment or Message object. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ export interface AttachmentDetails { + /** + * Gets a value that indicates the type of an attachment. + */ attachmentType: Office.MailboxEnums.AttachmentType; + /** + * Gets the MIME content type of the attachment. + */ contentType: string; + /** + * Gets the Exchange attachment ID of the attachment. + */ id: string; + /** + * Gets a value that indicates whether the attachment should be displayed in the body of the item. + */ isInline: boolean; + /** + * Gets the name of the attachment. + */ name: string; + /** + * Gets the size of the attachment in bytes. + */ size: number; } + /** + * The body object provides methods for adding and updating the content of the message or appointment. It is returned in the body property of the selected item. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ export interface Body { /** - * Returns the current body in a specified format - * @param coercionType The format of the returned body - * @param callback optional method to call when the getAsync method returns + * Returns the current body in a specified format. + * + * This method returns the entire current body in the format specified by coercionType. + * + * When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param coercionType The format for the returned body. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The body is provided in the requested format in the asyncResult.value property. */ - getAsync(coercionType: CoercionType, callback: (result: AsyncResult) => void): void; - /** - * Returns the current body in a specified format - * @param coercionType The format of the returned body - * @param options Any optional parameters or state data passed to the method - * @param callback optional method to call when the getAsync method returns - */ - getAsync(coercionType: CoercionType, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + getAsync(coercionType: CoercionType, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; - /* - * Gets a value that indicates whether the content is in HTML or text format - * @param tableData A TableData object with the headers and rows - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the getTypeAsync method returns + /** + * Gets a value that indicates whether the content is in HTML or text format. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The content type is returned as one of the CoercionType values in the asyncResult.value property. */ getTypeAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** - * Adds the specified content to the beginning of the item body - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters + * Adds the specified content to the beginning of the item body. + * + * The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to it's original place, relative to the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters. + * @param options Optional. 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 method. + * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. Any errors encountered will be provided in the asyncResult.error property. */ - prependAsync(data: string): void; - /** - * Adds the specified content to the beginning of the item body - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters - * @param options Any optional parameters or state data passed to the method - */ - prependAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; - /** - * Adds the specified content to the beginning of the item body - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters - * @param callback The optional method to call when the string is inserted - */ - prependAsync(data: string, callback: (result: AsyncResult) => void): void; - /** - * Adds the specified content to the beginning of the item body - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted - */ - prependAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions, callback: (result: AsyncResult) => void): void; - + prependAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; /** * Replaces the entire body with the specified text. - * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters + * + * When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + * @param options Optional. 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 method. + * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. Any errors encountered will be provided in the asyncResult.error property. */ - setAsync(data: string): void; + setAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; /** - * Replaces the entire body with the specified text. - * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters - * @param options Any optional parameters or state data passed to the method + * Replaces the selection in the body with the specified text. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + * @param options Optional. 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 method. + * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. Any errors encountered will be provided in the asyncResult.error property. */ - setAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; - /** - * Replaces the entire body with the specified text. - * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters - * @param callback the optional method to call when the body is replaced - */ - setAsync(data: string, callback: (result: AsyncResult) => void): void; - /** - * Replaces the entire body with the specified text. - * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters - * @param options Any optional parameters or state data passed to the method - * @param callback the optional method to call when the body is replaced - */ - setAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions, callback: (result: AsyncResult) => void): void; - - /** - * Replaces the selection in the body with the specified text - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters - */ - setSelectedDataAsync(data: string): void; - /** - * Replaces the selection in the body with the specified text - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters - * @param options Any optional parameters or state data passed to the method - */ - setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; - /** - * Replaces the selection in the body with the specified text - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters - * @param callback The optional method to call when the string is inserted - */ - setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; - /** - * Replaces the selection in the body with the specified text - * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted - */ - setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions, callback: (result: AsyncResult) => void): void; - + setSelectedDataAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; } + /** + * Represents a contact stored on the server. Read mode only. + * + * The list of contacts associated with an email message or appointment is returned in the contacts property of the Entities object that is returned by the getEntities or getEntitiesByType method of the active item. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Read + */ export interface Contact { + /** + * An array of strings containing the mailing and street addresses associated with the contact. Nullable. + */ addresses: Array; + /** + * A string containing the name of the business associated with the contact. Nullable. + */ businessName: string; + /** + * An array of strings containing the SMTP email addresses associated with the contact. Nullable, + */ emailAddresses: Array; + /** + * A string containing the name of the person associated with the contact. Nullable. + */ personName: string; + /** + * An array containing a PhoneNumber object for each phone number associated with the contact. Nullable. + */ phoneNumbers: Array; + /** + * An array of strings containing the Internet URLs associated with the contact. Nullable. + */ urls: Array; } /** - * Represents the runtime environment of the add-in and provides access to key objects of the API. - * - * @remarks - * Hosts: Access, Excel, Outlook, PowerPoint, Project, Word - */ + * The Office.context namespace provides shared interfaces that are used by add-ins in all of the Office apps. This listing documents only those interfaces that are used by Outlook add-ins. For a full listing of the Office.context namespace, see the (https://dev.office.com/reference/add-ins/shared/office.context.htm). + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ export interface Context { + /** + * Gets the locale (language) in RFC 1766 Language tag format specified by the user for the UI of the Office host application. + * + * The displayLanguage value reflects the current Display Language setting specified with File > Options > Language in the Office host application. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Applicable Outlook mode: Compose or read + */ + displayLanguage: string; + /** + * Provides access to the Outlook Add-in object model for Microsoft Outlook and Microsoft Outlook on the web. + * + * Namespaces: + * + * - diagnostics: Provides diagnostic information to an Outlook add-in. + * + * - item: Provides methods and properties for accessing a message or appointment in an Outlook add-in. + * + * - userProfile: Provides information about the user in an Outlook add-in. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + */ mailbox: Mailbox; /** - * Gets an object that represents the saved custom settings of the add-in. - */ + * Provides access to the properties for Office theme colors. + * + * Using Office theme colors let's you coordinate the color scheme of your add-in with the current Office theme selected by the user with File > Office Account > Office Theme UI, which is applied across all Office host applications. Using Office theme colors is appropriate for mail and task pane add-ins. + * + * |Name |Type |Description| + * |-----|-----|-----------| + * |bodyBackgroundColor|String|Gets the Office theme body background color as a hexadecimal color triplet.| + * |bodyForegroundColor|String|Gets the Office theme body foreground color as a hexadecimal color triplet.| + * |controlBackgroundColor|String|Gets the Office theme control background color as a hexadecimal color triplet.| + * |controlForegroundColor|String|Gets the Office theme body control color as a hexadecimal color triplet.| + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Note: This member is not supported in Outlook for iOS or Outlook for Android. + * + * Applicable Outlook mode: Compose or read + */ + officeTheme: Object; + /** + * Gets an object that represents the custom settings or state of a mail add-in saved to a user's mailbox. + * + * The RoamingSettings object lets you store and access data for a mail add-in that is stored in a user's mailbox, so that is available to that add-in when it is running from any host client application used to access that mailbox. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + */ roamingSettings: RoamingSettings; } + /** + * The CustomProperties object represents custom properties that are specific to a particular item and specific to a mail add-in for Outlook. For example, there might be a need for a mail add-in to save some data that is specific to the current email message that activated the add-in. If the user revisits the same message in the future and activates the mail add-in again, the add-in will be able to retrieve the data that had been saved as custom properties. + * + * Because Outlook for Mac doesn’t cache custom properties, if the user’s network goes down, mail add-ins cannot access their custom properties. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ export interface CustomProperties { /** - * Returns the value of the specified custom property - * @param name The name of the property to be returned + * Returns the value of the specified custom property. + * @param name The name of the custom property to be returned. + * @returns The value of the specified custom property. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read */ get(name: string): any; /** - * Sets the specified property to the specified value - * @param name The name of the property to be set - * @param value The value of the property to be set + * Sets the specified property to the specified value. + * + * The set method sets the specified property to the specified value. You must use the saveAsync method to save the property to the server. + * + * The set method creates a new property if the specified property does not already exist; otherwise, the existing value is replaced with the new value. The value parameter can be of any type; however, it is always passed to the server as a string. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param name The name of the property to be set. + * @param value The value of the property to be set. */ set(name: string, value: string): void; /** * Removes the specified property from the custom property collection. - * @param name The name of the property to be removed + * + * To make the removal of the property permanent, you must call the saveAsync method of the CustomProperties object. + * @param name The name of the property to be removed. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read */ remove(name: string): void; /** - * Saves the custom property collection to the server - * @param callback The optional callback method - * @param userContext Optional variable for any state data that is passed to the saveAsync method + * Saves item-specific custom properties to the server. + * + * You must call the saveAsync method to persist any changes made with the set method or the remove method of the CustomProperties object. The saving action is asynchronous. + * + * It’s a good practice to have your callback function check for and handle errors from saveAsync. In particular, a read add-in can be activated while the user is in a connected state in a read form, and subsequently the user becomes disconnected. If the add-in calls saveAsync while in the disconnected state, saveAsync would return an error. Your callback method should handle this error accordingly. + * + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param asyncContext Optional. Any state data that is passed to the callback method. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read */ - saveAsync(callback?: (result: AsyncResult) => void, userContext?: any): void; + saveAsync(callback?: (result: AsyncResult) => void, asyncContext?: any): void; } + /** + * Provides diagnostic information to an Outlook add-in. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ export interface Diagnostics { + /** + * Gets a string that represents the name of the host application. + * + * A string that can be one of the following values: Outlook, Mac Outlook, OutlookIOS, or OutlookWebApp. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ hostName: string; + /** + * Gets a string that represents the version of either the host application or the Exchange Server. + * + * If the mail add-in is running on the Outlook desktop client or Outlook for iOS, the hostVersion property returns the version of the host application, Outlook. In Outlook Web App, the property returns the version of the Exchange Server. An example is the string 15.0.468.0. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ hostVersion: string; + /** + * Gets a string that represents the current view of Outlook Web App. + * + * The returned string can be one of the following values: OneColumn, TwoColumns, or ThreeColumns. + * + * If the host application is not Outlook Web App, then accessing this property results in undefined. + * + * Outlook Web App has three views that correspond to the width of the screen and the window, and the number of columns that can be displayed: + * + * - OneColumn, which is displayed when the screen is narrow. Outlook Web App uses this single-column layout on the entire screen of a smartphone. + * + * - TwoColumns, which is displayed when the screen is wider. Outlook Web App uses this view on most tablets. + * + * - ThreeColumns, which is displayed when the screen is wide. For example, Outlook Web App uses this view in a full screen window on a desktop computer. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ OWAView: string; } + /** + * Provides the email properties of the sender or specified recipients of an email message or appointment. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ export interface EmailAddressDetails { + /** + * Gets the SMTP email address. + */ emailAddress: string; + /** + * Gets the display name associated with an email address. + */ displayName: string; + /** + * Gets the response that an attendee returned for an appointment. This property applies to only an attendee of an appointment, as represented by the optionalAttendees or requiredAttendees property. This property returns undefined in other scenarios. + */ appointmentResponse: Office.MailboxEnums.ResponseType; + /** + * Gets the email address type of a recipient. + */ recipientType: Office.MailboxEnums.RecipientType; } + /** + * Represents an email account on an Exchange Server. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ export interface EmailUser { + /** + * Gets the display name associated with an email address. + */ displayName: string; + /** + * Gets the SMTP email address. + */ emailAddress: string; } + /** + * Represents a collection of entities found in an email message or appointment. Read mode only. + * + * The Entities object is a container for the entity arrays returned by the getEntities and getEntitiesByType methods when the item (either an email message or an appointment) contains one or more entities that have been found by the server. You can use these entities in your code to provide additional context information to the viewer, such as a map to an address found in the item, or to open a dialer for a phone number found in the item. + * + * If no entities of the type specified in the property are present in the item, the property associated with that entity is null. For example, if a message contains a street address and a phone number, the addresses property and phoneNumbers property would contain information, and the other properties would be null. + * + * To be recognized as an address, the string must contain a United States postal address that has at least a subset of the elements of a street number, street name, city, state, and zip code. + * + * To be recognized as a phone number, the string must contain a North American phone number format. + * + * Entity recognition relies on natural language recognition that is based on machine learning of large amounts of data. The recognition of an entity is non-deterministic and success sometimes relies on the particular context in the item. + * + * When the property arrays are returned by the getEntitiesByType method, only the property for the specified entity contains data; all other properties are null. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ export interface Entities { + /** + * Gets the physical addresses (street or mailing addresses) found in an email message or appointment. + */ addresses: Array; + /** + * Gets the contacts found in an email address or appointment. + */ contacts: Array; + /** + * Gets the email addresses found in an email message or appointment. + */ emailAddresses: Array; + /** + * Gets the meeting suggestions found in an email message. + */ meetingSuggestions: Array; + /** + * Gets the phone numbers found in an email message or appointment. + */ phoneNumbers: Array; + /** + * Gets the task suggestions found in an email message or appointment. + */ taskSuggestions: Array; + /** + * Gets the Internet URLs present in an email message or appointment. + */ urls: Array; } + + + export interface Appointment extends Item { + } + export interface AppointmentCompose extends Appointment, ItemCompose { + /** + * Gets or sets the date and time that the appointment is to end. + * + * The end property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client’s local date and time. + * + * *Read mode* + * + * The end property returns a Date object. + * + * *Compose mode* + * + * The end property returns a Time object. + * + * When you use the Time.setAsync method to set the end time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + end: Time; + /** + * Gets or sets the location of an appointment. + * + * *Read mode* + * + * The location property returns a string that contains the location of the appointment. + * + * *Compose mode* + * + * The location property returns a Location object that provides methods that are used to get and set the location of the appointment. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + location: Location; + /** + * Provides access to the optional attendees of an event. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The optionalAttendees property returns an array that contains an EmailAddressDetails object for each optional attendee to the meeting. + * + * *Compose mode* + * + * The optionalAttendees property returns a Recipients object that provides methods to get or update the optional attendees for a meeting. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + optionalAttendees: Recipients; + /** + * Provides access to the required attendees of an event. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The requiredAttendees property returns an array that contains an EmailAddressDetails object for each required attendee to the meeting. + * + * *Compose mode* + * + * The requiredAttendees property returns a Recipients object that provides methods to get or update the required attendees for a meeting. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + requiredAttendees: Recipients; + /** + * Gets or sets the date and time that the appointment is to begin. + * + * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client’s local date and time. + * + * *Read mode* + * + * The start property returns a Date object. + * + * *Compose mode* + * + * The start property returns a Time object. + * + * When you use the Time.setAsync method to set the start time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + start: Time; + } + export interface AppointmentRead extends Appointment, ItemRead { + end: Date; + /** + * Gets or sets the location of an appointment. + * + * *Read mode* + * + * The location property returns a string that contains the location of the appointment. + * + * *Compose mode* + * + * The location property returns a Location object that provides methods that are used to get and set the location of the appointment. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + location: string; + /** + * Provides access to the optional attendees of an event. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The optionalAttendees property returns an array that contains an EmailAddressDetails object for each optional attendee to the meeting. + * + * *Compose mode* + * + * The optionalAttendees property returns a Recipients object that provides methods to get or update the optional attendees for a meeting. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + optionalAttendees: Array; + /** + * Gets the email address of the meeting organizer for a specified meeting. Read mode only. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ + organizer: EmailAddressDetails; + /** + * Provides access to the required attendees of an event. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The requiredAttendees property returns an array that contains an EmailAddressDetails object for each required attendee to the meeting. + * + * *Compose mode* + * + * The requiredAttendees property returns a Recipients object that provides methods to get or update the required attendees for a meeting. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + requiredAttendees: Array; + /** + * Gets or sets the date and time that the appointment is to begin. + * + * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client’s local date and time. + * + * *Read mode* + * + * The start property returns a Date object. + * + * *Compose mode* + * + * The start property returns a Time object. + * + * When you use the Time.setAsync method to set the start time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + start: Date; + } + export interface AppointmentForm { + /** + * Gets or sets the date and time that the appointment is to end. + * + * The end property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client’s local date and time. + * + * *Read mode* + * + * The end property returns a Date object. + * + * *Compose mode* + * + * The end property returns a Time object. + * + * When you use the Time.setAsync method to set the end time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + end: Date; + /** + * Gets or sets the location of an appointment. + * + * *Read mode* + * + * The location property returns a string that contains the location of the appointment. + * + * *Compose mode* + * + * The location property returns a Location object that provides methods that are used to get and set the location of the appointment. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + location: string; + /** + * Provides access to the optional attendees of an event. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The optionalAttendees property returns an array that contains an EmailAddressDetails object for each optional attendee to the meeting. + * + * *Compose mode* + * + * The optionalAttendees property returns a Recipients object that provides methods to get or update the optional attendees for a meeting. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + optionalAttendees: Array | Array; + /** + * Provides access to the required attendees of an event. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The requiredAttendees property returns an array that contains an EmailAddressDetails object for each required attendee to the meeting. + * + * *Compose mode* + * + * The requiredAttendees property returns a Recipients object that provides methods to get or update the required attendees for a meeting. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + requiredAttendees: Array | Array; + /** + * Gets or sets the date and time that the appointment is to begin. + * + * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client’s local date and time. + * + * *Read mode* + * + * The start property returns a Date object. + * + * *Compose mode* + * + * The start property returns a Time object. + * + * When you use the Time.setAsync method to set the start time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + start: Date; + /** + * Gets or sets the description that appears in the subject field of an item. + * + * The subject property gets or sets the entire subject of the item, as sent by the email server. + * + * *Read mode* + * + * The subject property returns a string. Use the normalizedSubject property to get the subject minus any leading prefixes such as RE: and FW:. + * + * *Compose mode* + * + * The subject property returns a Subject object that provides methods to get and set the subject. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + subject: string; + } + + /** + * The item namespace is used to access the currently selected message, meeting request, or appointment. You can determine the type of the item by using the itemType property. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + */ export interface Item { + /** + * Gets an object that provides methods for manipulating the body of an item. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ body: Body; - itemType: Office.MailboxEnums.ItemType; - notificationMessages: NotificationMessages; + /** + * Gets the date and time that an item was created. Read mode only. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ dateTimeCreated: Date; /** - * Asynchronously loads custom properties that are specific to the item and a app for Office - * @param callback The optional callback method - * @param userContext Optional variable for any state data that is passed to the asynchronous method + * Gets the date and time that an item was last modified. Read mode only. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] This member is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read */ - loadCustomPropertiesAsync(callback?: (result: AsyncResult) => void, userContext?: any): void; + dateTimeModifed: Date; + /** + * Gets the type of item that an instance represents. + * + * The itemType property returns one of the ItemType enumeration values, indicating whether the item object instance is a message or an appointment. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + itemType: Office.MailboxEnums.ItemType; + /** + * Gets the notification messages for an item. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + notificationMessages: NotificationMessages; + /** + * Asynchronously loads custom properties for this add-in on the selected item. + * + * Custom properties are stored as key/value pairs on a per-app, per-item basis. This method returns a CustomProperties object in the callback, which provides methods to access the custom properties specific to the current item and the current add-in. Custom properties are not encrypted on the item, so this should not be used as secure storage. + * + * The custom properties are provided as a CustomProperties object in the asyncResult.value property. This object can be used to get, set, and remove custom properties from the item and save changes to the custom property set back to the server. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param userContext Optional. Developers can provide any object they wish to access in the callback function. This object can be accessed by the asyncResult.asyncContext property in the callback function. + */ + loadCustomPropertiesAsync(callback: (result: AsyncResult) => void, userContext?: any): void; } export interface ItemCompose extends Item { + /** + * Gets or sets the description that appears in the subject field of an item. + * + * The subject property gets or sets the entire subject of the item, as sent by the email server. + * + * *Read mode* + * + * The subject property returns a string. Use the normalizedSubject property to get the subject minus any leading prefixes such as RE: and FW:. + * + * *Compose mode* + * + * The subject property returns a Subject object that provides methods to get and set the subject. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ subject: Subject; /** - * Adds a file to a message as an attachment - * @param uri The URI that provides the location of the file to attach to the message. The maximum length is 2048 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters + * Adds a file to a message or appointment as an attachment. + * + * The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * + * Errors: + * + * AttachmentSizeExceeded - The attachment is larger than allowed. + * + * FileTypeNotSupported - The attachment has an extension that is not allowed. + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param uri The URI that provides the location of the file to attach to the message or appointment. The maximum length is 2048 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + * @param options Optional. 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 method. + * inInline: If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. On success, the attachment identifier will be provided in the asyncResult.value property. If uploading the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. */ - addFileAttachmentAsync(uri: string, attachmentName: string): void; + addFileAttachmentAsync(uri: string, attachmentName: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** - * Adds a file to a message as an attachment - * @param uri The URI that provides the location of the file to attach to the message. The maximum length is 2048 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters - * @param options Any optional parameters or state data passed to the method + * Adds an Exchange item, such as a message, as an attachment to the message or appointment. + * + * The addItemAttachmentAsync method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback method, the method is called with one parameter, asyncResult, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback method, if needed. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * If your Office add-in is running in Outlook Web App, the addItemAttachmentAsync method can attach items to items other than the item that you are editing; however, this is not supported and is not recommended. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * + * Errors: + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + * @param options 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 method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. On success, the attachment identifier will be provided in the asyncResult.value property. If adding the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. */ - addFileAttachmentAsync(uri: string, attachmentName: string, options: AsyncContextOptions): void; - /** - * Adds a file to a message as an attachment - * @param uri The URI that provides the location of the file to attach to the message. The maximum length is 2048 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters - * @param callback The optional callback method - */ - addFileAttachmentAsync(uri: string, attachmentName: string, callback: (result: AsyncResult) => void): void; - /** - * Adds a file to a message as an attachment - * @param uri The URI that provides the location of the file to attach to the message. The maximum length is 2048 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters - * @param options Any optional parameters or state data passed to the method - * @param callback The optional callback method - */ - addFileAttachmentAsync(uri: string, attachmentName: string, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - - /** - * Adds an Exchange item, such as a message, as an attachment to the message - * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters - */ - addItemAttachmentAsync(itemId: any, attachmentName: string): void; - /** - * Adds an Exchange item, such as a message, as an attachment to the message - * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters - * @param options Any optional parameters or state data passed to the method - */ - addItemAttachmentAsync(itemId: any, attachmentName: string, options: AsyncContextOptions): void; - /** - * Adds an Exchange item, such as a message, as an attachment to the message - * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters - * @param callback The optional callback method - */ - addItemAttachmentAsync(itemId: any, attachmentName: string, callback: (result: AsyncResult) => void): void; - /** - * Adds an Exchange item, such as a message, as an attachment to the message - * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters - * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters - * @param options Any optional parameters or state data passed to the method - * @param callback The optional callback method - */ - addItemAttachmentAsync(itemId: any, attachmentName: string, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - + addItemAttachmentAsync(itemId: any, attachmentName: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Closes the current item that is being composed * @@ -4723,473 +5503,1345 @@ declare namespace Office { * prompts the user to save, discard, or close the action. * * In the Outlook desktop client, if the message is an inline reply, the close method has no effect. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * [!NOTE] In Outlook on the web, if the item is an appointment and it has previously been saved using saveAsync, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved. + * + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose */ close(): void; + /** + * Gets initialization data passed when the add-in is [activated by an actionable message]. + * + * [Api set: Mailbox Preview] + * + * @remarks + * + * [!NOTE] This method is only supported by Outlook 2016 for Windows (Click-to-Run versions greater than 16.0.8413.1000) and Outlook on the web for Office 365. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. On success, the initialization data is provided in the asyncResult.value property as a string. If there is no initialization context, the asyncResult object will contain an Error object with its code property set to 9020 and its name property set to GenericResponseError. + */ + getInitializationContextAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Asynchronously returns selected data from the subject or body of a message. - * - * If there is no selection but the cursor is in the body or the subject, the method returns null for the selected data. If a field other - * than the body or subject is selected, the method returns the InvalidSelection error + * + * If there is no selection but the cursor is in the body or subject, the method returns null for the selected data. If a field other than the body or subject is selected, the method returns the InvalidSelection error. + * + * [Api set: Mailbox 1.0] + * + * @returns + * The selected data as a string with format determined by coercionType. + * + * @remarks + * + * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. + * + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * + * @param coercionType Requests a format for the data. If Text, the method returns the plain text as a string , removing any HTML tags present. If HTML, the method returns the selected text, whether it is plaintext or HTML. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getSelectedDataAsync(coercionType: CoercionType, callback: (result: AsyncResult) => void): void; /** * Asynchronously returns selected data from the subject or body of a message. + * + * If there is no selection but the cursor is in the body or subject, the method returns null for the selected data. If a field other than the body or subject is selected, the method returns the InvalidSelection error. + * + * [Api set: Mailbox 1.0] + * + * @returns + * The selected data as a string with format determined by coercionType. * - * If there is no selection but the cursor is in the body or the subject, the method returns null for the selected data. If a field other - * than the body or subject is selected, the method returns the InvalidSelection error + * @remarks + * + * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. + * + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * + * @param coercionType Requests a format for the data. If Text, the method returns the plain text as a string , removing any HTML tags present. If HTML, the method returns the selected text, whether it is plaintext or HTML. + * @param options 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 method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getSelectedDataAsync(coercionType: CoercionType, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - /** - * Removes an attachment from a message - * @param attachmentIndex The index of the attachment to remove. The maximum length of the string is 100 characters + * Removes an attachment from a message or appointment. + * + * The removeAttachmentAsync method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook Web App and OWA for Devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing in an inline form and subsequently pops out the inline form to continue in a separate window. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param attachmentIndex The identifier of the attachment to remove. The maximum length of the string is 100 characters. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ - removeAttachmentAsync(attachmentIndex: string): void; - /** - * Removes an attachment from a message - * @param attachmentIndex The index of the attachment to remove. The maximum length of the string is 100 characters - * @param options Any optional parameters or state data passed to the method - */ - removeAttachmentAsync(attachmentIndex: string, options: AsyncContextOptions): void; - /** - * Removes an attachment from a message - * @param attachmentIndex The index of the attachment to remove. The maximum length of the string is 100 characters - * @param callback The optional callback method - */ - removeAttachmentAsync(attachmentIndex: string, callback: (result: AsyncResult) => void): void; - /** - * Removes an attachment from a message - * @param attachmentIndex The index of the attachment to remove. The maximum length of the string is 100 characters - * @param options Any optional parameters or state data passed to the method - * @param callback The optional callback method - */ - removeAttachmentAsync(attachmentIndex: string, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - - /** + removeAttachmentAsync(attachmentIndex: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** * Asynchronously saves an item. - * - * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or - * Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. + * + * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. + * + * Since appointments have no draft state, if saveAsync is called on an appointment in compose mode, the item will be saved as a normal appointment on the user's calendar. For new appointments that have not been saved before, no invitation will be sent. Saving an existing appointment will send an update to added or removed attendees. + * + * + * [Api set: Mailbox 1.3] + * + * @remarks + * [!NOTE] If your add-in calls saveAsync on an item in compose mode in order to get an itemId to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the itemId will return an error. + * + * [!NOTE] The following clients have different behavior for saveAsync on appointments in compose mode: + * + * - Mac Outlook does not support saveAsync on a meeting in compose mode. Calling saveAsync on a meeting in Mac Outlook will return an error. + * + * - Outlook on the web always sends an invitation or update when saveAsync is called on an appointment in compose mode. + * + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ - saveAsync(): void; - /** - * Asynchronously saves an item. - * - * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or - * Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. - */ - saveAsync(options: AsyncContextOptions): void; - /** - * Asynchronously saves an item. - * - * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or - * Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. - */ - saveAsync(callback: (result: AsyncResult) => void): void; - /** - * Asynchronously saves an item. - * - * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or - * Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. - */ - saveAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - - /** - * Asynchronously inserts data into the body or subject of a message. - */ - setSelectedDataAsync(data: string): void; - /** - * Asynchronously inserts data into the body or subject of a message. - */ - setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + saveAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Asynchronously inserts data into the body or subject of a message. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content. + * + * [Api set: Mailbox 1.2] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; /** * Asynchronously inserts data into the body or subject of a message. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content. + * + * [Api set: Mailbox 1.2] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. + * @param options Optional. 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 method. + * coercionType: If text, the current style is applied in Outlook Web App and Outlook. If the field is an HTML editor, only the text data is inserted, even if the data is HTML. If html and the field supports HTML (the subject doesn't), the current style is applied in Outlook Web App and the default style is applied in Outlook. If the field is a text field, an InvalidDataFormat error is returned. If coercionType is not set, the result depends on the field: if the field is HTML then HTML is used; if the field is text, then plain text is used. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions, callback: (result: AsyncResult) => void): void; } export interface ItemRead extends Item { + /** + * Gets an array of attachments for the item. Read mode only. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] Certain types of files are blocked by Outlook due to potential security issues and are therefore not returned. For more information, see [Blocked attachments in Outlook]. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + */ attachments: Array; + /** + * Gets the Exchange Web Services item class of the selected item. Read mode only. + * + * The itemClass property specifies the message class of the selected item. The following are the default message classes for the message or appointment item. + * + * [div class="mx-tdBreakAll"|Type|Description|item class| + * |-----------|------------|------------| + * |Appointment items|These are calendar items of the item class IPM.Appointment or IPM.Appointment.Occurence.|IPM.Appointment,IPM.Appointment.Occurence| + * |Message items|These include email messages that have the default message class IPM.Note, and meeting requests, responses, and cancellations, that use IPM.Schedule.Meeting as the base message class.|IPM.Note,IPM.Schedule.Meeting.Request,IPM.Schedule.Meeting.Neg,IPM.Schedule.Meeting.Pos,IPM.Schedule.Meeting.Tent,IPM.Schedule.Meeting.Canceled| + * + * You can create custom message classes that extends a default message class, for example, a custom appointment message class IPM.Appointment.Contoso. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ itemClass: string; + /** + * Gets the Exchange Web Services item identifier for the current item. Read mode only. + * + * The itemId property is not available in compose mode. If an item identifier is required, the saveAsync method can be used to save the item to the store, which will return the item identifier in the AsyncResult.value parameter in the callback function. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ itemId: string; + /** + * Gets the subject of an item, with all prefixes removed (including RE: and FWD:). Read mode only. + * + * The normalizedSubject property gets the subject of the item, with any standard prefixes (such as RE: and FW:) that are added by email programs. To get the subject of the item with the prefixes intact, use the subject property. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ normalizedSubject: string; + /** + * Gets or sets the description that appears in the subject field of an item. + * + * The subject property gets or sets the entire subject of the item, as sent by the email server. + * + * *Read mode* + * + * The subject property returns a string. Use the normalizedSubject property to get the subject minus any leading prefixes such as RE: and FW:. + * + * *Compose mode* + * + * The subject property returns a Subject object that provides methods to get and set the subject. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ subject: string; /** - * Displays a reply form that includes the sender and all the recipients of the selected message + * Displays a reply form that includes the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment. + * + * In Outlook Web App, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2- or 1-column view. + * + * If any of the string parameters exceed their limits, displayReplyAllForm throws an exception. + * + * When attachments are specified in the formData.attachments parameter, Outlook and Outlook Web App attempt to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * * @param formData A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB * OR * An object that contains body or attachment data and a callback function + * htmlBody: A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB. + * attachments: An array of JSON objects that are either file or item attachments. + * attachments.type: Indicates the type of attachment. Must be file for a file attachment or item for an item attachment. + * attachments.name: A string that contains the name of the attachment, up to 255 characters in length. + * attachments.url: Only used if type is set to file. The URI of the location for the file. + * attachments.isLine: Only used if type is set to file. If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list. + * attachments.itemId: Only used if type is set to item. The EWS item id of the attachment. This is a string up to 100 characters. */ displayReplyAllForm(formData: string | ReplyFormData): void; /** - * Displays a reply form that includes only the sender of the selected message - * @param formData A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB - * OR - * An object that contains body or attachment data and a callback function + * Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment. + * + * In Outlook Web App, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2- or 1-column view. + * + * If any of the string parameters exceed their limits, displayReplyForm throws an exception. + * + * When attachments are specified in the formData.attachments parameter, Outlook and Outlook Web App attempt to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + * @param formData A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB. + * OR + * An object that contains body or attachment data and a callback function. The object is defined as follows. + * htmlBody: A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB. + * attachments: An array of JSON objects that are either file or item attachments. + * attachments.type: Indicates the type of attachment. Must be file for a file attachment or item for an item attachment. + * attachments.name: A string that contains the name of the attachment, up to 255 characters in length. + * attachments.url: Only used if type is set to file. The URI of the location for the file. + * attachments.isLine: Only used if type is set to file. If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list. + * attachments.itemId: Only used if type is set to item. The EWS item id of the attachment. This is a string up to 100 characters. */ displayReplyForm(formData: string | ReplyFormData): void; /** - * Gets the entities found in the selected item + * Gets the entities found in the selected item. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read */ getEntities(): Entities; /** - * Gets an array of entities of the specified entity type found in an message - * @param entityType One of the EntityType enumeration values + * Gets an array of all the entities of the specified entity type found in the selected item. + * + * [Api set: Mailbox 1.0] + * + * @returns + * If the value passed in entityType is not a valid member of the EntityType enumeration, the method returns null. If no entities of the specified type are present on the item, the method returns an empty array. Otherwise, the type of the objects in the returned array depends on the type of entity requested in the entityType parameter. + * + * While the minimum permission level to use this method is Restricted, some entity types require ReadItem to access, as specified in the following table. + * |Value of entityType|Type of objects in returned array|Required Permission Level| + * |-------|-----------|----------| + * |Address|String|Restricted| + * |Contact|Contact|ReadItem| + * |EmailAddress|String|ReadItem| + * |MeetingSuggestion|MeetingSuggestion|ReadItem| + * |PhoneNumber|PhoneNumber|Restricted| + * |TaskSuggestion|TaskSuggestion|ReadItem| + * |URL|String|Restricted| + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: Restricted + * Applicable Outlook mode: Read + * @param entityType One of the EntityType enumeration values. */ getEntitiesByType(entityType: Office.MailboxEnums.EntityType): Array<(string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)>; /** - * Returns well-known entities that pass the named filter defined in the manifest XML file - * @param name The name of the ItemHasKnownEntity rule element that defines the filter to match + * Returns well-known entities in the selected item that pass the named filter defined in the manifest XML file. + * + * The getFilteredEntitiesByName method returns the entities that match the regular expression defined in the ItemHasKnownEntity rule element in the manifest XML file with the specified FilterName element value. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + * @param name The name of the ItemHasKnownEntity rule element that defines the filter to match. + * @returns If there is no ItemHasKnownEntity element in the manifest with a FilterName element value that matches the name parameter, the method returns null. If the name parameter does match an ItemHasKnownEntity element in the manifest, but there are no entities in the current item that match, the method return an empty array. */ getFilteredEntitiesByName(name: string): Array<(string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)>; /** - * Returns string values in the currently selected message object that match the regular expressions defined in the manifest XML file + * Returns string values in the selected item that match the regular expressions defined in the manifest XML file. + * + * The getRegExMatches method returns the strings that match the regular expression defined in each ItemHasRegularExpressionMatch or ItemHasKnownEntity rule element in the manifest XML file. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties. + * + * If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body. + * + * [Api set: Mailbox 1.0] + * + * @returns + * An object that contains arrays of strings that match the regular expressions defined in the manifest XML file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule or the FilterName attribute of the matching ItemHasKnownEntity rule. + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read */ getRegExMatches(): any; /** - * Returns string values that match the named regular expression defined in the manifest XML file + * Returns string values in the selected item that match the named regular expression defined in the manifest XML file. + * + * The getRegExMatchesByName method returns the strings that match the regular expression defined in the ItemHasRegularExpressionMatch rule element in the manifest XML file with the specified RegExName element value. + * + * If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. + * + * [Api set: Mailbox 1.0] + * + * @returns + * An array that contains the strings that match the regular expression defined in the manifest XML file. + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + * @param name The name of the ItemHasRegularExpressionMatch rule element that defines the filter to match. */ getRegExMatchesByName(name: string): Array; /** - * Gets the entities found in the selected item that are currently selected - * - * [Api set: Mailbox 1.6] - */ + * Gets the entities found in a highlighted match a user has selected. Highlighted matches apply to contextual add-ins. + * + * [Api set: Mailbox 1.6] + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + * @param name The name of the ItemHasRegularExpressionMatch rule element that defines the filter to match. + */ getSelectedEntities(): Entities; /** - * Returns string values in the currently selected message object that match the regular expressions defined in the manifest XML file and - * are selected in the current item - * + * Returns string values in a highlighted match that match the regular expressions defined in the manifest XML file. Highlighted matches apply to contextual add-ins. + * + * The getSelectedRegExMatches method returns the strings that match the regular expression defined in each ItemHasRegularExpressionMatch or ItemHasKnownEntity rule element in the manifest XML file. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties. + * + * If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body. + * * [Api set: Mailbox 1.6] + * + * @returns + * An object that contains arrays of strings that match the regular expressions defined in the manifest XML file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule or the FilterName attribute of the matching ItemHasKnownEntity rule. + * + * @remarks + * + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read */ getSelectedRegExMatches(): any; } + export interface Message extends Item { + /** + * Gets an identifier for the email conversation that contains a particular message. + * + * You can get an integer for this property if your mail app is activated in read forms or responses in compose forms. If subsequently the user changes the subject of the reply message, upon sending the reply, the conversation ID for that message will change and that value you obtained earlier will no longer apply. + * + * You get null for this property for a new item in a compose form. If the user sets a subject and saves the item, the conversationId property will return a value. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + conversationId: string; + } + export interface MessageCompose extends Message, ItemCompose { + /** + * Gets an object that provides methods to get or update the recipients on the Bcc (blind carbon copy) line of a message. Compose mode only. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + */ + bcc: Recipients; + /** + * Provides access to the Cc (carbon copy) recipients of a message. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The cc property returns an array that contains an EmailAddressDetails object for each recipient listed on the Cc line of the message. The collection is limited to a maximum of 100 members. + * + * *Compose mode* + * + * The cc property returns a Recipients object that provides methods to get or update the recipients on the Cc line of the message. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + cc: Recipients; + /** + * Provides access to the recipients on the To line of a message. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The to property returns an array that contains an EmailAddressDetails object for each recipient listed on the To line of the message. The collection is limited to a maximum of 100 members. + * + * *Compose mode* + * + * The to property returns a Recipients object that provides methods to get or update the recipients on the To line of the message. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + to: Recipients; + } + export interface MessageRead extends Message, ItemRead { + /** + * Provides access to the Cc (carbon copy) recipients of a message. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The cc property returns an array that contains an EmailAddressDetails object for each recipient listed on the Cc line of the message. The collection is limited to a maximum of 100 members. + * + * *Compose mode* + * + * The cc property returns a Recipients object that provides methods to get or update the recipients on the Cc line of the message. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + cc: Array; + /** + * Gets the email address of the sender of a message. Read mode only. + * + * The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] The recipientType property of the EmailAddressDetails object in the from property is undefined. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ + from: EmailAddressDetails; + /** + * Gets the Internet message identifier for an email message. Read mode only. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ + internetMessageId: string; + /** + * Gets the email address of the sender of an email message. Read mode only. + * + * The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] The recipientType property of the EmailAddressDetails object in the sender property is undefined. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ + sender: EmailAddressDetails; + /** + * Provides access to the recipients on the To line of a message. The type of object and level of access depends on the mode of the current item. + * + * *Read mode* + * + * The to property returns an array that contains an EmailAddressDetails object for each recipient listed on the To line of the message. The collection is limited to a maximum of 100 members. + * + * *Compose mode* + * + * The to property returns a Recipients object that provides methods to get or update the recipients on the To line of the message. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + to: Array; + } + + /** + * Represents a date and time in the local client's time zone. Read mode only. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ export interface LocalClientTime { + /** + * Integer value representing the month, beginning with 0 for January to 11 for December. + */ month: number; + /** + * Integer value representing the day of the month. + */ date: number; + /** + * Integer value repesenting the year. + */ year: number; + /** + * Integer value representing the hour on a 24-hour clock. + */ hours: number; + /** + * Integer value representing the minutes. + */ minutes: number; + /** + * Integer value representing the seconds. + */ seconds: number; + /** + * Integer value representing the milliseconds. + */ milliseconds: number; + /** + * Integer value representing the number of minutes difference between the local time zone and UTC. + */ timezoneOffset: number; } + /** + * Provides methods to get and set the location of a meeting in an Outlook add-in. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + */ export interface Location { /** - * Begins an asynchronous request for the location of an appointment - * @param callback The optional method to call when the string is inserted + * Gets the location of an appointment. + * + * The getAsync method starts an asynchronous call to the Exchange server to get the location of an appointment. The location of the appointment is provided as a string in the asyncResult.value property. + * + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose */ - getAsync(callback: (result: AsyncResult) => void): void; + getAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** - * Begins an asynchronous request for the location of an appointment - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted + * Sets the location of an appointment. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the location of an appointment. Setting the location of an appointment overwrites the current location. + * + * @param data The location of the appointment. The string is limited to 255 characters. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the location fails, the asyncResult.error property will contain an error code. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The location parameter is longer than 255 characters. */ - getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - - /** - * Begins an asynchronous request to set the location of an appointment - * @param data The location of the appointment. The string is limited to 255 characters - */ - setAsync(location: string): void; - /** - * Begins an asynchronous request to set the location of an appointment - * @param data The location of the appointment. The string is limited to 255 characters - * @param options Any optional parameters or state data passed to the method - */ - setAsync(location: string, options: AsyncContextOptions): void; - /** - * Begins an asynchronous request to set the location of an appointment - * @param data The location of the appointment. The string is limited to 255 characters - * @param callback The optional method to call when the location is set - */ - setAsync(location: string, callback: (result: AsyncResult) => void): void; - /** - * Begins an asynchronous request to set the location of an appointment - * @param data The location of the appointment. The string is limited to 255 characters - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the location is set - */ - setAsync(location: string, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + setAsync(location: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; } + /** + * Provides access to the Outlook Add-in object model for Microsoft Outlook and Microsoft Outlook on the web. + * + * Namespaces: + * + * - diagnostics: Provides diagnostic information to an Outlook add-in. + * + * - item: Provides methods and properties for accessing a message or appointment in an Outlook add-in. + * + * - userProfile: Provides information about the user in an Outlook add-in. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + */ export interface Mailbox { - diagnostics: Diagnostics; + /** + * Gets the URL of the Exchange Web Services (EWS) endpoint for this email account. Read mode only. + * + * The ewsUrl value can be used by a remote service to make EWS calls to the user's mailbox. For example, you can create a remote service to [get attachments from the selected item]. + * + * Your app must have the ReadItem permission specified in its manifest to call the ewsUrl member in read mode. + * + * In compose mode you must call the saveAsync method before you can use the ewsUrl member. Your app must have ReadWriteItem permissions to call the saveAsync method. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] This member is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ ewsUrl: string; - /** The mailbox item. Depending on the context in which the add-in opened, the item may be of any number of types. + /** + * The mailbox item. Depending on the context in which the add-in opened, the item may be of any number of types. * If you want to see IntelliSense for only a specific type, you should cast this item to one of the following: * `ItemCompose`, `ItemRead`, `MessageCompose`, `MessageRead`, `AppointmentCompose`, `AppointmentRead` - */ - item: Item & MessageRead & MessageCompose & AppointmentRead & AppointmentCompose; - userProfile: UserProfile; + */ + item: Item & MessageRead & MessageCompose & AppointmentRead & AppointmentCompose; /** - * Adds an event handler for a supported event - * @param eventType The event that should invoke the handler - * @param handler The function to handle the event - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the handler is added + * Gets the URL of the REST endpoint for this email account. + * + * The restUrl value can be used to make [REST API] calls to the user's mailbox. + * + * Your app must have the ReadItem permission specified in its manifest to call the restUrl member in read mode. + * + * In compose mode you must call the saveAsync method before you can use the restUrl member. Your app must have ReadWriteItem permissions to call the saveAsync method. + * + * [Api set: Mailbox 1.5] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + restUrl: string; + /** + * Adds an event handler for a supported event. + * + * Currently the only supported event type is Office.EventType.ItemChanged, which is invoked when the user selects a new item. This event is used by add-ins that implement a pinnable taskpane, and allows the add-in to refresh the taskpane UI based on the currently selected item. + * + * [Api set: Mailbox 1.5] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param eventType The event that should invoke the handler. + * @param handler The function to handle the event. The function must accept a single parameter, which is an object literal. The type property on the parameter will match the eventType parameter passed to addHandlerAsync. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ addHandlerAsync(eventType: Office.EventType, handler: (type: Office.EventType) => void, options?: any, callback?: (result: AsyncResult) => void): void; /** * Converts an item ID formatted for REST into EWS format. - * @param itemId An item ID formatted for the Outlook REST APIs - * @param restVersion A value indicating the version of the Outlook REST API used to retrieve the item ID + * + * Item IDs retrieved via a REST API (such as the Outlook Mail API or the Microsoft Graph) use a different format than the format used by Exchange Web Services (EWS). The convertToEwsId method converts a REST-formatted ID into the proper format for EWS. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + * + * @param itemId An item ID formatted for the Outlook REST APIs. + * @param restVersion A value indicating the version of the Outlook REST API used to retrieve the item ID. */ convertToEwsId(itemId: string, restVersion: Office.MailboxEnums.RestVersion): string; /** - * Gets a Date object from a dictionary containing time information - * @param timeValue A Date object + * Gets a dictionary containing time information in local client time. + * + * The dates and times used by a mail app for Outlook or Outlook Web App can use different time zones. Outlook uses the client computer time zone; Outlook Web App uses the time zone set on the Exchange Admin Center (EAC). You should handle date and time values so that the values you display on the user interface are always consistent with the time zone that the user expects. + * + * If the mail app is running in Outlook, the convertToLocalClientTime method will return a dictionary object with the values set to the client computer time zone. If the mail app is running in Outlook Web App, the convertToLocalClientTime method will return a dictionary object with the values set to the time zone specified in the EAC. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param timeValue A Date object. */ convertToLocalClientTime(timeValue: Date): LocalClientTime; /** * Converts an item ID formatted for EWS into REST format. - * @param itemId An item ID formatted for the Outlook EWS APIs - * @param restVersion A value indicating the version of the Outlook REST API that the converted ID will be used with + * + * Item IDs retrieved via EWS or via the itemId property use a different format than the format used by REST APIs (such as the [Outlook Mail API] or the [Microsoft Graph]). The convertToRestId method converts an EWS-formatted ID into the proper format for REST. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + * + * @param itemId An item ID formatted for Exchange Web Services (EWS) + * @param restVersion A value indicating the version of the Outlook REST API that the converted ID will be used with. */ convertToRestId(itemId: string, restVersion: Office.MailboxEnums.RestVersion): string; /** - * Gets a dictionary containing time information in local client time - * @param input A dictionary containing a date. The dictionary should contain the following fields: year, month, date, hours, minutes, seconds, time zone, time zone offset + * Gets a Date object from a dictionary containing time information. + * + * The convertToUtcClientTime method converts a dictionary containing a local date and time to a Date object with the correct values for the local date and time. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param input The local time value to convert. + * @returns A Date object with the time expressed in UTC. */ convertToUtcClientTime(input: LocalClientTime): Date; /** - * Displays an existing calendar appointment - * @param itemId The Exchange Web Services (EWS) identifier for an existing calendar appointment + * Displays an existing calendar appointment. + * + * The displayAppointmentForm method opens an existing calendar appointment in a new window on the desktop or in a dialog box on mobile devices. + * + * In Outlook for Mac, you can use this method to display a single appointment that is not part of a recurring series, or the master appointment of a recurring series, but you cannot display an instance of the series. This is because in Outlook for Mac, you cannot access the properties (including the item ID) of instances of a recurring series. + * + * In Outlook Web App, this method opens the specified form only if the body of the form is less than or equal to 32KB number of characters. + * + * If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message will be returned. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * @param itemId The Exchange Web Services (EWS) identifier for an existing calendar appointment. */ displayAppointmentForm(itemId: string): void; /** - * Displays an existing message - * @param itemId The Exchange Web Services (EWS) identifier for an existing message + * Displays an existing message. + * + * The displayMessageForm method opens an existing message in a new window on the desktop or in a dialog box on mobile devices. + * + * In Outlook Web App, this method opens the specified form only if the body of the form is less than or equal to 32 KB number of characters. + * + * If the specified item identifier does not identify an existing message, no message will be displayed on the client computer, and no error message will be returned. + * + * Do not use the displayMessageForm with an itemId that represents an appointment. Use the displayAppointmentForm method to display an existing appointment, and displayNewAppointmentForm to display a form to create a new appointment. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * @param itemId The Exchange Web Services (EWS) identifier for an existing message. */ displayMessageForm(itemId: string): void; /** - * Displays a form for creating a new calendar appointment - * @param parameters A dictionary of parameters describing the new appointment. + * Displays a form for creating a new calendar appointment. + * + * The displayNewAppointmentForm method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters. + * + * In Outlook Web App and OWA for Devices, this method always displays a form with an attendees field. If you do not specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button. + * + * In the Outlook rich client and Outlook RT, if you specify any attendees or resources in the requiredAttendees, optionalAttendees, or resources parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button. + * + * If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + * @param parameters A dictionary of parameters describing the new appointment. All parameters are optional. + * requiredAttendees: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the required attendees for the appointment. The array is limited to a maximum of 100 entries. + * optionalAttendees: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the optional attendees for the appointment. The array is limited to a maximum of 100 entries. + * start: A Date object specifying the start date and time of the appointment. + * end: A Date object specifying the end date and time of the appointment. + * location: A string containing the location of the appointment. The string is limited to a maximum of 255 characters. + * resources: An array of strings containing the resources required for the appointment. The array is limited to a maximum of 100 entries. + * subject: A string containing the subject of the appointment. The string is limited to a maximum of 255 characters. + * body: The body of the appointment. The body content is limited to a maximum size of 32 KB. */ - displayNewAppointmentForm(parameters?: AppointmentForm): void; + displayNewAppointmentForm(parameters: AppointmentForm): void; /** - * Displays a new message form - * WARNING: This api is not officially released, and may not work on all platforms - * @param options A dictionary containing all values to be filled in for the user in the new form + * Displays a form for creating a new message. + * + * The displayNewMessageForm method opens a form that enables the user to create a new message. If parameters are specified, the message form fields are automatically populated with the contents of the parameters. + * + * If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. + * + * [Api set: Mailbox 1.6] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + * + * @param parameters A dictionary containing all values to be filled in for the user in the new form. All parameters are optional. + * toRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the To line. The array is limited to a maximum of 100 entries. + * ccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Cc line. The array is limited to a maximum of 100 entries. + * bccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Bcc line. The array is limited to a maximum of 100 entries. + * subject: A string containing the subject of the message. The string is limited to a maximum of 255 characters. + * htmlBody: The HTML body of the message. The body content is limited to a maximum size of 32 KB. + * attachments: An array of JSON objects that are either file or item attachments. + * attachments.type: Indicates the type of attachment. Must be file for a file attachment or item for an item attachment. + * attachments.name: A string that contains the name of the attachment, up to 255 characters in length. + * attachments.url: Only used if type is set to file. The URI of the location for the file. + * attachments.isInline: Only used if type is set to file. If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list. + * attachments.itemId: Only used if type is set to item. The EWS item id of the attachment. This is a string up to 100 characters. */ - displayNewMessageForm(options?: any): void; + displayNewMessageForm(parameters: any): void; /** - * Gets a string that contains a token used to get an attachment or item from an Exchange Server - * @param callback The optional method to call when the string is inserted - * @param userContext Optional variable for any state data that is passed to the asynchronous method + * Gets a string that contains a token used to call REST APIs or Exchange Web Services. + * + * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes. + * + * *REST Tokens* + * + * When a REST token is requested (options.isRest = true), the resulting token will not work to authenticate Exchange Web Services calls. The token will be limited in scope to read-only access to the current item and its attachments, unless the add-in has specified the ReadWriteMailbox permission in its manifest. If the ReadWriteMailbox permission is specified, the resulting token will grant read/write access to mail, calendar, and contacts, including the ability to send mail. + * + * The add-in should use the restUrl property to determine the correct URL to use when making REST API calls. + * + * *EWS Tokens* + * + * When an EWS token is requested (options.isRest = false), the resulting token will not work to authenticate REST API calls. The token will be limited in scope to accessing the current item. + * + * The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls. + * + * [Api set: Mailbox 1.5] + * + * @remarks + * + * [!NOTE] It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose and read + * + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. */ - getCallbackTokenAsync(callback?: (result: AsyncResult) => void, userContext?: any): void; + getCallbackTokenAsync(callback: (result: AsyncResult) => void): void; /** - * Gets a token identifying the user and the app for Office - * @param callback The optional method to call when the string is inserted - * @param userContext Optional variable for any state data that is passed to the asynchronous method + * Gets a string that contains a token used to call REST APIs or Exchange Web Services. + * + * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes. + * + * *REST Tokens* + * + * When a REST token is requested (options.isRest = true), the resulting token will not work to authenticate Exchange Web Services calls. The token will be limited in scope to read-only access to the current item and its attachments, unless the add-in has specified the ReadWriteMailbox permission in its manifest. If the ReadWriteMailbox permission is specified, the resulting token will grant read/write access to mail, calendar, and contacts, including the ability to send mail. + * + * The add-in should use the restUrl property to determine the correct URL to use when making REST API calls. + * + * *EWS Tokens* + * + * When an EWS token is requested (options.isRest = false), the resulting token will not work to authenticate REST API calls. The token will be limited in scope to accessing the current item. + * + * The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls. + * + * [Api set: Mailbox 1.5] + * + * @remarks + * + * [!NOTE] It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose and read + * + * @param options An object literal that contains one or more of the following properties. + * isRest: Determines if the token provided will be used for the Outlook REST APIs or Exchange Web Services. Default value is false. + * asyncContext: Any state data that is passed to the asynchronous method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. */ - getUserIdentityTokenAsync(callback?: (result: AsyncResult) => void, userContext?: any): void; + getCallbackTokenAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; /** - * Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user’s mailbox - * @param data The EWS request - * @param callback The optional method to call when the string is inserted - * @param userContext Optional variable for any state data that is passed to the asynchronous method + * Gets a string that contains a token used to get an attachment or item from an Exchange Server. + * + * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes. + * + * You can pass the token and an attachment identifier or item identifier to a third-party system. The third-party system uses the token as a bearer authorization token to call the Exchange Web Services (EWS) GetAttachment or GetItem operation to return an attachment or item. For example, you can create a remote service to get attachments from the selected item. + * + * Your app must have the ReadItem permission specified in its manifest to call the getCallbackTokenAsync method in read mode. + * + * In compose mode you must call the saveAsync method to get an item identifier to pass to the getCallbackTokenAsync method. Your app must have ReadWriteItem permissions to call the saveAsync method. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose and read + * + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. + * @param userContext Optional. Any state data that is passed to the asynchronous method. */ - makeEwsRequestAsync(data: any, callback?: (result: AsyncResult) => void, userContext?: any): void; - } - export interface Message extends Item { - conversationId: string; - } - export interface MessageCompose extends Message, ItemCompose { - bcc: Recipients; - cc: Recipients; - to: Recipients; - } - export interface MessageRead extends Message, ItemRead { - cc: Array; - from: EmailAddressDetails; - internetMessageId: string; - sender: EmailAddressDetails; - to: Array; + getCallbackTokenAsync(callback: (result: AsyncResult) => void, userContext?: any): void; + /** + * Gets a token identifying the user and the Office Add-in. + * + * The getUserIdentityTokenAsync method returns a token that you can use to identify and [authenticate the add-in and user with a third-party system]. + * + * The token is provided as a string in the asyncResult.value property. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose and read + * + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param userContext Optional. Any state data that is passed to the asynchronous method.| + */ + getUserIdentityTokenAsync(callback: (result: AsyncResult) => void, userContext?: any): void; + /** + * Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user’s mailbox. + * + * + * In these cases, add-ins should use REST APIs to access the user's mailbox instead. + * + * The makeEwsRequestAsync method sends an EWS request on behalf of the add-in to Exchange. + * + * You cannot request Folder Associated Items with the makeEwsRequestAsync method. + * + * The XML request must specify UTF-8 encoding. + * + * Your add-in must have the ReadWriteMailbox permission to use the makeEwsRequestAsync method. For information about using the ReadWriteMailbox permission and the EWS operations that you can call with the makeEwsRequestAsync method, see Specify permissions for mail add-in access to the user's mailbox. + * + * The XML result of the EWS call is provided as a string in the asyncResult.value property. If the result exceeds 1 MB in size, an error message is returned instead. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * + * [!NOTE] This method is not supported in the following scenarios. - In Outlook for iOS or Outlook for Android - When the add-in is loaded in a Gmail mailbox + * + * [!NOTE] The server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests. + * + * *Version differences* + * + * When you use the makeEwsRequestAsync method in mail apps running in Outlook versions earlier than version 15.0.4535.1004, you should set the encoding value to ISO-8859-1. + * + * + * + * You do not need to set the encoding value when your mail app is running in Outlook on the web. You can determine whether your mail app is running in Outlook or Outlook on the web by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property. + * + * Minimum permission level: ReadWriteMailbox + * Applicable Outlook mode: Compose and read + * + * @param data The EWS request. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param userContext Optional. Any state data that is passed to the asynchronous method. + */ + makeEwsRequestAsync(data: any, callback: (result: AsyncResult) => void, userContext?: any): void; } + + /** + * Represents a suggested meeting found in an item. Read mode only. + * + * The list of meetings suggested in an email message is returned in the meetingSuggestions property of the Entities object that is returned when the getEntities or getEntitiesByType method is called on the active item. + * + * The start and end values are string representations of a Date object that contains the date and time at which the suggested meeting is to begin and end. The values are in the default time zone specified for the current user. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ export interface MeetingSuggestion { + /** + * Gets the attendees for a suggested meeting. + */ attendees: Array; + /** + * Gets the date and time that a suggested meeting is to end. + */ end: string; + /** + * Gets the location of a suggested meeting. + */ location: string; + /** + * Gets a string that was identified as a meeting suggestion. + */ meetingstring: string; + /** + * Gets the date and time that a suggested meeting is to begin. + */ start: string; + /** + * Gets the subject of a suggested meeting. + */ subject: string; } + /** + * An array of NotificationMessageDetails objects are returned by the NotificationMessages.getAllAsync method. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ export interface NotificationMessageDetails { + /** + * The identifier for the notification message. + */ key?: string; + /** + * The type of notification message. + */ type: Office.MailboxEnums.ItemNotificationMessageType; + /** + * The resource identifier of the icon used for the message. Only applicable when type is InformationalMessage. + */ icon?: string; + /** + * This is the text of the message. Maximum length is 150 characters. + */ message: string; + /** + * If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. Only applicable when type is InformationalMessage. + */ persistent?: Boolean; } + /** + * The NotificationMessages object is returned as the notificationMessages property of an item. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ export interface NotificationMessages { /** - * Adds a notification to an item - * @param key A developer-specified key used to refrence this notification message. Developers can use it to modify this message later. - * @param JSONmessage A JSON object that contains the notification message to be added to this item + * Adds a notification to an item. + * + * There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error. + * + * @param key 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. + * @param JSONmessage A JSON object that contains the notification message to be added to the item. It consists of the following properties. + * type: Specifies the Office.MailboxEnums.ItemNotificationMessageType of message. If type is ProgressIndicator or ErrorMessage, an icon is automatically supplied and the message is not persistent. Therefore the icon and persistent properties are not valid for these types of messages. Including them will result in an ArgumentException. If type is ProgressIndicator, the developer should remove or replace the progress indicator when the action is complete. + * icon: A reference to an icon that is defined in the manifest in the Resources section. It appears in the infobar area. It is only applicable if the type is InformationalMessage. Specifying this parameter for an unsupported type results in an exception. + * message: The text of the notification message. Maximum length is 150 characters. If the developer passes in a longer string, an ArgumentOutOfRange exception is thrown. + * persistent: Only applicable when type is InformationalMessage. If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. For error notifications, the message persists until the user sees it once. Specifying this parameter for an unsupported type throws an exception. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read */ - addAsync(key: string, JSONmessage: NotificationMessageDetails): void; - /** - * Adds a notification to an item - * @param key A developer-specified key used to refrence this notification message. Developers can use it to modify this message later. - * @param JSONmessage A JSON object that contains the notification message to be added to this item - * @param options Any optional parameters or state data passed to the method - */ - addAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions): void; - /** - * Adds a notification to an item - * @param key A developer-specified key used to refrence this notification message. Developers can use it to modify this message later. - * @param JSONmessage A JSON object that contains the notification message to be added to this item - * @param callback The optional callback method - */ - addAsync(key: string, JSONmessage: NotificationMessageDetails, callback: (result: AsyncResult) => void): void; - /** - * Adds a notification to an item - * @param key A developer-specified key used to refrence this notification message. Developers can use it to modify this message later. - * @param JSONmessage A JSON object that contains the notification message to be added to this item - * @param options Any optional parameters or state data passed to the method - * @param callback The optional callback method - */ - addAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + addAsync(key: string, JSONmessage: NotificationMessageDetails, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Returns all keys and messages for an item. - * @param callback The optional callback method + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ - getAllAsync(callback: (result: AsyncResult) => void): void; - /** - * Returns all keys and messages for an item. - * @param options Any optional parameters or state data passed to the method - * @param callback The optional callback method - */ - getAllAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + getAllAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Removes a notification message for an item. - * @param key The key for the notification message to remove + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to remove. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ - removeAsync(key: string): void; - /** - * Removes a notification message for an item. - * @param key The key for the notification message to remove - * @param options Any optional parameters or state data passed to the method - */ - removeAsync(key: string, options: AsyncContextOptions): void; - /** - * Removes a notification message for an item. - * @param key The key for the notification message to remove - * @param callback The optional callback method - */ - removeAsync(key: string, callback: (result: AsyncResult) => void): void; - /** - * Removes a notification message for an item. - * @param key The key for the notification message to remove - * @param options Any optional parameters or state data passed to the method - * @param callback The optional callback method - */ - removeAsync(key: string, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + removeAsync(key: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** - * Replaces a notification message that has a given key with another message - * @param key The key for the notification message to replace. - * @param JSONmessage A JSON object that contains the new notification message to replace the existing message + * 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. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to replace. It can't be longer than 32 characters. + * @param JSONmessage A JSON object that contains the new notification message to replace the existing message. It consists of the following properties. + * type: Specifies the Office.MailboxEnums.ItemNotificationMessageType of message. If type is ProgressIndicator or ErrorMessage, an icon is automatically supplied and the message is not persistent. Therefore the icon and persistent properties are not valid for these types of messages. Including them will result in an ArgumentException. If type is ProgressIndicator, the developer should remove or replace the progress indicator when the action is complete. + * icon: A reference to an icon that is defined in the manifest in the Resources section. It appears in the infobar area. It is only applicable if the type is InformationalMessage. Specifying this parameter for an unsupported type results in an exception. + * message: The text of the notification message. Maximum length is 150 characters. If the developer passes in a longer string, an ArgumentOutOfRange exception is thrown. + * persistent: Only applicable when type is InformationalMessage. If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. For error notifications, the message persists until the user sees it once. Specifying this parameter for an unsupported type throws an exception. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ - replaceAsync(key: string, JSONmessage: NotificationMessageDetails): void; - /** - * Replaces a notification message that has a given key with another message - * @param key The key for the notification message to replace. - * @param JSONmessage A JSON object that contains the new notification message to replace the existing message - * @param options Any optional parameters or state data passed to the method - */ - replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions): void; - /** - * Replaces a notification message that has a given key with another message - * @param key The key for the notification message to replace. - * @param JSONmessage A JSON object that contains the new notification message to replace the existing message - * @param callback The optional callback method - */ - replaceAsync(key: string, JSONmessage: NotificationMessageDetails, callback: (result: AsyncResult) => void): void; - /** - * Replaces a notification message that has a given key with another message - * @param key The key for the notification message to replace. - * @param JSONmessage A JSON object that contains the new notification message to replace the existing message - * @param options Any optional parameters or state data passed to the method - * @param callback The optional callback method - */ - replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; } + /** + * Represents a phone number identified in an item. Read mode only. + * + * An array of PhoneNumber objects containing the phone numbers found in an email message is returned in the phoneNumbers property of the Entities object that is returned when you call the getEntities method on the selected item. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ export interface PhoneNumber { + /** + * Gets a string containing a phone number. This string contains only the digits of the telephone number and excludes characters like parentheses and hyphens, if they exist in the original item. + */ phoneString: string; + /** + * Gets the text that was identified in an item as a phone number. + */ originalPhoneString: string; + /** + * Gets a string that identifies the type of phone number: Home, Work, Mobile, Unspecified. + */ type: string; } + /** + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + */ export interface Recipients { /** - * Begins an asynchronous request to add a recipient list to an appointment or message - * @param recipients The recipients to add to the recipients list + * Adds a recipient list to the existing recipients for an appointment or message. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If adding the recipients fails, the asyncResult.error property will contain an error code. */ - addAsync(recipients: Array): void; + addAsync(recipients: Array, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** - * Begins an asynchronous request to add a recipient list to an appointment or message - * @param recipients The recipients to add to the recipients list - * @param options Any optional parameters or state data passed to the method - */ - addAsync(recipients: Array, options: AsyncContextOptions): void; - /** - * Begins an asynchronous request to add a recipient list to an appointment or message - * @param recipients The recipients to add to the recipients list - * @param callback The optional method to call when the string is inserted - */ - addAsync(recipients: Array, callback: (result: AsyncResult) => void): void; - /** - * Begins an asynchronous request to add a recipient list to an appointment or message - * @param recipients The recipients to add to the recipients list - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted - */ - addAsync(recipients: Array, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - /** - * Begins an asynchronous request to get the recipient list for an appointment or message - * @param callback The optional method to call when the string is inserted + * Gets a recipient list for an appointment or message. + * + * When the call completes, the asyncResult.value property will contain an array of EmailAddressDetails objects. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getAsync(callback: (result: AsyncResult) => void): void; /** - * Begins an asynchronous request to get the recipient list for an appointment or message - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted + * Gets a recipient list for an appointment or message. + * + * When the call completes, the asyncResult.value property will contain an array of EmailAddressDetails objects. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * + * @param options 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 method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; /** - * Begins an asynchronous request to set the recipient list for an appointment or message - * @param recipients The recipients to add to the recipients list + * Sets a recipient list for an appointment or message. + * + * The setAsync method overwrites the current recipient list. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + * @param options Optional. 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 method. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the recipients fails the asyncResult.error property will contain a code that indicates any error that occurred while adding the data. */ - setAsync(recipients: Array): void; - /** - * Begins an asynchronous request to set the recipient list for an appointment or message - * @param recipients The recipients to add to the recipients list - * @param options Any optional parameters or state data passed to the method - */ - setAsync(recipients: Array, options: AsyncContextOptions): void; - /** - * Begins an asynchronous request to set the recipient list for an appointment or message - * @param recipients The recipients to add to the recipients list - * @param callback The optional method to call when the string is inserted - */ - setAsync(recipients: Array, callback: (result: AsyncResult) => void): void; - /** - * Begins an asynchronous request to set the recipient list for an appointment or message - * @param recipients The recipients to add to the recipients list - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted - */ - setAsync(recipients: Array, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + setAsync(recipients: Array, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; } export interface ReplyFormAttachment { @@ -5203,114 +6855,284 @@ declare namespace Office { attachments?: Array; callback?: (result: AsyncResult) => void; } + /** + * The settings created by using the methods of the RoamingSettings object are saved per add-in and per user. That is, they are available only to the add-in that created them, and only from the user's mail box in which they are saved. + * + * While the Outlook Add-in API limits access to these settings to only the add-in that created them, these settings should not be considered secure storage. They can be accessed by Exchange Web Services or Extended MAPI. They should not be used to store sensitive information such as user credentials or security tokens. + * + * The name of a setting is a String, while the value can be a String, Number, Boolean, null, Object, or Array. + * + * The RoamingSettings object is accessible via the roamingSettings property in the Office.context namespace. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * [!IMPORTANT]: The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded. For task panes, this means that it is only initialized when the task pane first opens. If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has persisted changes. The persisted changes will not be available until the task pane is closed and reopened. + * + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + */ export interface RoamingSettings { /** - * Retrieves the specified setting - * @param name The case-sensitive name of the setting to retrieve + * Retrieves the specified setting. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + * + * @param name The case-sensitive name of the setting to retrieve. + * @returns Type: String | Number | Boolean | Object | Array */ get(name: string): any; /** * Removes the specified setting - * @param name The case-sensitive name of the setting to remove + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + * + * @param name The case-sensitive name of the setting to remove. */ remove(name: string): void; /** - * Saves the settings - * @param callback A function that is invoked when the callback returns, whose only parameter is of type AsyncResult + * Saves the settings. + * + * Any settings previously saved by an add-in are loaded when it is initialized, so during the lifetime of the session you can just use the set and get methods to work with the in-memory copy of the settings property bag. When you want to persist the settings so that they are available the next time the add-in is used, use the saveAsync method. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + * + * @param callback Optional? When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ saveAsync(callback?: (result: AsyncResult) => void): void; /** - * Sets or creates the specified setting - * @param name The case-sensitive name of the setting to set or create - * @param value Specifies the value to be stored + * Sets or creates the specified setting. + * + * The set method creates a new setting of the specified name if it does not already exist, or sets an existing setting of the specified name. The value is stored in the document as the serialized JSON representation of its data type. + * + * A maximum of 2MB is available for the settings of each add-in, and each individual setting is limited to 32KB. + * + * Any changes made to settings using the set function will not be saved to the server until the saveAsync function is called. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: Restricted + * Applicable Outlook mode: Compose or read + * + * @param name The case-sensitive name of the setting to set or create. + * @param value Specifies the value to be stored. */ set(name: string, value: any): void; } + + /** + * Provides methods to get and set the subject of an appointment or message in an Outlook add-in. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + */ export interface Subject { /** - * Begins an asynchronous request to get the subject of an appointment or message - * @param callback The optional method to call when the string is inserted + * Gets the subject of an appointment or message. + * The getAsync method starts an asynchronous call to the Exchange server to get the subject of an appointment or message. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getAsync(callback: (result: AsyncResult) => void): void; /** - * Begins an asynchronous request to get the subject of an appointment or message - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted + * Gets the subject of an appointment or message. + * + * The getAsync method starts an asynchronous call to the Exchange server to get the subject of an appointment or message. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * + * @param options 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 method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; /** - * Begins an asynchronous call to set the subject of an appointment or message - * @param data The subject of the appointment. The string is limited to 255 characters + * Sets the subject of an appointment or message. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the subject of an appointment or message. Setting the subject overwrites the current subject, but leaves any prefixes, such as "Fwd:" or "Re:" in place. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The subject parameter is longer than 255 characters. + * + * @param subject The subject of the appointment or message. The string is limited to 255 characters. + * @param options 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 method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the subject fails, the asyncResult.error property will contain an error code. */ - setAsync(data: string): void; - /** - * Begins an asynchronous call to set the subject of an appointment or message - * @param data The subject of the appointment. The string is limited to 255 characters - * @param options Any optional parameters or state data passed to the method - */ - setAsync(data: string, options: AsyncContextOptions): void; - /** - * Begins an asynchronous call to set the subject of an appointment or message - * @param data The subject of the appointment. The string is limited to 255 characters - * @param callback The optional method to call when the string is inserted - */ - setAsync(data: string, callback: (result: AsyncResult) => void): void; - /** - * Begins an asynchronous call to set the subject of an appointment or message - * @param data The subject of the appointment. The string is limited to 255 characters - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted - */ - setAsync(data: string, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + setAsync(subject: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; } + /** + * Represents a suggested task identified in an item. Read mode only. + * + * The list of tasks suggested in an email message is returned in the taskSuggestions property of the [Entities]Entities object that is returned when the getEntities or getEntitiesByType method is called on the active item. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Read + */ export interface TaskSuggestion { + /** + * Gets the users that should be assigned a suggested task. + */ assignees: Array; + /** + * Gets the text of an item that was identified as a task suggestion. + */ taskString: string; } + /** + * The Time object is returned as the start or end property of an appointment in compose mode. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + */ export interface Time { /** - * Begins an asynchronous request to get the start or end time - * @param callback The optional method to call when the string is inserted + * Gets the start or end time of an appointment. + * + * The date and time is provided as a Date object in the asyncResult.value property. The value is in Coordinated Universal Time (UTC). You can convert the UTC time to the local client time by using the convertToLocalClientTime method. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getAsync(callback: (result: AsyncResult) => void): void; /** - * Begins an asynchronous request to get the start or end time - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted + * Gets the start or end time of an appointment. + * + * The date and time is provided as a Date object in the asyncResult.value property. The value is in Coordinated Universal Time (UTC). You can convert the UTC time to the local client time by using the convertToLocalClientTime method. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose + * + * @param options 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 method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; /** - * Begins an asynchronous request to set the start or end time - * @param dateTime A date-time object in Coordinated Universal Time (UTC) + * Sets the start or end time of an appointment. + * + * If the setAsync method is called on the start property, the end property will be adjusted to maintain the duration of the appointment as previously set. If the setAsync method is called on the end property, the duration of the appointment will be extended to the new end time. + * + * The time must be in UTC; you can get the correct UTC time by using the convertToUtcClientTime method. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: InvalidEndTime - The appointment end time is before the appointment start time. + * + * @param dateTime A date-time object in Coordinated Universal Time (UTC). + * @param options 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 method. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the date and time fails, the asyncResult.error property will contain an error code. */ - setAsync(dateTime: Date): void; - /** - * Begins an asynchronous request to set the start or end time - * @param dateTime A date-time object in Coordinated Universal Time (UTC) - * @param options Any optional parameters or state data passed to the method - */ - setAsync(dateTime: Date, options: AsyncContextOptions): void; - /** - * Begins an asynchronous request to set the start or end time - * @param dateTime A date-time object in Coordinated Universal Time (UTC) - * @param callback The optional method to call when the string is inserted - */ - setAsync(dateTime: Date, callback: (result: AsyncResult) => void): void; - /** - * Begins an asynchronous request to set the start or end time - * @param dateTime A date-time object in Coordinated Universal Time (UTC) - * @param options Any optional parameters or state data passed to the method - * @param callback The optional method to call when the string is inserted - */ - setAsync(dateTime: Date, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + setAsync(dateTime: Date, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; } + /** + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ export interface UserProfile { + /** + * Gets the account type of the user associated with the mailbox. The possible values are listed in the following table. + * + * [Api set: Mailbox 1.6] + * + * @remarks + * [!NOTE] This member is currently only supported in Outlook 2016 for Mac, build 16.9.1212 and greater. + * + * |Value |Description | + * |---------|--------------| + * |enterprise |The mailbox is on an on-premises Exchange server.| + * |gmail |The mailbox is associated with a Gmail account.| + * |office365 |The mailbox is associated with an Office 365 work or school account.| + * |outlookCom |The mailbox is associated with a personal Outlook.com account.| + * + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ + accountType: string; + /** + * Gets the user's display name. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ displayName: string; + /** + * Gets the user's display name. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ emailAddress: string; + /** + * Gets the user's SMTP email address. + * + * [Api set: Mailbox 1.0] + * + * @remarks + * Minimum permission level: ReadItem + * Applicable Outlook mode: Compose or read + */ timeZone: string; } } From bd72b87b201aea63a782dd20408bdec5fdc58030 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Tue, 29 May 2018 15:40:41 -0700 Subject: [PATCH 2/7] Adding class and method descriptions for Exchange API - hyperlink fix --- types/office-js/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index 3f3d653fca..c52852d6fd 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -4705,7 +4705,7 @@ declare namespace Office { urls: Array; } /** - * The Office.context namespace provides shared interfaces that are used by add-ins in all of the Office apps. This listing documents only those interfaces that are used by Outlook add-ins. For a full listing of the Office.context namespace, see the (https://dev.office.com/reference/add-ins/shared/office.context.htm). + * The Office.context namespace provides shared interfaces that are used by add-ins in all of the Office apps. This listing documents only those interfaces that are used by Outlook add-ins. For a full listing of the Office.context namespace, see the [Office.context reference in the Shared API]. * * [Api set: Mailbox 1.0] * From 742114ea42e64a4d095f3b3f21564d12a1de9355 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Tue, 29 May 2018 15:48:35 -0700 Subject: [PATCH 3/7] Adding class and method descriptions for Exchange API - note fixing --- types/office-js/index.d.ts | 75 ++++++++++++++++++-------------------- 1 file changed, 36 insertions(+), 39 deletions(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index c52852d6fd..b360bdf381 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -1724,8 +1724,7 @@ declare namespace Office { * @remarks * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. * - * > [!IMPORTANT] - * > Your add-in's code can register a handler for the settingsChanged event when the add-in is running with any Excel client, but the event will fire only when the add-in is loaded with a spreadsheet that is opened in Excel Online, and more than one user is editing the spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios. + * Important: Your add-in's code can register a handler for the settingsChanged event when the add-in is running with any Excel client, but the event will fire only when the add-in is loaded with a spreadsheet that is opened in Excel Online, and more than one user is editing the spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios. * * Hosts: Excel * @@ -1788,8 +1787,7 @@ declare namespace Office { * @remarks * null is a valid value for a setting. Therefore, assigning null to the setting will not remove it from the settings property bag. * - * > [!IMPORTANT] - * > Be aware that the Settings.remove method affects only the in-memory copy of the settings property bag. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method. + * Important: Be aware that the Settings.remove method affects only the in-memory copy of the settings property bag. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method. * Hosts: Access, Excel, PowerPoint, Word * * Available in Requirement set: Settings @@ -1822,9 +1820,9 @@ declare namespace Office { * @remarks * Any settings previously saved by an add-in are loaded when it is initialized, so during the lifetime of the session you can just use the set and get methods to work with the in-memory copy of the settings property bag. When you want to persist the settings so that they are available the next time the add-in is used, use the saveAsync method. * - * > [!NOTE] - * > The saveAsync method persists the in-memory settings property bag into the document file; however, the changes to the document file itself are saved only when the user (or AutoRecover setting) saves the document to the file system. - * > The refreshAsync method is only useful in coauthoring scenarios (which are only supported in Word) when other instances of the same add-in might change the settings and those changes should be made available to all instances. + * Note: + * The saveAsync method persists the in-memory settings property bag into the document file; however, the changes to the document file itself are saved only when the user (or AutoRecover setting) saves the document to the file system. + * The refreshAsync method is only useful in coauthoring scenarios (which are only supported in Word) when other instances of the same add-in might change the settings and those changes should be made available to all instances. * * Hosts: Access, Excel, PowerPoint, Word * @param options Syntax example: {overwriteIfStale:false} @@ -1848,8 +1846,7 @@ declare namespace Office { * @remarks * The set method creates a new setting of the specified name if it does not already exist, or sets an existing setting of the specified name in the in-memory copy of the settings property bag. After you call the Settings.saveAsync method, the value is stored in the document as the serialized JSON representation of its data type. A maximum of 2MB is available for the settings of each add-in. * - * > [!IMPORTANT] - * > Be aware that the Settings.set method affects only the in-memory copy of the settings property bag. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document. + * Important: Be aware that the Settings.set method affects only the in-memory copy of the settings property bag. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document. * * Hosts: Access, Excel, PowerPoint, Word * @@ -5370,7 +5367,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This member is not supported in Outlook for iOS or Outlook for Android. + * Note: This member is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5507,7 +5504,7 @@ declare namespace Office { * [Api set: Mailbox 1.3] * * @remarks - * [!NOTE] In Outlook on the web, if the item is an appointment and it has previously been saved using saveAsync, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved. + * Note: In Outlook on the web, if the item is an appointment and it has previously been saved using saveAsync, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved. * * Minimum permission level: Restricted * Applicable Outlook mode: Compose @@ -5520,7 +5517,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is only supported by Outlook 2016 for Windows (Click-to-Run versions greater than 16.0.8413.1000) and Outlook on the web for Office 365. + * Note: This method is only supported by Outlook 2016 for Windows (Click-to-Run versions greater than 16.0.8413.1000) and Outlook on the web for Office 365. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5604,9 +5601,9 @@ declare namespace Office { * [Api set: Mailbox 1.3] * * @remarks - * [!NOTE] If your add-in calls saveAsync on an item in compose mode in order to get an itemId to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the itemId will return an error. + * Note: If your add-in calls saveAsync on an item in compose mode in order to get an itemId to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the itemId will return an error. * - * [!NOTE] The following clients have different behavior for saveAsync on appointments in compose mode: + * Note: The following clients have different behavior for saveAsync on appointments in compose mode: * * - Mac Outlook does not support saveAsync on a meeting in compose mode. Calling saveAsync on a meeting in Mac Outlook will return an error. * @@ -5668,7 +5665,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] Certain types of files are blocked by Outlook due to potential security issues and are therefore not returned. For more information, see [Blocked attachments in Outlook]. + * Note: Certain types of files are blocked by Outlook due to potential security issues and are therefore not returned. For more information, see [Blocked attachments in Outlook]. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5704,7 +5701,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * + * Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5757,7 +5754,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5787,7 +5784,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5811,7 +5808,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5838,7 +5835,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: Restricted * Applicable Outlook mode: Read @@ -5854,7 +5851,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5877,7 +5874,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5897,7 +5894,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5912,7 +5909,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -5934,7 +5931,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -6038,7 +6035,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] The recipientType property of the EmailAddressDetails object in the from property is undefined. + * Note: The recipientType property of the EmailAddressDetails object in the from property is undefined. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -6064,7 +6061,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] The recipientType property of the EmailAddressDetails object in the sender property is undefined. + * Note: The recipientType property of the EmailAddressDetails object in the sender property is undefined. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -6211,7 +6208,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] This member is not supported in Outlook for iOS or Outlook for Android. + * Note: This member is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Compose or read @@ -6267,7 +6264,7 @@ declare namespace Office { * [Api set: Mailbox 1.3] * * @remarks - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: Restricted * Applicable Outlook mode: Compose or read @@ -6301,7 +6298,7 @@ declare namespace Office { * [Api set: Mailbox 1.3] * * @remarks - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: Restricted * Applicable Outlook mode: Compose or read @@ -6340,7 +6337,7 @@ declare namespace Office { * [Api set: Mailbox 1.0] * * @remarks - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Compose or read @@ -6361,7 +6358,7 @@ declare namespace Office { * [Api set: Mailbox 1.0] * * @remarks - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Compose or read @@ -6382,7 +6379,7 @@ declare namespace Office { * [Api set: Mailbox 1.0] * * @remarks - * [!NOTE] This method is not supported in Outlook for iOS or Outlook for Android. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * Applicable Outlook mode: Read @@ -6447,7 +6444,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. + * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. * * Minimum permission level: ReadItem * Applicable Outlook mode: Compose and read @@ -6476,7 +6473,7 @@ declare namespace Office { * * @remarks * - * [!NOTE] It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. + * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. * * Minimum permission level: ReadItem * Applicable Outlook mode: Compose and read @@ -6547,9 +6544,9 @@ declare namespace Office { * * @remarks * - * [!NOTE] This method is not supported in the following scenarios. - In Outlook for iOS or Outlook for Android - When the add-in is loaded in a Gmail mailbox + * Note: This method is not supported in the following scenarios. - In Outlook for iOS or Outlook for Android - When the add-in is loaded in a Gmail mailbox * - * [!NOTE] The server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests. + * Note: The server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests. * * *Version differences* * @@ -6867,7 +6864,7 @@ declare namespace Office { * [Api set: Mailbox 1.0] * * @remarks - * [!IMPORTANT]: The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded. For task panes, this means that it is only initialized when the task pane first opens. If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has persisted changes. The persisted changes will not be available until the task pane is closed and reopened. + * Important: The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded. For task panes, this means that it is only initialized when the task pane first opens. If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has persisted changes. The persisted changes will not be available until the task pane is closed and reopened. * * Minimum permission level: Restricted * Applicable Outlook mode: Compose or read @@ -7091,7 +7088,7 @@ declare namespace Office { * [Api set: Mailbox 1.6] * * @remarks - * [!NOTE] This member is currently only supported in Outlook 2016 for Mac, build 16.9.1212 and greater. + * Note: This member is currently only supported in Outlook 2016 for Mac, build 16.9.1212 and greater. * * |Value |Description | * |---------|--------------| From 524cd8423952372d96a54a87a1a6a7570cee88a3 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Tue, 29 May 2018 17:02:25 -0700 Subject: [PATCH 4/7] Outlook documentation migration - spacing --- types/office-js/index.d.ts | 148 ++++++++++++++++++++++++++++++++++++- 1 file changed, 147 insertions(+), 1 deletion(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index b360bdf381..76ef91c769 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -4526,6 +4526,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ export interface AttachmentDetails { @@ -4561,6 +4562,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ export interface Body { @@ -4575,6 +4577,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param coercionType The format for the returned body. @@ -4591,6 +4594,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose * * @param options Optional. An object literal that contains one or more of the following properties. @@ -4630,8 +4634,11 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. * * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. @@ -4652,8 +4659,11 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. * * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. @@ -4673,6 +4683,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Read */ export interface Contact { @@ -4736,6 +4747,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read */ mailbox: Mailbox; @@ -4768,6 +4780,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read */ roamingSettings: RoamingSettings; @@ -4781,6 +4794,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ export interface CustomProperties { @@ -4793,6 +4807,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ get(name: string): any; @@ -4807,6 +4822,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param name The name of the property to be set. @@ -4823,6 +4839,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ remove(name: string): void; @@ -4840,6 +4857,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ saveAsync(callback?: (result: AsyncResult) => void, asyncContext?: any): void; @@ -4851,6 +4869,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ export interface Diagnostics { @@ -4863,6 +4882,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ hostName: string; @@ -4875,6 +4895,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ hostVersion: string; @@ -4897,6 +4918,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ OWAView: string; @@ -4908,6 +4930,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ export interface EmailAddressDetails { @@ -4935,6 +4958,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ export interface EmailUser { @@ -4966,6 +4990,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ export interface Entities { @@ -5023,6 +5048,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ end: Time; @@ -5042,6 +5068,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ location: Location; @@ -5061,6 +5088,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ optionalAttendees: Recipients; @@ -5080,6 +5108,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ requiredAttendees: Recipients; @@ -5103,6 +5132,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ start: Time; @@ -5125,6 +5155,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ location: string; @@ -5144,6 +5175,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ optionalAttendees: Array; @@ -5155,6 +5187,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ organizer: EmailAddressDetails; @@ -5174,6 +5207,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ requiredAttendees: Array; @@ -5197,6 +5231,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ start: Date; @@ -5222,6 +5257,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ end: Date; @@ -5260,6 +5296,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ optionalAttendees: Array | Array; @@ -5279,6 +5316,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ requiredAttendees: Array | Array; @@ -5302,6 +5340,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ start: Date; @@ -5323,6 +5362,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ subject: string; @@ -5335,6 +5375,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read */ export interface Item { @@ -5346,6 +5387,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ body: Body; @@ -5357,6 +5399,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ dateTimeCreated: Date; @@ -5370,6 +5413,7 @@ declare namespace Office { * Note: This member is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ dateTimeModifed: Date; @@ -5383,6 +5427,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ itemType: Office.MailboxEnums.ItemType; @@ -5394,6 +5439,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ notificationMessages: NotificationMessages; @@ -5409,6 +5455,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. @@ -5435,6 +5482,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ subject: Subject; @@ -5449,6 +5497,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose * * Errors: @@ -5480,6 +5529,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose * * Errors: @@ -5507,6 +5557,7 @@ declare namespace Office { * Note: In Outlook on the web, if the item is an appointment and it has previously been saved using saveAsync, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved. * * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose */ close(): void; @@ -5520,6 +5571,7 @@ declare namespace Office { * Note: This method is only supported by Outlook 2016 for Windows (Click-to-Run versions greater than 16.0.8413.1000) and Outlook on the web for Office 365. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param options Optional. An object literal that contains one or more of the following properties. @@ -5542,6 +5594,7 @@ declare namespace Office { * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. * * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose * * @param coercionType Requests a format for the data. If Text, the method returns the plain text as a string , removing any HTML tags present. If HTML, the method returns the selected text, whether it is plaintext or HTML. @@ -5563,6 +5616,7 @@ declare namespace Office { * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. * * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose * * @param coercionType Requests a format for the data. If Text, the method returns the plain text as a string , removing any HTML tags present. If HTML, the method returns the selected text, whether it is plaintext or HTML. @@ -5581,7 +5635,9 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: InvalidAttachmentId - The attachment identifier does not exist. * * @param attachmentIndex The identifier of the attachment to remove. The maximum length of the string is 100 characters. @@ -5590,7 +5646,7 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ removeAttachmentAsync(attachmentIndex: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; - /** + /** * Asynchronously saves an item. * * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. @@ -5610,7 +5666,9 @@ declare namespace Office { * - Outlook on the web always sends an invitation or update when saveAsync is called on an appointment in compose mode. * * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: InvalidAttachmentId - The attachment identifier does not exist. * * @param options Optional. An object literal that contains one or more of the following properties. @@ -5628,7 +5686,9 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: InvalidAttachmentId - The attachment identifier does not exist. * * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. @@ -5645,7 +5705,9 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: InvalidAttachmentId - The attachment identifier does not exist. * * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. @@ -5668,6 +5730,7 @@ declare namespace Office { * Note: Certain types of files are blocked by Outlook due to potential security issues and are therefore not returned. For more information, see [Blocked attachments in Outlook]. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * */ @@ -5689,6 +5752,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ itemClass: string; @@ -5704,6 +5768,7 @@ declare namespace Office { * Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ itemId: string; @@ -5717,6 +5782,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ normalizedSubject: string; @@ -5738,6 +5804,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ subject: string; @@ -5757,6 +5824,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param formData A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB @@ -5787,6 +5855,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param formData A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB. @@ -5811,6 +5880,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ getEntities(): Entities; @@ -5838,7 +5908,9 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: Restricted + * * Applicable Outlook mode: Read + * * @param entityType One of the EntityType enumeration values. */ getEntitiesByType(entityType: Office.MailboxEnums.EntityType): Array<(string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)>; @@ -5854,6 +5926,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param name The name of the ItemHasKnownEntity rule element that defines the filter to match. @@ -5877,6 +5950,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ getRegExMatches(): any; @@ -5897,6 +5971,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param name The name of the ItemHasRegularExpressionMatch rule element that defines the filter to match. @@ -5912,6 +5987,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param name The name of the ItemHasRegularExpressionMatch rule element that defines the filter to match. @@ -5934,6 +6010,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ getSelectedRegExMatches(): any; @@ -5951,6 +6028,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ conversationId: string; @@ -5964,6 +6042,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose */ bcc: Recipients; @@ -5983,6 +6062,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ cc: Recipients; @@ -6002,6 +6082,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ to: Recipients; @@ -6023,6 +6104,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ cc: Array; @@ -6038,6 +6120,7 @@ declare namespace Office { * Note: The recipientType property of the EmailAddressDetails object in the from property is undefined. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ from: EmailAddressDetails; @@ -6049,6 +6132,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ internetMessageId: string; @@ -6064,6 +6148,7 @@ declare namespace Office { * Note: The recipientType property of the EmailAddressDetails object in the sender property is undefined. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ sender: EmailAddressDetails; @@ -6083,6 +6168,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ to: Array; @@ -6095,6 +6181,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ export interface LocalClientTime { @@ -6138,6 +6225,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose */ export interface Location { @@ -6154,6 +6242,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose */ getAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; @@ -6171,7 +6260,9 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose + * * Errors: DataExceedsMaximumSize - The location parameter is longer than 255 characters. */ setAsync(location: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; @@ -6192,6 +6283,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read */ export interface Mailbox { @@ -6211,6 +6303,7 @@ declare namespace Office { * Note: This member is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ ewsUrl: string; @@ -6234,6 +6327,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ restUrl: string; @@ -6247,6 +6341,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param eventType The event that should invoke the handler. @@ -6267,6 +6362,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read * * @param itemId An item ID formatted for the Outlook REST APIs. @@ -6285,6 +6381,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param timeValue A Date object. @@ -6301,6 +6398,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read * * @param itemId An item ID formatted for Exchange Web Services (EWS) @@ -6317,6 +6415,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param input The local time value to convert. @@ -6340,7 +6439,9 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read + * * @param itemId The Exchange Web Services (EWS) identifier for an existing calendar appointment. */ displayAppointmentForm(itemId: string): void; @@ -6361,7 +6462,9 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read + * * @param itemId The Exchange Web Services (EWS) identifier for an existing message. */ displayMessageForm(itemId: string): void; @@ -6382,6 +6485,7 @@ declare namespace Office { * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param parameters A dictionary of parameters describing the new appointment. All parameters are optional. @@ -6407,6 +6511,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read * * @param parameters A dictionary containing all values to be filled in for the user in the new form. All parameters are optional. @@ -6447,6 +6552,7 @@ declare namespace Office { * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose and read * * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. @@ -6476,6 +6582,7 @@ declare namespace Office { * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose and read * * @param options An object literal that contains one or more of the following properties. @@ -6500,6 +6607,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose and read * * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. @@ -6518,6 +6626,7 @@ declare namespace Office { * @remarks * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose and read * * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. @@ -6557,6 +6666,7 @@ declare namespace Office { * You do not need to set the encoding value when your mail app is running in Outlook on the web. You can determine whether your mail app is running in Outlook or Outlook on the web by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property. * * Minimum permission level: ReadWriteMailbox + * * Applicable Outlook mode: Compose and read * * @param data The EWS request. @@ -6577,6 +6687,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ export interface MeetingSuggestion { @@ -6612,6 +6723,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ export interface NotificationMessageDetails { @@ -6643,6 +6755,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ export interface NotificationMessages { @@ -6665,6 +6778,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ addAsync(key: string, JSONmessage: NotificationMessageDetails, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; @@ -6676,6 +6790,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param options Optional. An object literal that contains one or more of the following properties. @@ -6691,6 +6806,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param key The key for the notification message to remove. @@ -6709,6 +6825,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read * * @param key The key for the notification message to replace. It can't be longer than 32 characters. @@ -6733,6 +6850,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ export interface PhoneNumber { @@ -6754,6 +6872,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose */ export interface Recipients { @@ -6772,7 +6891,9 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. * * @param recipients The recipients to add to the recipients list. @@ -6791,6 +6912,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose * * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. @@ -6805,6 +6927,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose * * @param options An object literal that contains one or more of the following properties. @@ -6830,7 +6953,9 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. * * @param recipients The recipients to add to the recipients list. @@ -6867,6 +6992,7 @@ declare namespace Office { * Important: The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded. For task panes, this means that it is only initialized when the task pane first opens. If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has persisted changes. The persisted changes will not be available until the task pane is closed and reopened. * * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read */ export interface RoamingSettings { @@ -6877,6 +7003,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read * * @param name The case-sensitive name of the setting to retrieve. @@ -6890,6 +7017,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read * * @param name The case-sensitive name of the setting to remove. @@ -6904,6 +7032,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read * * @param callback Optional? When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. @@ -6922,6 +7051,7 @@ declare namespace Office { * * @remarks * Minimum permission level: Restricted + * * Applicable Outlook mode: Compose or read * * @param name The case-sensitive name of the setting to set or create. @@ -6937,6 +7067,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose */ export interface Subject { @@ -6948,6 +7079,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose * * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. @@ -6962,6 +7094,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose * * @param options An object literal that contains one or more of the following properties. @@ -6979,7 +7112,9 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose + * * Errors: DataExceedsMaximumSize - The subject parameter is longer than 255 characters. * * @param subject The subject of the appointment or message. The string is limited to 255 characters. @@ -6999,6 +7134,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Read */ export interface TaskSuggestion { @@ -7018,6 +7154,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose */ export interface Time { @@ -7030,6 +7167,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose * * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. @@ -7044,6 +7182,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose * * @param options An object literal that contains one or more of the following properties. @@ -7063,7 +7202,9 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadWriteItem + * * Applicable Outlook mode: Compose + * * Errors: InvalidEndTime - The appointment end time is before the appointment start time. * * @param dateTime A date-time object in Coordinated Universal Time (UTC). @@ -7079,6 +7220,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ export interface UserProfile { @@ -7098,6 +7240,7 @@ declare namespace Office { * |outlookCom |The mailbox is associated with a personal Outlook.com account.| * * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ accountType: string; @@ -7108,6 +7251,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ displayName: string; @@ -7118,6 +7262,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ emailAddress: string; @@ -7128,6 +7273,7 @@ declare namespace Office { * * @remarks * Minimum permission level: ReadItem + * * Applicable Outlook mode: Compose or read */ timeZone: string; From f73089b02231a60a0d8bdbfd5d70901ad440dc6b Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Tue, 29 May 2018 17:38:36 -0700 Subject: [PATCH 5/7] Outlook documentation migration - OfficeTheme fix --- types/office-js/index.d.ts | 44 +++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index 76ef91c769..827a159214 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -388,10 +388,34 @@ declare namespace Office { */ asyncContext?: any } + /** + * Provides access to the properties for Office theme colors. + * + * Using Office theme colors lets you coordinate the color scheme of your add-in with the current Office theme selected by the user with File > Office Account > Office Theme UI, which is applied across all Office host applications. Using Office theme colors is appropriate for mail and task pane add-ins. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Note: This member is not supported in Outlook for iOS or Outlook for Android. + * + * Applicable Outlook mode: Compose or read + */ export interface OfficeTheme { + /** + * Gets the Office theme body background color as a hexadecimal color triplet. + */ bodyBackgroundColor: string; + /** + * Gets the Office theme body foreground color as a hexadecimal color triplet. + */ bodyForegroundColor: string; + /** + * Gets the Office theme control background color as a hexadecimal color triplet. + */ controlBackgroundColor: string; + /** + * Gets the Office theme body control color as a hexadecimal color triplet. + */ controlForegroundColor: string; } /** @@ -4751,26 +4775,6 @@ declare namespace Office { * Applicable Outlook mode: Compose or read */ mailbox: Mailbox; - /** - * Provides access to the properties for Office theme colors. - * - * Using Office theme colors let's you coordinate the color scheme of your add-in with the current Office theme selected by the user with File > Office Account > Office Theme UI, which is applied across all Office host applications. Using Office theme colors is appropriate for mail and task pane add-ins. - * - * |Name |Type |Description| - * |-----|-----|-----------| - * |bodyBackgroundColor|String|Gets the Office theme body background color as a hexadecimal color triplet.| - * |bodyForegroundColor|String|Gets the Office theme body foreground color as a hexadecimal color triplet.| - * |controlBackgroundColor|String|Gets the Office theme control background color as a hexadecimal color triplet.| - * |controlForegroundColor|String|Gets the Office theme body control color as a hexadecimal color triplet.| - * - * [Api set: Mailbox 1.3] - * - * @remarks - * Note: This member is not supported in Outlook for iOS or Outlook for Android. - * - * Applicable Outlook mode: Compose or read - */ - officeTheme: Object; /** * Gets an object that represents the custom settings or state of a mail add-in saved to a user's mailbox. * From 0deac20f0902ec26e74708ea2f8cb19bae39fa44 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Wed, 30 May 2018 15:04:06 -0700 Subject: [PATCH 6/7] Office Migration - Zlatkovsky's change requests --- types/office-js/index.d.ts | 375 +++++++++++++++++++++---------------- 1 file changed, 217 insertions(+), 158 deletions(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index 827a159214..18975697fe 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -392,29 +392,25 @@ declare namespace Office { * Provides access to the properties for Office theme colors. * * Using Office theme colors lets you coordinate the color scheme of your add-in with the current Office theme selected by the user with File > Office Account > Office Theme UI, which is applied across all Office host applications. Using Office theme colors is appropriate for mail and task pane add-ins. - * - * [Api set: Mailbox 1.3] - * + * * @remarks - * Note: This member is not supported in Outlook for iOS or Outlook for Android. - * - * Applicable Outlook mode: Compose or read + * Hosts: Excel, Outlook, Powerpoint, Project, Word */ export interface OfficeTheme { /** - * Gets the Office theme body background color as a hexadecimal color triplet. + * Gets the Office theme body background color as a hexadecimal color triplet (e.g. "FFA500"). */ bodyBackgroundColor: string; /** - * Gets the Office theme body foreground color as a hexadecimal color triplet. + * Gets the Office theme body foreground color as a hexadecimal color triplet (e.g. "FFA500"). */ bodyForegroundColor: string; /** - * Gets the Office theme control background color as a hexadecimal color triplet. + * Gets the Office theme control background color as a hexadecimal color triplet (e.g. "FFA500"). */ controlBackgroundColor: string; /** - * Gets the Office theme body control color as a hexadecimal color triplet. + * Gets the Office theme body control color as a hexadecimal color triplet (e.g. "FFA500"). */ controlForegroundColor: string; } @@ -1745,11 +1741,11 @@ declare namespace Office { /** * Adds an event handler for the settingsChanged event. * + * Important: Your add-in's code can register a handler for the settingsChanged event when the add-in is running with any Excel client, but the event will fire only when the add-in is loaded with a spreadsheet that is opened in Excel Online, and more than one user is editing the spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios. + * * @remarks * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. * - * Important: Your add-in's code can register a handler for the settingsChanged event when the add-in is running with any Excel client, but the event will fire only when the add-in is loaded with a spreadsheet that is opened in Excel Online, and more than one user is editing the spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios. - * * Hosts: Excel * * Available in Requirement set: Settings @@ -1808,10 +1804,11 @@ declare namespace Office { /** * Removes the specified setting. * + * Important: Be aware that the Settings.remove method affects only the in-memory copy of the settings property bag. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method. + * * @remarks * null is a valid value for a setting. Therefore, assigning null to the setting will not remove it from the settings property bag. * - * Important: Be aware that the Settings.remove method affects only the in-memory copy of the settings property bag. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method. * Hosts: Access, Excel, PowerPoint, Word * * Available in Requirement set: Settings @@ -1867,11 +1864,12 @@ declare namespace Office { /** * Sets or creates the specified setting. * - * @remarks - * The set method creates a new setting of the specified name if it does not already exist, or sets an existing setting of the specified name in the in-memory copy of the settings property bag. After you call the Settings.saveAsync method, the value is stored in the document as the serialized JSON representation of its data type. A maximum of 2MB is available for the settings of each add-in. * * Important: Be aware that the Settings.set method affects only the in-memory copy of the settings property bag. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document. * + * @remarks + * The set method creates a new setting of the specified name if it does not already exist, or sets an existing setting of the specified name in the in-memory copy of the settings property bag. After you call the Settings.saveAsync method, the value is stored in the document as the serialized JSON representation of its data type. A maximum of 2MB is available for the settings of each add-in. + * * Hosts: Access, Excel, PowerPoint, Word * * Available in Requirement set: Settings @@ -4380,7 +4378,7 @@ declare namespace Office { */ Address, /** - * Specifies that the entity is a SMTP email address. + * Specifies that the entity is an SMTP email address. */ EmailAddress, /** @@ -4607,9 +4605,10 @@ declare namespace Office { * @param coercionType The format for the returned body. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The body is provided in the requested format in the asyncResult.value property. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The body is provided in the requested format in the asyncResult.value property. */ getAsync(coercionType: CoercionType, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + getAsync(coercionType: CoercionType, callback: (result: AsyncResult) => void): void; /** * Gets a value that indicates whether the content is in HTML or text format. @@ -4623,13 +4622,13 @@ declare namespace Office { * * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The content type is returned as one of the CoercionType values in the asyncResult.value property. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The content type is returned as one of the CoercionType values in the asyncResult.value property. */ getTypeAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Adds the specified content to the beginning of the item body. * - * The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to it's original place, relative to the inserted content. + * The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content. * * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. * @@ -4644,9 +4643,12 @@ declare namespace Office { * @param options Optional. 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 method. * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. Any errors encountered will be provided in the asyncResult.error property. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. */ prependAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; + prependAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + prependAsync(data: string, callback: (result: AsyncResult) => void): void; + prependAsync(data: string): void; /** * Replaces the entire body with the specified text. * @@ -4669,9 +4671,13 @@ declare namespace Office { * @param options Optional. 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 method. * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. Any errors encountered will be provided in the asyncResult.error property. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. */ setAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; + setAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + setAsync(data: string, callback: (result: AsyncResult) => void): void; + setAsync(data: string): void; + /** * Replaces the selection in the body with the specified text. * @@ -4694,9 +4700,12 @@ declare namespace Office { * @param options Optional. 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 method. * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. Any errors encountered will be provided in the asyncResult.error property. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. */ setSelectedDataAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; + setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; + setSelectedDataAsync(data: string): void; } /** * Represents a contact stored on the server. Read mode only. @@ -4737,11 +4746,13 @@ declare namespace Office { urls: Array; } /** - * The Office.context namespace provides shared interfaces that are used by add-ins in all of the Office apps. This listing documents only those interfaces that are used by Outlook add-ins. For a full listing of the Office.context namespace, see the [Office.context reference in the Shared API]. + * The Office.context namespace provides shared interfaces that are used by add-ins in all of the Office apps. This listing documents only those interfaces that are used by Outlook add-ins. * * [Api set: Mailbox 1.0] * * @remarks + * For a full listing of the Office.context namespace, see the [Office.context reference in the Shared API]. + * * Applicable Outlook mode: Compose or read */ export interface Context { @@ -4792,7 +4803,7 @@ declare namespace Office { /** * The CustomProperties object represents custom properties that are specific to a particular item and specific to a mail add-in for Outlook. For example, there might be a need for a mail add-in to save some data that is specific to the current email message that activated the add-in. If the user revisits the same message in the future and activates the mail add-in again, the add-in will be able to retrieve the data that had been saved as custom properties. * - * Because Outlook for Mac doesn’t cache custom properties, if the user’s network goes down, mail add-ins cannot access their custom properties. + * Because Outlook for Mac doesn't cache custom properties, if the user's network goes down, mail add-ins cannot access their custom properties. * * [Api set: Mailbox 1.0] * @@ -4852,9 +4863,9 @@ declare namespace Office { * * You must call the saveAsync method to persist any changes made with the set method or the remove method of the CustomProperties object. The saving action is asynchronous. * - * It’s a good practice to have your callback function check for and handle errors from saveAsync. In particular, a read add-in can be activated while the user is in a connected state in a read form, and subsequently the user becomes disconnected. If the add-in calls saveAsync while in the disconnected state, saveAsync would return an error. Your callback method should handle this error accordingly. + * It's a good practice to have your callback function check for and handle errors from saveAsync. In particular, a read add-in can be activated while the user is in a connected state in a read form, and subsequently the user becomes disconnected. If the add-in calls saveAsync while in the disconnected state, saveAsync would return an error. Your callback method should handle this error accordingly. * - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. * @param asyncContext Optional. Any state data that is passed to the callback method. * * [Api set: Mailbox 1.0] @@ -5001,31 +5012,31 @@ declare namespace Office { /** * Gets the physical addresses (street or mailing addresses) found in an email message or appointment. */ - addresses: Array; + addresses: string[]; /** * Gets the contacts found in an email address or appointment. */ - contacts: Array; + contacts: Contact[]; /** * Gets the email addresses found in an email message or appointment. */ - emailAddresses: Array; + emailAddresses: string[]; /** * Gets the meeting suggestions found in an email message. */ - meetingSuggestions: Array; + meetingSuggestions: MeetingSuggestion[]; /** * Gets the phone numbers found in an email message or appointment. */ - phoneNumbers: Array; + phoneNumbers: PhoneNumber[]; /** * Gets the task suggestions found in an email message or appointment. */ - taskSuggestions: Array; + taskSuggestions: string[]; /** * Gets the Internet URLs present in an email message or appointment. */ - urls: Array; + urls: string[]; } @@ -5035,7 +5046,7 @@ declare namespace Office { /** * Gets or sets the date and time that the appointment is to end. * - * The end property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client’s local date and time. + * The end property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client's local date and time. * * *Read mode* * @@ -5119,7 +5130,7 @@ declare namespace Office { /** * Gets or sets the date and time that the appointment is to begin. * - * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client’s local date and time. + * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time. * * *Read mode* * @@ -5182,7 +5193,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read */ - optionalAttendees: Array; + optionalAttendees: EmailAddressDetails[]; /** * Gets the email address of the meeting organizer for a specified meeting. Read mode only. * @@ -5214,11 +5225,11 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read */ - requiredAttendees: Array; + requiredAttendees: EmailAddressDetails[]; /** * Gets or sets the date and time that the appointment is to begin. * - * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client’s local date and time. + * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time. * * *Read mode* * @@ -5244,7 +5255,7 @@ declare namespace Office { /** * Gets or sets the date and time that the appointment is to end. * - * The end property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client’s local date and time. + * The end property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client's local date and time. * * *Read mode* * @@ -5303,7 +5314,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read */ - optionalAttendees: Array | Array; + optionalAttendees: string[] | EmailAddressDetails[]; /** * Provides access to the required attendees of an event. The type of object and level of access depends on the mode of the current item. * @@ -5323,11 +5334,11 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read */ - requiredAttendees: Array | Array; + requiredAttendees: string[] | EmailAddressDetails[]; /** * Gets or sets the date and time that the appointment is to begin. * - * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client’s local date and time. + * The start property is expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time. * * *Read mode* * @@ -5462,7 +5473,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read * - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. * @param userContext Optional. Developers can provide any object they wish to access in the callback function. This object can be accessed by the asyncResult.asyncContext property in the callback function. */ loadCustomPropertiesAsync(callback: (result: AsyncResult) => void, userContext?: any): void; @@ -5517,9 +5528,13 @@ declare namespace Office { * @param options Optional. 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 method. * inInline: If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. On success, the attachment identifier will be provided in the asyncResult.value property. If uploading the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type asyncResult. On success, the attachment identifier will be provided in the asyncResult.value property. If uploading the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. */ addFileAttachmentAsync(uri: string, attachmentName: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + addFileAttachmentAsync(uri: string, attachmentName: string): void; + addFileAttachmentAsync(uri: string, attachmentName: string, options: AsyncContextOptions): void; + addFileAttachmentAsync(uri: string, attachmentName: string, callback: (result: AsyncResult) => void): void; + /** * Adds an Exchange item, such as a message, as an attachment to the message or appointment. * @@ -5544,21 +5559,25 @@ declare namespace Office { * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. * @param options 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 method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. On success, the attachment identifier will be provided in the asyncResult.value property. If adding the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. On success, the attachment identifier will be provided in the asyncResult.value property. If adding the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. */ addItemAttachmentAsync(itemId: any, attachmentName: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + addItemAttachmentAsync(itemId: any, attachmentName: string): void; + addItemAttachmentAsync(itemId: any, attachmentName: string, options: AsyncContextOptions): void; + addItemAttachmentAsync(itemId: any, attachmentName: string, callback: (result: AsyncResult) => void): void; + /** * Closes the current item that is being composed * - * The behaviors of the close method depends on the current state of the item being composed. If the item has unsaved changes, the client - * prompts the user to save, discard, or close the action. + * The behaviors of the close method depends on the current state of the item being composed. If the item has unsaved changes, the client prompts the user to save, discard, or close the action. * * In the Outlook desktop client, if the message is an inline reply, the close method has no effect. * + * Note: In Outlook on the web, if the item is an appointment and it has previously been saved using saveAsync, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved. + * * [Api set: Mailbox 1.3] * * @remarks - * Note: In Outlook on the web, if the item is an appointment and it has previously been saved using saveAsync, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved. * * Minimum permission level: Restricted * @@ -5566,21 +5585,22 @@ declare namespace Office { */ close(): void; /** - * Gets initialization data passed when the add-in is [activated by an actionable message]. + * Gets initialization data passed when the add-in is activated by an actionable message. * + * Note: This method is only supported by Outlook 2016 for Windows (Click-to-Run versions greater than 16.0.8413.1000) and Outlook on the web for Office 365. + * * [Api set: Mailbox Preview] * * @remarks * - * Note: This method is only supported by Outlook 2016 for Windows (Click-to-Run versions greater than 16.0.8413.1000) and Outlook on the web for Office 365. - * + * More information on [actionable messages]. * Minimum permission level: ReadItem * * Applicable Outlook mode: Read * * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. On success, the initialization data is provided in the asyncResult.value property as a string. If there is no initialization context, the asyncResult object will contain an Error object with its code property set to 9020 and its name property set to GenericResponseError. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. On success, the initialization data is provided in the asyncResult.value property as a string. If there is no initialization context, the asyncResult object will contain an Error object with its code property set to 9020 and its name property set to GenericResponseError. */ getInitializationContextAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** @@ -5588,6 +5608,8 @@ declare namespace Office { * * If there is no selection but the cursor is in the body or subject, the method returns null for the selected data. If a field other than the body or subject is selected, the method returns the InvalidSelection error. * + * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. + * * [Api set: Mailbox 1.0] * * @returns @@ -5595,14 +5617,12 @@ declare namespace Office { * * @remarks * - * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. - * * Minimum permission level: ReadWriteItem * * Applicable Outlook mode: Compose * * @param coercionType Requests a format for the data. If Text, the method returns the plain text as a string , removing any HTML tags present. If HTML, the method returns the selected text, whether it is plaintext or HTML. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getSelectedDataAsync(coercionType: CoercionType, callback: (result: AsyncResult) => void): void; /** @@ -5610,6 +5630,8 @@ declare namespace Office { * * If there is no selection but the cursor is in the body or subject, the method returns null for the selected data. If a field other than the body or subject is selected, the method returns the InvalidSelection error. * + * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. + * * [Api set: Mailbox 1.0] * * @returns @@ -5617,8 +5639,6 @@ declare namespace Office { * * @remarks * - * To access the selected data from the callback method, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject. - * * Minimum permission level: ReadWriteItem * * Applicable Outlook mode: Compose @@ -5626,7 +5646,7 @@ declare namespace Office { * @param coercionType Requests a format for the data. If Text, the method returns the plain text as a string , removing any HTML tags present. If HTML, the method returns the selected text, whether it is plaintext or HTML. * @param options 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 method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getSelectedDataAsync(coercionType: CoercionType, options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; /** @@ -5647,9 +5667,13 @@ declare namespace Office { * @param attachmentIndex The identifier of the attachment to remove. The maximum length of the string is 100 characters. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ removeAttachmentAsync(attachmentIndex: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + removeAttachmentAsync(attachmentIndex: string): void; + removeAttachmentAsync(attachmentIndex: string, options: AsyncContextOptions): void; + removeAttachmentAsync(attachmentIndex: string, callback: (result: AsyncResult) => void): void; + /** * Asynchronously saves an item. * @@ -5657,10 +5681,6 @@ declare namespace Office { * * Since appointments have no draft state, if saveAsync is called on an appointment in compose mode, the item will be saved as a normal appointment on the user's calendar. For new appointments that have not been saved before, no invitation will be sent. Saving an existing appointment will send an update to added or removed attendees. * - * - * [Api set: Mailbox 1.3] - * - * @remarks * Note: If your add-in calls saveAsync on an item in compose mode in order to get an itemId to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the itemId will return an error. * * Note: The following clients have different behavior for saveAsync on appointments in compose mode: @@ -5669,6 +5689,10 @@ declare namespace Office { * * - Outlook on the web always sends an invitation or update when saveAsync is called on an appointment in compose mode. * + * [Api set: Mailbox 1.3] + * + * @remarks + * * Minimum permission level: ReadWriteItem * * Applicable Outlook mode: Compose @@ -5677,9 +5701,12 @@ declare namespace Office { * * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ saveAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + saveAsync(): void; + saveAsync(options: AsyncContextOptions): void; + saveAsync(callback: (result: AsyncResult) => void): void; /** * Asynchronously inserts data into the body or subject of a message. * @@ -5696,9 +5723,12 @@ declare namespace Office { * Errors: InvalidAttachmentId - The attachment identifier does not exist. * * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; + setSelectedDataAsync(data: string): void; + setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; /** * Asynchronously inserts data into the body or subject of a message. * @@ -5718,7 +5748,7 @@ declare namespace Office { * @param options Optional. 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 method. * coercionType: If text, the current style is applied in Outlook Web App and Outlook. If the field is an HTML editor, only the text data is inserted, even if the data is HTML. If html and the field supports HTML (the subject doesn't), the current style is applied in Outlook Web App and the default style is applied in Outlook. If the field is a text field, an InvalidDataFormat error is returned. If coercionType is not set, the result depends on the field: if the field is HTML then HTML is used; if the field is text, then plain text is used. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions, callback: (result: AsyncResult) => void): void; @@ -5738,7 +5768,7 @@ declare namespace Office { * Applicable Outlook mode: Read * */ - attachments: Array; + attachments: AttachmentDetails[]; /** * Gets the Exchange Web Services item class of the selected item. Read mode only. * @@ -5764,12 +5794,12 @@ declare namespace Office { * Gets the Exchange Web Services item identifier for the current item. Read mode only. * * The itemId property is not available in compose mode. If an item identifier is required, the saveAsync method can be used to save the item to the store, which will return the item identifier in the AsyncResult.value parameter in the callback function. + * + * Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * * * [Api set: Mailbox 1.0] * * @remarks - * - * Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * * * Minimum permission level: ReadItem * @@ -5821,12 +5851,11 @@ declare namespace Office { * * When attachments are specified in the formData.attachments parameter, Outlook and Outlook Web App attempt to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @remarks - * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -5852,12 +5881,12 @@ declare namespace Office { * * When attachments are specified in the formData.attachments parameter, Outlook and Outlook Web App attempt to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @remarks * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -5876,13 +5905,13 @@ declare namespace Office { displayReplyForm(formData: string | ReplyFormData): void; /** * Gets the entities found in the selected item. - * + * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @remarks * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -5890,7 +5919,9 @@ declare namespace Office { getEntities(): Entities; /** * Gets an array of all the entities of the specified entity type found in the selected item. - * + * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @returns @@ -5908,26 +5939,23 @@ declare namespace Office { * |URL|String|Restricted| * * @remarks - * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: Restricted * * Applicable Outlook mode: Read * * @param entityType One of the EntityType enumeration values. */ - getEntitiesByType(entityType: Office.MailboxEnums.EntityType): Array<(string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)>; + getEntitiesByType(entityType: Office.MailboxEnums.EntityType): (string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)[]; /** * Returns well-known entities in the selected item that pass the named filter defined in the manifest XML file. * * The getFilteredEntitiesByName method returns the entities that match the regular expression defined in the ItemHasKnownEntity rule element in the manifest XML file with the specified FilterName element value. - * - * [Api set: Mailbox 1.0] - * - * @remarks * * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * + * [Api set: Mailbox 1.0] + * + * @remarks * * Minimum permission level: ReadItem * @@ -5936,7 +5964,7 @@ declare namespace Office { * @param name The name of the ItemHasKnownEntity rule element that defines the filter to match. * @returns If there is no ItemHasKnownEntity element in the manifest with a FilterName element value that matches the name parameter, the method returns null. If the name parameter does match an ItemHasKnownEntity element in the manifest, but there are no entities in the current item that match, the method return an empty array. */ - getFilteredEntitiesByName(name: string): Array<(string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)>; + getFilteredEntitiesByName(name: string): (string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)[]; /** * Returns string values in the selected item that match the regular expressions defined in the manifest XML file. * @@ -5944,6 +5972,8 @@ declare namespace Office { * * If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @returns @@ -5951,8 +5981,6 @@ declare namespace Office { * * @remarks * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -5965,6 +5993,8 @@ declare namespace Office { * * If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @returns @@ -5972,24 +6002,22 @@ declare namespace Office { * * @remarks * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read * * @param name The name of the ItemHasRegularExpressionMatch rule element that defines the filter to match. */ - getRegExMatchesByName(name: string): Array; + getRegExMatchesByName(name: string): string[]; /** * Gets the entities found in a highlighted match a user has selected. Highlighted matches apply to contextual add-ins. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.6] * * @remarks * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -6004,6 +6032,8 @@ declare namespace Office { * * If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.6] * * @returns @@ -6011,8 +6041,6 @@ declare namespace Office { * * @remarks * - * Note: This method is not supported in Outlook for iOS or Outlook for Android. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -6111,18 +6139,18 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read */ - cc: Array; + cc: EmailAddressDetails[]; /** * Gets the email address of the sender of a message. Read mode only. * * The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate. * + * Note: The recipientType property of the EmailAddressDetails object in the from property is undefined. + * * [Api set: Mailbox 1.0] * * @remarks * - * Note: The recipientType property of the EmailAddressDetails object in the from property is undefined. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -6145,12 +6173,12 @@ declare namespace Office { * * The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate. * + * Note: The recipientType property of the EmailAddressDetails object in the sender property is undefined. + * * [Api set: Mailbox 1.0] * * @remarks * - * Note: The recipientType property of the EmailAddressDetails object in the sender property is undefined. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -6175,7 +6203,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read */ - to: Array; + to: EmailAddressDetails[]; } /** @@ -6184,6 +6212,7 @@ declare namespace Office { * [Api set: Mailbox 1.0] * * @remarks + * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -6240,7 +6269,7 @@ declare namespace Office { * * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. * * [Api set: Mailbox 1.1] * @@ -6250,6 +6279,7 @@ declare namespace Office { * Applicable Outlook mode: Compose */ getAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + getAsync(callback: (result: AsyncResult) => void): void; /** * Sets the location of an appointment. * @@ -6258,7 +6288,7 @@ declare namespace Office { * @param data The location of the appointment. The string is limited to 255 characters. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the location fails, the asyncResult.error property will contain an error code. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the location fails, the asyncResult.error property will contain an error code. * * [Api set: Mailbox 1.1] * @@ -6270,6 +6300,9 @@ declare namespace Office { * Errors: DataExceedsMaximumSize - The location parameter is longer than 255 characters. */ setAsync(location: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + setAsync(location: string): void; + setAsync(location: string, options: AsyncContextOptions): void; + setAsync(location: string, callback: (result: AsyncResult) => void): void; } /** @@ -6294,17 +6327,17 @@ declare namespace Office { /** * Gets the URL of the Exchange Web Services (EWS) endpoint for this email account. Read mode only. * - * The ewsUrl value can be used by a remote service to make EWS calls to the user's mailbox. For example, you can create a remote service to [get attachments from the selected item]. - * * Your app must have the ReadItem permission specified in its manifest to call the ewsUrl member in read mode. * * In compose mode you must call the saveAsync method before you can use the ewsUrl member. Your app must have ReadWriteItem permissions to call the saveAsync method. * + * Note: This member is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @remarks * - * Note: This member is not supported in Outlook for iOS or Outlook for Android. + * The ewsUrl value can be used by a remote service to make EWS calls to the user's mailbox. For example, you can create a remote service to [get attachments from the selected item]. * * Minimum permission level: ReadItem * @@ -6320,8 +6353,6 @@ declare namespace Office { /** * Gets the URL of the REST endpoint for this email account. * - * The restUrl value can be used to make [REST API] calls to the user's mailbox. - * * Your app must have the ReadItem permission specified in its manifest to call the restUrl member in read mode. * * In compose mode you must call the saveAsync method before you can use the restUrl member. Your app must have ReadWriteItem permissions to call the saveAsync method. @@ -6330,6 +6361,8 @@ declare namespace Office { * * @remarks * + * The restUrl value can be used to make [REST API] calls to the user's mailbox. + * * Minimum permission level: ReadItem * * Applicable Outlook mode: Compose or read @@ -6352,7 +6385,7 @@ declare namespace Office { * @param handler The function to handle the event. The function must accept a single parameter, which is an object literal. The type property on the parameter will match the eventType parameter passed to addHandlerAsync. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ addHandlerAsync(eventType: Office.EventType, handler: (type: Office.EventType) => void, options?: any, callback?: (result: AsyncResult) => void): void; /** @@ -6360,10 +6393,11 @@ declare namespace Office { * * Item IDs retrieved via a REST API (such as the Outlook Mail API or the Microsoft Graph) use a different format than the format used by Exchange Web Services (EWS). The convertToEwsId method converts a REST-formatted ID into the proper format for EWS. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.3] * * @remarks - * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: Restricted * @@ -6394,12 +6428,13 @@ declare namespace Office { /** * Converts an item ID formatted for EWS into REST format. * - * Item IDs retrieved via EWS or via the itemId property use a different format than the format used by REST APIs (such as the [Outlook Mail API] or the [Microsoft Graph]). The convertToRestId method converts an EWS-formatted ID into the proper format for REST. + * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * [Api set: Mailbox 1.3] * * @remarks - * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * + * Item IDs retrieved via EWS or via the itemId property use a different format than the format used by REST APIs (such as the [Outlook Mail API] or the [Microsoft Graph]). The convertToRestId method converts an EWS-formatted ID into the proper format for REST. * * Minimum permission level: Restricted * @@ -6437,10 +6472,11 @@ declare namespace Office { * * If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message will be returned. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @remarks - * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * @@ -6460,10 +6496,11 @@ declare namespace Office { * * Do not use the displayMessageForm with an itemId that represents an appointment. Use the displayAppointmentForm method to display an existing appointment, and displayNewAppointmentForm to display a form to create a new appointment. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @remarks - * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * @@ -6483,10 +6520,11 @@ declare namespace Office { * * If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. * + * Note: This method is not supported in Outlook for iOS or Outlook for Android. + * * [Api set: Mailbox 1.0] * * @remarks - * Note: This method is not supported in Outlook for iOS or Outlook for Android. * * Minimum permission level: ReadItem * @@ -6549,17 +6587,17 @@ declare namespace Office { * * The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls. * + * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. + * * [Api set: Mailbox 1.5] * * @remarks * - * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Compose and read * - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The token is provided as a string in the asyncResult.value property. */ getCallbackTokenAsync(callback: (result: AsyncResult) => void): void; /** @@ -6579,12 +6617,12 @@ declare namespace Office { * * The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls. * + * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. + * * [Api set: Mailbox 1.5] * * @remarks * - * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. - * * Minimum permission level: ReadItem * * Applicable Outlook mode: Compose and read @@ -6592,7 +6630,7 @@ declare namespace Office { * @param options An object literal that contains one or more of the following properties. * isRest: Determines if the token provided will be used for the Outlook REST APIs or Exchange Web Services. Default value is false. * asyncContext: Any state data that is passed to the asynchronous method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The token is provided as a string in the asyncResult.value property. */ getCallbackTokenAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; /** @@ -6614,32 +6652,31 @@ declare namespace Office { * * Applicable Outlook mode: Compose and read * - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The token is provided as a string in the asyncResult.value property. * @param userContext Optional. Any state data that is passed to the asynchronous method. */ getCallbackTokenAsync(callback: (result: AsyncResult) => void, userContext?: any): void; /** * Gets a token identifying the user and the Office Add-in. * - * The getUserIdentityTokenAsync method returns a token that you can use to identify and [authenticate the add-in and user with a third-party system]. - * * The token is provided as a string in the asyncResult.value property. * * [Api set: Mailbox 1.0] * * @remarks * + * The getUserIdentityTokenAsync method returns a token that you can use to identify and [authenticate the add-in and user with a third-party system]. + * * Minimum permission level: ReadItem * * Applicable Outlook mode: Compose and read * - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. * @param userContext Optional. Any state data that is passed to the asynchronous method.| */ getUserIdentityTokenAsync(callback: (result: AsyncResult) => void, userContext?: any): void; /** - * Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user’s mailbox. - * + * Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user's mailbox. * * In these cases, add-ins should use REST APIs to access the user's mailbox instead. * @@ -6653,10 +6690,6 @@ declare namespace Office { * * The XML result of the EWS call is provided as a string in the asyncResult.value property. If the result exceeds 1 MB in size, an error message is returned instead. * - * [Api set: Mailbox 1.0] - * - * @remarks - * * Note: This method is not supported in the following scenarios. - In Outlook for iOS or Outlook for Android - When the add-in is loaded in a Gmail mailbox * * Note: The server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests. @@ -6667,14 +6700,18 @@ declare namespace Office { * * * - * You do not need to set the encoding value when your mail app is running in Outlook on the web. You can determine whether your mail app is running in Outlook or Outlook on the web by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property. + * You do not need to set the encoding value when your mail app is running in Outlook on the web. You can determine whether your mail app is running in Outlook or Outlook on the web by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property. + * + * [Api set: Mailbox 1.0] + * + * @remarks * * Minimum permission level: ReadWriteMailbox * * Applicable Outlook mode: Compose and read * * @param data The EWS request. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. * @param userContext Optional. Any state data that is passed to the asynchronous method. */ makeEwsRequestAsync(data: any, callback: (result: AsyncResult) => void, userContext?: any): void; @@ -6698,7 +6735,7 @@ declare namespace Office { /** * Gets the attendees for a suggested meeting. */ - attendees: Array; + attendees: EmailUser[]; /** * Gets the date and time that a suggested meeting is to end. */ @@ -6776,7 +6813,7 @@ declare namespace Office { * persistent: Only applicable when type is InformationalMessage. If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. For error notifications, the message persists until the user sees it once. Specifying this parameter for an unsupported type throws an exception. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. * * [Api set: Mailbox 1.3] * @@ -6786,6 +6823,9 @@ declare namespace Office { * Applicable Outlook mode: Compose or read */ addAsync(key: string, JSONmessage: NotificationMessageDetails, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + addAsync(key: string, JSONmessage: NotificationMessageDetails): void; + addAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions): void; + addAsync(key: string, JSONmessage: NotificationMessageDetails, callback: (result: AsyncResult) => void): void; /** * Returns all keys and messages for an item. @@ -6799,9 +6839,10 @@ declare namespace Office { * * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAllAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + getAllAsync(callback: (result: AsyncResult) => void): void; /** * Removes a notification message for an item. @@ -6816,9 +6857,12 @@ declare namespace Office { * @param key The key for the notification message to remove. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ removeAsync(key: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + removeAsync(key: string): void; + removeAsync(key: string, options: AsyncContextOptions): void; + removeAsync(key: string, callback: (result: AsyncResult) => void): void; /** * Replaces a notification message that has a given key with another message. @@ -6840,10 +6884,12 @@ declare namespace Office { * persistent: Only applicable when type is InformationalMessage. If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. For error notifications, the message persists until the user sees it once. Specifying this parameter for an unsupported type throws an exception. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; - + replaceAsync(key: string, JSONmessage: NotificationMessageDetails): void; + replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions): void; + replaceAsync(key: string, JSONmessage: NotificationMessageDetails, callback: (result: AsyncResult) => void): void; } /** * Represents a phone number identified in an item. Read mode only. @@ -6903,9 +6949,12 @@ declare namespace Office { * @param recipients The recipients to add to the recipients list. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If adding the recipients fails, the asyncResult.error property will contain an error code. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If adding the recipients fails, the asyncResult.error property will contain an error code. */ - addAsync(recipients: Array, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + addAsync(recipients: (string | EmailUser | EmailAddressDetails)[]): void; + addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: AsyncContextOptions): void; + addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], callback: (result: AsyncResult) => void): void; /** * Gets a recipient list for an appointment or message. @@ -6919,7 +6968,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose * - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(callback: (result: AsyncResult) => void): void; /** @@ -6936,7 +6985,7 @@ declare namespace Office { * * @param options 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 method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; @@ -6965,9 +7014,12 @@ declare namespace Office { * @param recipients The recipients to add to the recipients list. * @param options Optional. 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 method. - * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the recipients fails the asyncResult.error property will contain a code that indicates any error that occurred while adding the data. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the recipients fails the asyncResult.error property will contain a code that indicates any error that occurred while adding the data. */ - setAsync(recipients: Array, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + setAsync(recipients: (string | EmailUser | EmailAddressDetails)[]): void; + setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: AsyncContextOptions): void; + setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], callback: (result: AsyncResult) => void): void; } export interface ReplyFormAttachment { @@ -6978,7 +7030,7 @@ declare namespace Office { } export interface ReplyFormData { htmlBody?: string; - attachments?: Array; + attachments?: ReplyFormAttachment[]; callback?: (result: AsyncResult) => void; } /** @@ -6990,11 +7042,11 @@ declare namespace Office { * * The RoamingSettings object is accessible via the roamingSettings property in the Office.context namespace. * + * Important: The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded. For task panes, this means that it is only initialized when the task pane first opens. If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has persisted changes. The persisted changes will not be available until the task pane is closed and reopened. + * * [Api set: Mailbox 1.0] * * @remarks - * Important: The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded. For task panes, this means that it is only initialized when the task pane first opens. If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has persisted changes. The persisted changes will not be available until the task pane is closed and reopened. - * * Minimum permission level: Restricted * * Applicable Outlook mode: Compose or read @@ -7039,7 +7091,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read * - * @param callback Optional? When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback Optional? When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ saveAsync(callback?: (result: AsyncResult) => void): void; /** @@ -7086,7 +7138,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose * - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(callback: (result: AsyncResult) => void): void; /** @@ -7103,7 +7155,7 @@ declare namespace Office { * * @param options 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 method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; @@ -7124,9 +7176,12 @@ declare namespace Office { * @param subject The subject of the appointment or message. The string is limited to 255 characters. * @param options 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 method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the subject fails, the asyncResult.error property will contain an error code. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the subject fails, the asyncResult.error property will contain an error code. */ setAsync(subject: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + setAsync(data: string): void; + setAsync(data: string, options: AsyncContextOptions): void; + setAsync(data: string, callback: (result: AsyncResult) => void): void; } /** @@ -7145,7 +7200,7 @@ declare namespace Office { /** * Gets the users that should be assigned a suggested task. */ - assignees: Array; + assignees: EmailUser[]; /** * Gets the text of an item that was identified as a task suggestion. */ @@ -7174,7 +7229,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose * - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(callback: (result: AsyncResult) => void): void; /** @@ -7191,7 +7246,7 @@ declare namespace Office { * * @param options 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 method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; @@ -7214,9 +7269,12 @@ declare namespace Office { * @param dateTime A date-time object in Coordinated Universal Time (UTC). * @param options 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 method. - * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. If setting the date and time fails, the asyncResult.error property will contain an error code. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the date and time fails, the asyncResult.error property will contain an error code. */ setAsync(dateTime: Date, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + setAsync(dateTime: Date): void; + setAsync(dateTime: Date, options: AsyncContextOptions): void; + setAsync(dateTime: Date, callback: (result: AsyncResult) => void): void; } /** @@ -7231,10 +7289,11 @@ declare namespace Office { /** * Gets the account type of the user associated with the mailbox. The possible values are listed in the following table. * + * Note: This member is currently only supported in Outlook 2016 for Mac, build 16.9.1212 and greater. + * * [Api set: Mailbox 1.6] * * @remarks - * Note: This member is currently only supported in Outlook 2016 for Mac, build 16.9.1212 and greater. * * |Value |Description | * |---------|--------------| From a368664d073bbbedab46b36aefc79bffc129c4d4 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Wed, 30 May 2018 17:16:35 -0700 Subject: [PATCH 7/7] Outlook Migration - Overload documentation and Zlatkovsky's comments --- types/office-js/index.d.ts | 1102 +++++++++++++++++++++++++++++++++--- 1 file changed, 1029 insertions(+), 73 deletions(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index 18975697fe..da9e84fa1b 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -4529,16 +4529,6 @@ declare namespace Office { */ Subject } - export interface AppointmentForm { - requiredAttendees: Array | Array; - optionalAttendees: Array | Array; - start: Date; - end: Date; - location: string; - resources: Array; - subject: string; - body: string; - } /** * Represents an attachment on an item from the server. Read mode only. * @@ -4608,6 +4598,23 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The body is provided in the requested format in the asyncResult.value property. */ getAsync(coercionType: CoercionType, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Returns the current body in a specified format. + * + * This method returns the entire current body in the format specified by coercionType. + * + * When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param coercionType The format for the returned body. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The body is provided in the requested format in the asyncResult.value property. + */ getAsync(coercionType: CoercionType, callback: (result: AsyncResult) => void): void; /** @@ -4646,8 +4653,60 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. */ prependAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds the specified content to the beginning of the item body. + * + * The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters. + * @param options Optional. 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 method. + * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. + */ prependAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + /** + * Adds the specified content to the beginning of the item body. + * + * The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. + */ prependAsync(data: string, callback: (result: AsyncResult) => void): void; + /** + * Adds the specified content to the beginning of the item body. + * + * The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * Applicable Outlook mode: Compose + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * @param data The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters. + */ prependAsync(data: string): void; /** * Replaces the entire body with the specified text. @@ -4674,8 +4733,72 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. */ setAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; + /** + * Replaces the entire body with the specified text. + * + * When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + * @param options Optional. 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 method. + * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. + */ setAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + /** + * Replaces the entire body with the specified text. + * + * When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. + */ setAsync(data: string, callback: (result: AsyncResult) => void): void; + /** + * Replaces the entire body with the specified text. + * + * When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + */ setAsync(data: string): void; /** @@ -4703,8 +4826,72 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. */ setSelectedDataAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; + /** + * Replaces the selection in the body with the specified text. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + * @param options Optional. 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 method. + * coercionType: The desired format for the body. The string in the data parameter will be converted to this format. + */ setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + /** + * Replaces the selection in the body with the specified text. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. Any errors encountered will be provided in the asyncResult.error property. + */ setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; + /** + * Replaces the selection in the body with the specified text. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content. + * + * When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor () to LPNoLP. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The data parameter is longer than 1,000,000 characters. + * + * InvalidFormatError - The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text. + * + * @param data The string that will replace the existing body. The string is limited to 1,000,000 characters. + */ setSelectedDataAsync(data: string): void; } /** @@ -4936,7 +5123,7 @@ declare namespace Office { * * Applicable Outlook mode: Compose or read */ - OWAView: string; + OWAView: "string"; } /** * Provides the email properties of the sender or specified recipients of an email message or appointment. @@ -5252,6 +5439,18 @@ declare namespace Office { start: Date; } export interface AppointmentForm { + /** + * Gets an object that provides methods for manipulating the body of an item. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + */ + body: string; /** * Gets or sets the date and time that the appointment is to end. * @@ -5315,6 +5514,7 @@ declare namespace Office { * Applicable Outlook mode: Compose or read */ optionalAttendees: string[] | EmailAddressDetails[]; + resources: string[]; /** * Provides access to the required attendees of an event. The type of object and level of access depends on the mode of the current item. * @@ -5531,8 +5731,87 @@ declare namespace Office { * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type asyncResult. On success, the attachment identifier will be provided in the asyncResult.value property. If uploading the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. */ addFileAttachmentAsync(uri: string, attachmentName: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds a file to a message or appointment as an attachment. + * + * The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: + * + * AttachmentSizeExceeded - The attachment is larger than allowed. + * + * FileTypeNotSupported - The attachment has an extension that is not allowed. + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param uri The URI that provides the location of the file to attach to the message or appointment. The maximum length is 2048 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + */ addFileAttachmentAsync(uri: string, attachmentName: string): void; + /** + * Adds a file to a message or appointment as an attachment. + * + * The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: + * + * AttachmentSizeExceeded - The attachment is larger than allowed. + * + * FileTypeNotSupported - The attachment has an extension that is not allowed. + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param uri The URI that provides the location of the file to attach to the message or appointment. The maximum length is 2048 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + * @param options Optional. 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 method. + * inInline: If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list. + */ addFileAttachmentAsync(uri: string, attachmentName: string, options: AsyncContextOptions): void; + /** + * Adds a file to a message or appointment as an attachment. + * + * The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: + * + * AttachmentSizeExceeded - The attachment is larger than allowed. + * + * FileTypeNotSupported - The attachment has an extension that is not allowed. + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param uri The URI that provides the location of the file to attach to the message or appointment. The maximum length is 2048 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type asyncResult. On success, the attachment identifier will be provided in the asyncResult.value property. If uploading the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. + */ addFileAttachmentAsync(uri: string, attachmentName: string, callback: (result: AsyncResult) => void): void; /** @@ -5562,8 +5841,80 @@ declare namespace Office { * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. On success, the attachment identifier will be provided in the asyncResult.value property. If adding the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. */ addItemAttachmentAsync(itemId: any, attachmentName: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds an Exchange item, such as a message, as an attachment to the message or appointment. + * + * The addItemAttachmentAsync method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback method, the method is called with one parameter, asyncResult, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback method, if needed. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * If your Office add-in is running in Outlook Web App, the addItemAttachmentAsync method can attach items to items other than the item that you are editing; however, this is not supported and is not recommended. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + */ addItemAttachmentAsync(itemId: any, attachmentName: string): void; - addItemAttachmentAsync(itemId: any, attachmentName: string, options: AsyncContextOptions): void; + /** + * Adds an Exchange item, such as a message, as an attachment to the message or appointment. + * + * The addItemAttachmentAsync method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback method, the method is called with one parameter, asyncResult, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback method, if needed. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * If your Office add-in is running in Outlook Web App, the addItemAttachmentAsync method can attach items to items other than the item that you are editing; however, this is not supported and is not recommended. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + * @param options 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 method. + */ + addItemAttachmentAsync(itemId: any, attachmentName: string, options: AsyncContextOptions): void; + /** + * Adds an Exchange item, such as a message, as an attachment to the message or appointment. + * + * The addItemAttachmentAsync method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback method, the method is called with one parameter, asyncResult, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback method, if needed. + * + * You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session. + * + * If your Office add-in is running in Outlook Web App, the addItemAttachmentAsync method can attach items to items other than the item that you are editing; however, this is not supported and is not recommended. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: + * + * NumberOfAttachmentsExceeded - The message or appointment has too many attachments. + * + * @param itemId The Exchange identifier of the item to attach. The maximum length is 100 characters. + * @param attachmentName The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. On success, the attachment identifier will be provided in the asyncResult.value property. If adding the attachment fails, the asyncResult object will contain an Error object that provides a description of the error. + */ addItemAttachmentAsync(itemId: any, attachmentName: string, callback: (result: AsyncResult) => void): void; /** @@ -5594,6 +5945,7 @@ declare namespace Office { * @remarks * * More information on [actionable messages]. + * * Minimum permission level: ReadItem * * Applicable Outlook mode: Read @@ -5670,8 +6022,62 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ removeAttachmentAsync(attachmentIndex: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes an attachment from a message or appointment. + * + * The removeAttachmentAsync method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook Web App and OWA for Devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing in an inline form and subsequently pops out the inline form to continue in a separate window. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param attachmentIndex The identifier of the attachment to remove. The maximum length of the string is 100 characters. + */ removeAttachmentAsync(attachmentIndex: string): void; + /** + * Removes an attachment from a message or appointment. + * + * The removeAttachmentAsync method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook Web App and OWA for Devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing in an inline form and subsequently pops out the inline form to continue in a separate window. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param attachmentIndex The identifier of the attachment to remove. The maximum length of the string is 100 characters. + * @param options Optional. 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 method. + */ removeAttachmentAsync(attachmentIndex: string, options: AsyncContextOptions): void; + /** + * Removes an attachment from a message or appointment. + * + * The removeAttachmentAsync method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook Web App and OWA for Devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing in an inline form and subsequently pops out the inline form to continue in a separate window. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param attachmentIndex The identifier of the attachment to remove. The maximum length of the string is 100 characters. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. + */ removeAttachmentAsync(attachmentIndex: string, callback: (result: AsyncResult) => void): void; /** @@ -5704,15 +6110,78 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ saveAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; - saveAsync(): void; - saveAsync(options: AsyncContextOptions): void; - saveAsync(callback: (result: AsyncResult) => void): void; /** - * Asynchronously inserts data into the body or subject of a message. + * Asynchronously saves an item. * - * The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content. + * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. * - * [Api set: Mailbox 1.2] + * Since appointments have no draft state, if saveAsync is called on an appointment in compose mode, the item will be saved as a normal appointment on the user's calendar. For new appointments that have not been saved before, no invitation will be sent. Saving an existing appointment will send an update to added or removed attendees. + * + * Note: If your add-in calls saveAsync on an item in compose mode in order to get an itemId to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the itemId will return an error. + * + * Note: The following clients have different behavior for saveAsync on appointments in compose mode: + * + * - Mac Outlook does not support saveAsync on a meeting in compose mode. Calling saveAsync on a meeting in Mac Outlook will return an error. + * + * - Outlook on the web always sends an invitation or update when saveAsync is called on an appointment in compose mode. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + */ + saveAsync(): void; + /** + * Asynchronously saves an item. + * + * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. + * + * Since appointments have no draft state, if saveAsync is called on an appointment in compose mode, the item will be saved as a normal appointment on the user's calendar. For new appointments that have not been saved before, no invitation will be sent. Saving an existing appointment will send an update to added or removed attendees. + * + * Note: If your add-in calls saveAsync on an item in compose mode in order to get an itemId to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the itemId will return an error. + * + * Note: The following clients have different behavior for saveAsync on appointments in compose mode: + * + * - Mac Outlook does not support saveAsync on a meeting in compose mode. Calling saveAsync on a meeting in Mac Outlook will return an error. + * + * - Outlook on the web always sends an invitation or update when saveAsync is called on an appointment in compose mode. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param options Optional. 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 method. + */ + saveAsync(options: AsyncContextOptions): void; + /** + * Asynchronously saves an item. + * + * When invoked, this method saves the current message as a draft and returns the item id via the callback method. In Outlook Web App or Outlook in online mode, the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache. + * + * Since appointments have no draft state, if saveAsync is called on an appointment in compose mode, the item will be saved as a normal appointment on the user's calendar. For new appointments that have not been saved before, no invitation will be sent. Saving an existing appointment will send an update to added or removed attendees. + * + * Note: If your add-in calls saveAsync on an item in compose mode in order to get an itemId to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the itemId will return an error. + * + * Note: The following clients have different behavior for saveAsync on appointments in compose mode: + * + * - Mac Outlook does not support saveAsync on a meeting in compose mode. Calling saveAsync on a meeting in Mac Outlook will return an error. + * + * - Outlook on the web always sends an invitation or update when saveAsync is called on an appointment in compose mode. + * + * [Api set: Mailbox 1.3] * * @remarks * @@ -5722,13 +6191,9 @@ declare namespace Office { * * Errors: InvalidAttachmentId - The attachment identifier does not exist. * - * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ - setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; - setSelectedDataAsync(data: string): void; - setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; - setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; + saveAsync(callback: (result: AsyncResult) => void): void; /** * Asynchronously inserts data into the body or subject of a message. * @@ -5750,8 +6215,65 @@ declare namespace Office { * coercionType: If text, the current style is applied in Outlook Web App and Outlook. If the field is an HTML editor, only the text data is inserted, even if the data is HTML. If html and the field supports HTML (the subject doesn't), the current style is applied in Outlook Web App and the default style is applied in Outlook. If the field is a text field, an InvalidDataFormat error is returned. If coercionType is not set, the result depends on the field: if the field is HTML then HTML is used; if the field is text, then plain text is used. * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. */ - setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions, callback: (result: AsyncResult) => void): void; - + setSelectedDataAsync(data: string, options?: AsyncContextOptions & CoercionTypeOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously inserts data into the body or subject of a message. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content. + * + * [Api set: Mailbox 1.2] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. + */ + setSelectedDataAsync(data: string): void; + /** + * Asynchronously inserts data into the body or subject of a message. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content. + * + * [Api set: Mailbox 1.2] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. + * @param options Optional. 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 method. + * coercionType: If text, the current style is applied in Outlook Web App and Outlook. If the field is an HTML editor, only the text data is inserted, even if the data is HTML. If html and the field supports HTML (the subject doesn't), the current style is applied in Outlook Web App and the default style is applied in Outlook. If the field is a text field, an InvalidDataFormat error is returned. If coercionType is not set, the result depends on the field: if the field is HTML then HTML is used; if the field is text, then plain text is used. + */ + setSelectedDataAsync(data: string, options: AsyncContextOptions & CoercionTypeOptions): void; + /** + * Asynchronously inserts data into the body or subject of a message. + * + * The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content. + * + * [Api set: Mailbox 1.2] + * + * @remarks + * + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidAttachmentId - The attachment identifier does not exist. + * + * @param data The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure. + */ + setSelectedDataAsync(data: string, callback: (result: AsyncResult) => void): void; } export interface ItemRead extends Item { /** @@ -5795,7 +6317,7 @@ declare namespace Office { * * The itemId property is not available in compose mode. If an item identifier is required, the saveAsync method can be used to save the item to the store, which will return the item identifier in the AsyncResult.value parameter in the callback function. * - * Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * + * Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in. * * [Api set: Mailbox 1.0] * @@ -6279,13 +6801,27 @@ declare namespace Office { * Applicable Outlook mode: Compose */ getAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the location of an appointment. + * + * The getAsync method starts an asynchronous call to the Exchange server to get the location of an appointment. The location of the appointment is provided as a string in the asyncResult.value property. + * + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose + */ getAsync(callback: (result: AsyncResult) => void): void; /** * Sets the location of an appointment. * * The setAsync method starts an asynchronous call to the Exchange server to set the location of an appointment. Setting the location of an appointment overwrites the current location. * - * @param data The location of the appointment. The string is limited to 255 characters. + * @param location The location of the appointment. The string is limited to 255 characters. * @param options Optional. 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 method. * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the location fails, the asyncResult.error property will contain an error code. @@ -6300,8 +6836,59 @@ declare namespace Office { * Errors: DataExceedsMaximumSize - The location parameter is longer than 255 characters. */ setAsync(location: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets the location of an appointment. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the location of an appointment. Setting the location of an appointment overwrites the current location. + * + * @param location The location of the appointment. The string is limited to 255 characters. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The location parameter is longer than 255 characters. + */ setAsync(location: string): void; + /** + * Sets the location of an appointment. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the location of an appointment. Setting the location of an appointment overwrites the current location. + * + * @param location The location of the appointment. The string is limited to 255 characters. + * @param options Optional. 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 method. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The location parameter is longer than 255 characters. + */ setAsync(location: string, options: AsyncContextOptions): void; + /** + * Sets the location of an appointment. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the location of an appointment. Setting the location of an appointment overwrites the current location. + * + * @param location The location of the appointment. The string is limited to 255 characters. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the location fails, the asyncResult.error property will contain an error code. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The location parameter is longer than 255 characters. + */ setAsync(location: string, callback: (result: AsyncResult) => void): void; } @@ -6530,15 +7117,7 @@ declare namespace Office { * * Applicable Outlook mode: Read * - * @param parameters A dictionary of parameters describing the new appointment. All parameters are optional. - * requiredAttendees: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the required attendees for the appointment. The array is limited to a maximum of 100 entries. - * optionalAttendees: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the optional attendees for the appointment. The array is limited to a maximum of 100 entries. - * start: A Date object specifying the start date and time of the appointment. - * end: A Date object specifying the end date and time of the appointment. - * location: A string containing the location of the appointment. The string is limited to a maximum of 255 characters. - * resources: An array of strings containing the resources required for the appointment. The array is limited to a maximum of 100 entries. - * subject: A string containing the subject of the appointment. The string is limited to a maximum of 255 characters. - * body: The body of the appointment. The body content is limited to a maximum size of 32 KB. + * @param parameters An AppointmentForm describing the new appointment. All properties are optional. */ displayNewAppointmentForm(parameters: AppointmentForm): void; /** @@ -6597,27 +7176,22 @@ declare namespace Office { * * Applicable Outlook mode: Compose and read * + * @param options An object literal that contains one or more of the following properties. + * isRest: Determines if the token provided will be used for the Outlook REST APIs or Exchange Web Services. Default value is false. + * asyncContext: Any state data that is passed to the asynchronous method. * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The token is provided as a string in the asyncResult.value property. */ - getCallbackTokenAsync(callback: (result: AsyncResult) => void): void; + getCallbackTokenAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; /** - * Gets a string that contains a token used to call REST APIs or Exchange Web Services. + * Gets a string that contains a token used to get an attachment or item from an Exchange Server. * * The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes. * - * *REST Tokens* + * You can pass the token and an attachment identifier or item identifier to a third-party system. The third-party system uses the token as a bearer authorization token to call the Exchange Web Services (EWS) GetAttachment or GetItem operation to return an attachment or item. For example, you can create a remote service to get attachments from the selected item. * - * When a REST token is requested (options.isRest = true), the resulting token will not work to authenticate Exchange Web Services calls. The token will be limited in scope to read-only access to the current item and its attachments, unless the add-in has specified the ReadWriteMailbox permission in its manifest. If the ReadWriteMailbox permission is specified, the resulting token will grant read/write access to mail, calendar, and contacts, including the ability to send mail. + * Your app must have the ReadItem permission specified in its manifest to call the getCallbackTokenAsync method in read mode. * - * The add-in should use the restUrl property to determine the correct URL to use when making REST API calls. - * - * *EWS Tokens* - * - * When an EWS token is requested (options.isRest = false), the resulting token will not work to authenticate REST API calls. The token will be limited in scope to accessing the current item. - * - * The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls. - * - * Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible. + * In compose mode you must call the saveAsync method to get an item identifier to pass to the getCallbackTokenAsync method. Your app must have ReadWriteItem permissions to call the saveAsync method. * * [Api set: Mailbox 1.5] * @@ -6627,12 +7201,9 @@ declare namespace Office { * * Applicable Outlook mode: Compose and read * - * @param options An object literal that contains one or more of the following properties. - * isRest: Determines if the token provided will be used for the Outlook REST APIs or Exchange Web Services. Default value is false. - * asyncContext: Any state data that is passed to the asynchronous method. * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. The token is provided as a string in the asyncResult.value property. */ - getCallbackTokenAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; + getCallbackTokenAsync(callback: (result: AsyncResult) => void): void; /** * Gets a string that contains a token used to get an attachment or item from an Exchange Server. * @@ -6773,19 +7344,19 @@ declare namespace Office { */ key?: string; /** - * The type of notification message. + * Specifies the Office.MailboxEnums.ItemNotificationMessageType of message. If type is ProgressIndicator or ErrorMessage, an icon is automatically supplied and the message is not persistent. Therefore the icon and persistent properties are not valid for these types of messages. Including them will result in an ArgumentException. If type is ProgressIndicator, the developer should remove or replace the progress indicator when the action is complete. */ type: Office.MailboxEnums.ItemNotificationMessageType; /** - * The resource identifier of the icon used for the message. Only applicable when type is InformationalMessage. + * A reference to an icon that is defined in the manifest in the Resources section. It appears in the infobar area. It is only applicable if the type is InformationalMessage. Specifying this parameter for an unsupported type results in an exception. */ icon?: string; /** - * This is the text of the message. Maximum length is 150 characters. + * The text of the notification message. Maximum length is 150 characters. If the developer passes in a longer string, an ArgumentOutOfRange exception is thrown. */ message: string; /** - * If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. Only applicable when type is InformationalMessage. + * Only applicable when type is InformationalMessage. If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. For error notifications, the message persists until the user sees it once. Specifying this parameter for an unsupported type throws an exception. */ persistent?: Boolean; } @@ -6806,11 +7377,7 @@ declare namespace Office { * There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error. * * @param key 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. - * @param JSONmessage A JSON object that contains the notification message to be added to the item. It consists of the following properties. - * type: Specifies the Office.MailboxEnums.ItemNotificationMessageType of message. If type is ProgressIndicator or ErrorMessage, an icon is automatically supplied and the message is not persistent. Therefore the icon and persistent properties are not valid for these types of messages. Including them will result in an ArgumentException. If type is ProgressIndicator, the developer should remove or replace the progress indicator when the action is complete. - * icon: A reference to an icon that is defined in the manifest in the Resources section. It appears in the infobar area. It is only applicable if the type is InformationalMessage. Specifying this parameter for an unsupported type results in an exception. - * message: The text of the notification message. Maximum length is 150 characters. If the developer passes in a longer string, an ArgumentOutOfRange exception is thrown. - * persistent: Only applicable when type is InformationalMessage. If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. For error notifications, the message persists until the user sees it once. Specifying this parameter for an unsupported type throws an exception. + * @param JSONmessage A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object. * @param options Optional. 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 method. * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. @@ -6823,10 +7390,57 @@ declare namespace Office { * Applicable Outlook mode: Compose or read */ addAsync(key: string, JSONmessage: NotificationMessageDetails, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds a notification to an item. + * + * There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error. + * + * @param key 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. + * @param JSONmessage A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + */ addAsync(key: string, JSONmessage: NotificationMessageDetails): void; + /** + * Adds a notification to an item. + * + * There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error. + * + * @param key 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. + * @param JSONmessage A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object. + * @param options Optional. 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 method. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + */ addAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions): void; + /** + * Adds a notification to an item. + * + * There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error. + * + * @param key 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. + * @param JSONmessage A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + */ addAsync(key: string, JSONmessage: NotificationMessageDetails, callback: (result: AsyncResult) => void): void; - /** * Returns all keys and messages for an item. * @@ -6842,8 +7456,19 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAllAsync(options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Returns all keys and messages for an item. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. + */ getAllAsync(callback: (result: AsyncResult) => void): void; - /** * Removes a notification message for an item. * @@ -6860,10 +7485,48 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ removeAsync(key: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes a notification message for an item. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to remove. + */ removeAsync(key: string): void; + /** + * Removes a notification message for an item. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to remove. + * @param options Optional. 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 method. + */ removeAsync(key: string, options: AsyncContextOptions): void; + /** + * Removes a notification message for an item. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to remove. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. + */ removeAsync(key: string, callback: (result: AsyncResult) => void): void; - /** * Replaces a notification message that has a given key with another message. * @@ -6877,18 +7540,62 @@ declare namespace Office { * Applicable Outlook mode: Compose or read * * @param key The key for the notification message to replace. It can't be longer than 32 characters. - * @param JSONmessage A JSON object that contains the new notification message to replace the existing message. It consists of the following properties. - * type: Specifies the Office.MailboxEnums.ItemNotificationMessageType of message. If type is ProgressIndicator or ErrorMessage, an icon is automatically supplied and the message is not persistent. Therefore the icon and persistent properties are not valid for these types of messages. Including them will result in an ArgumentException. If type is ProgressIndicator, the developer should remove or replace the progress indicator when the action is complete. - * icon: A reference to an icon that is defined in the manifest in the Resources section. It appears in the infobar area. It is only applicable if the type is InformationalMessage. Specifying this parameter for an unsupported type results in an exception. - * message: The text of the notification message. Maximum length is 150 characters. If the developer passes in a longer string, an ArgumentOutOfRange exception is thrown. - * persistent: Only applicable when type is InformationalMessage. If true, the message remains until removed by this add-in or dismissed by the user. If false, it is removed when the user navigates to a different item. For error notifications, the message persists until the user sees it once. Specifying this parameter for an unsupported type throws an exception. + * @param JSONmessage A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object. * @param options Optional. 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 method. * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * 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. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to replace. It can't be longer than 32 characters. + * @param JSONmessage A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object. + */ replaceAsync(key: string, JSONmessage: NotificationMessageDetails): void; + /** + * 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. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to replace. It can't be longer than 32 characters. + * @param JSONmessage A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object. + * @param options Optional. 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 method. + */ replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options: AsyncContextOptions): void; + /** + * 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. + * + * [Api set: Mailbox 1.3] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose or read + * + * @param key The key for the notification message to replace. It can't be longer than 32 characters. + * @param JSONmessage A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. + */ replaceAsync(key: string, JSONmessage: NotificationMessageDetails, callback: (result: AsyncResult) => void): void; } /** @@ -6952,8 +7659,77 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If adding the recipients fails, the asyncResult.error property will contain an error code. */ addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds a recipient list to the existing recipients for an appointment or message. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + */ addAsync(recipients: (string | EmailUser | EmailAddressDetails)[]): void; + /** + * Adds a recipient list to the existing recipients for an appointment or message. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + * @param options Optional. 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 method. + */ addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: AsyncContextOptions): void; + /** + * Adds a recipient list to the existing recipients for an appointment or message. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If adding the recipients fails, the asyncResult.error property will contain an error code. + */ addAsync(recipients: (string | EmailUser | EmailAddressDetails)[], callback: (result: AsyncResult) => void): void; /** @@ -6988,7 +7764,6 @@ declare namespace Office { * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - /** * Sets a recipient list for an appointment or message. * @@ -7017,8 +7792,83 @@ declare namespace Office { * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the recipients fails the asyncResult.error property will contain a code that indicates any error that occurred while adding the data. */ setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets a recipient list for an appointment or message. + * + * The setAsync method overwrites the current recipient list. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + */ setAsync(recipients: (string | EmailUser | EmailAddressDetails)[]): void; + /** + * Sets a recipient list for an appointment or message. + * + * The setAsync method overwrites the current recipient list. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + * @param options Optional. 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 method. + */ setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], options: AsyncContextOptions): void; + /** + * Sets a recipient list for an appointment or message. + * + * The setAsync method overwrites the current recipient list. + * + * The recipients parameter can be an array of one of the following: + * + * - Strings containing SMTP email addresses + * + * - EmailUser objects + * + * - EmailAddressDetails objects + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: NumberOfRecipientsExceeded - The number of recipients exceeded 100 entries. + * + * @param recipients The recipients to add to the recipients list. + * @param callback Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the recipients fails the asyncResult.error property will contain a code that indicates any error that occurred while adding the data. + */ setAsync(recipients: (string | EmailUser | EmailAddressDetails)[], callback: (result: AsyncResult) => void): void; } @@ -7158,7 +8008,6 @@ declare namespace Office { * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - /** * Sets the subject of an appointment or message. * @@ -7179,8 +8028,59 @@ declare namespace Office { * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the subject fails, the asyncResult.error property will contain an error code. */ setAsync(subject: string, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets the subject of an appointment or message. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the subject of an appointment or message. Setting the subject overwrites the current subject, but leaves any prefixes, such as "Fwd:" or "Re:" in place. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The subject parameter is longer than 255 characters. + * + * @param subject The subject of the appointment or message. The string is limited to 255 characters. + */ setAsync(data: string): void; + /** + * Sets the subject of an appointment or message. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the subject of an appointment or message. Setting the subject overwrites the current subject, but leaves any prefixes, such as "Fwd:" or "Re:" in place. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The subject parameter is longer than 255 characters. + * + * @param subject The subject of the appointment or message. The string is limited to 255 characters. + * @param options 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 method. + */ setAsync(data: string, options: AsyncContextOptions): void; + /** + * Sets the subject of an appointment or message. + * + * The setAsync method starts an asynchronous call to the Exchange server to set the subject of an appointment or message. Setting the subject overwrites the current subject, but leaves any prefixes, such as "Fwd:" or "Re:" in place. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadItem + * + * Applicable Outlook mode: Compose + * + * Errors: DataExceedsMaximumSize - The subject parameter is longer than 255 characters. + * + * @param subject The subject of the appointment or message. The string is limited to 255 characters. + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the subject fails, the asyncResult.error property will contain an error code. + */ setAsync(data: string, callback: (result: AsyncResult) => void): void; } @@ -7249,7 +8149,6 @@ declare namespace Office { * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. */ getAsync(options: AsyncContextOptions, callback: (result: AsyncResult) => void): void; - /** * Sets the start or end time of an appointment. * @@ -7272,8 +8171,65 @@ declare namespace Office { * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the date and time fails, the asyncResult.error property will contain an error code. */ setAsync(dateTime: Date, options?: AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets the start or end time of an appointment. + * + * If the setAsync method is called on the start property, the end property will be adjusted to maintain the duration of the appointment as previously set. If the setAsync method is called on the end property, the duration of the appointment will be extended to the new end time. + * + * The time must be in UTC; you can get the correct UTC time by using the convertToUtcClientTime method. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidEndTime - The appointment end time is before the appointment start time. + * + * @param dateTime A date-time object in Coordinated Universal Time (UTC). + */ setAsync(dateTime: Date): void; + /** + * Sets the start or end time of an appointment. + * + * If the setAsync method is called on the start property, the end property will be adjusted to maintain the duration of the appointment as previously set. If the setAsync method is called on the end property, the duration of the appointment will be extended to the new end time. + * + * The time must be in UTC; you can get the correct UTC time by using the convertToUtcClientTime method. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidEndTime - The appointment end time is before the appointment start time. + * + * @param dateTime A date-time object in Coordinated Universal Time (UTC). + * @param options 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 method. + */ setAsync(dateTime: Date, options: AsyncContextOptions): void; + /** + * Sets the start or end time of an appointment. + * + * If the setAsync method is called on the start property, the end property will be adjusted to maintain the duration of the appointment as previously set. If the setAsync method is called on the end property, the duration of the appointment will be extended to the new end time. + * + * The time must be in UTC; you can get the correct UTC time by using the convertToUtcClientTime method. + * + * [Api set: Mailbox 1.1] + * + * @remarks + * Minimum permission level: ReadWriteItem + * + * Applicable Outlook mode: Compose + * + * Errors: InvalidEndTime - The appointment end time is before the appointment start time. + * + * @param dateTime A date-time object in Coordinated Universal Time (UTC). + * @param callback When the method completes, the function passed in the callback parameter is called with a single parameter of type AsyncResult. If setting the date and time fails, the asyncResult.error property will contain an error code. + */ setAsync(dateTime: Date, callback: (result: AsyncResult) => void): void; }