Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Outlook add-in API subset of the Office JavaScript API includes objects, methods, properties, and events that you can use in an Outlook add-in. Outlook JavaScript API 1.1 (Mailbox 1.1) is the first version of the API.
Note
This documentation is for a requirement set other than the latest requirement set.
What's new in 1.1
Mailbox requirement set 1.1 includes all of the Common API requirement sets supported in Outlook. It added the following features.
Added methods to get or set the body of messages and appointments. For more information, see Get or set the body of a message or appointment in Outlook.
Added methods to add, get, and remove attachments from messages and appointments being composed. For more information, see Manage an item's attachments in a compose form in Outlook.
Added methods to get or set the subject of messages and appointments being composed. For more information, see Get or set the subject when composing an appointment or message in Outlook.
Added methods to get or set the location of appointments being composed. For more information, see Get or set the location when composing an appointment in Outlook.
Added methods to get or set the start time and end time of appointments being composed. For more information, see Get or set the time when composing an appointment in Outlook.
Added methods to get or set the recipients (To, Cc, Bcc) of messages being composed. For more information, see Get, set, or add recipients to an appointment or message in Outlook.
Added methods to display reply forms and new appointment forms.
Added methods to display existing messages and appointments.
Added the ability to make Exchange Web Services (EWS) requests directly from an add-in.
Important
Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication (NAA). Exchange user identity tokens are still supported for Exchange on-premises.
Added support for custom properties and roaming settings to store add-in data. For more information, see Get and set add-in metadata for an Outlook add-in.
Added methods to detect and extract entities (such as addresses, phone numbers, and URLs) from item bodies.
Important
This element or attribute value is documented to assist developers troubleshooting existing contextual Outlook add-ins. We recommend that you not create new contextual Outlook add-ins.
- Entity-based contextual Outlook add-ins are now retired.
- Scenarios that previously required regular expression rules in contextual add-ins can now be implemented with Event-based Outlook add-ins, which are activated automatically in response to events such as creating a new message or meeting. JavaScript has built-in support for regular expressions, and you can also reference JavaScript libraries that provide advanced regular expression functionality. Unlike contextual add-ins, Event-based add-ins can work in compose contexts as well as read mode.
API list
The following table lists the APIs introduced in Mailbox requirement set 1.1. To view API reference documentation for all APIs supported by Mailbox requirement set 1.1, see Outlook APIs.
| Class | Fields | Description |
|---|---|---|
| AppointmentCompose | addFileAttachmentAsync(uri: string, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds a file to a message or appointment as an attachment. |
| addFileAttachmentAsync(uri: string, attachmentName: string, options: Office.AsyncContextOptions & { isInline: boolean }, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds a file to a message or appointment as an attachment. | |
| addItemAttachmentAsync(itemId: any, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds an Exchange item, such as a message, as an attachment to the message or appointment. | |
| addItemAttachmentAsync(itemId: any, attachmentName: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds an Exchange item, such as a message, as an attachment to the message or appointment. | |
| body | Gets an object that provides methods for manipulating the body of an item. | |
| loadCustomPropertiesAsync(callback: (asyncResult: Office.AsyncResult<CustomProperties>) => void, userContext?: any) | Asynchronously loads custom properties for this add-in on the selected item. | |
| location | Gets or sets the location of an appointment. | |
| removeAttachmentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Removes an attachment from a message or appointment. | |
| removeAttachmentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Removes an attachment from a message or appointment. | |
| AppointmentForm | body | Sets the body of the appointment. |
| end | Sets the date and time that the appointment is to end. | |
| location | Sets the location of the appointment. | |
| optionalAttendees | Sets the optional attendees of the appointment. | |
| requiredAttendees | Sets the required attendees of the appointment. | |
| resources | Sets the resources of the appointment. | |
| start | Sets the date and time that the appointment is to begin. | |
| subject | Sets the description that appears in the Title field of the appointment. | |
| AppointmentRead | body | Gets an object that provides methods for manipulating the body of an item. |
| dateTimeModified | Gets the date and time that an item was last modified. | |
| displayReplyAllForm(formData: string | ReplyFormData) | Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the | |
| displayReplyForm(formData: string | ReplyFormData) | Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment. | |
| getEntities() | Gets the entities found in the selected item's body. | |
| getEntitiesByType(entityType: MailboxEnums.EntityType | string) | Gets an array of all the entities of the specified entity type found in the selected item's body. | |
| getFilteredEntitiesByName(name: string) | Returns well-known entities in the selected item that pass the named filter defined in an add-in only manifest file. | |
| getRegExMatches() | Returns string values in the selected item that match the regular expressions defined in an add-in only manifest file. | |
| getRegExMatchesByName(name: string) | Returns string values in the selected item that match the named regular expression defined in an add-in only manifest file. | |
| loadCustomPropertiesAsync(callback: (asyncResult: Office.AsyncResult<CustomProperties>) => void, userContext?: any) | Asynchronously loads custom properties for this add-in on the selected item. | |
| location | Gets the location of an appointment. | |
| AttachmentDetails | attachmentType | Gets a value that indicates the attachment's type. |
| contentType | Gets the MIME content type of the attachment. | |
| id | Gets the Exchange attachment ID of the attachment. | |
| isInline | Gets a value that indicates whether the attachment appears as an image in the body of the item instead of in the attachment list. | |
| name | Gets the name of the attachment. | |
| size | Gets the size of the attachment in bytes. | |
| Body | getTypeAsync(callback?: (asyncResult: Office.AsyncResult<Office.CoercionType>) => void) | Gets a value that indicates whether the content is in HTML or text format. |
| getTypeAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<Office.CoercionType>) => void) | Gets a value that indicates whether the content is in HTML or text format. | |
| prependAsync(data: string, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Adds the specified content to the beginning of the item body. | |
| prependAsync(data: string, options: Office.AsyncContextOptions & CoercionTypeOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Adds the specified content to the beginning of the item body. | |
| setSelectedDataAsync(data: string, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Replaces the selection in the body with the specified text. | |
| setSelectedDataAsync(data: string, options: Office.AsyncContextOptions & CoercionTypeOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Replaces the selection in the body with the specified text. | |
| CustomProperties | get(name: string) | Returns the value of the specified custom property. |
| remove(name: string) | Removes the specified property from the custom property collection. | |
| saveAsync(asyncContext?: any) | Saves custom properties to a message or appointment. | |
| saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any) | Saves custom properties to a message or appointment. | |
| set(name: string, value: string) | Sets the specified property to the specified value. | |
| Diagnostics | OWAView | Gets a string that represents the current view of Outlook on the web. |
| hostName | Gets a string that represents the type of Outlook client. | |
| hostVersion | Gets a string that represents the version of either the Outlook client or the Exchange Server (for example, "15.0.468.0"). | |
| Location | getAsync(callback: (asyncResult: Office.AsyncResult<string>) => void) | Gets the location of an appointment. |
| getAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void) | Gets the location of an appointment. | |
| setAsync(location: string, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Sets the location of an appointment. | |
| setAsync(location: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Sets the location of an appointment. | |
| Mailbox | displayAppointmentForm(itemId: string) | Displays an existing calendar appointment. |
| displayMessageForm(itemId: string) | Displays an existing message. | |
| displayNewAppointmentForm(parameters: AppointmentForm) | Displays a form for creating a new calendar appointment. | |
| ewsUrl | Gets the URL of the Exchange Web Services (EWS) endpoint for this email account. | |
| makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any) | Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user's mailbox. | |
| MessageCompose | addFileAttachmentAsync(uri: string, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds a file to a message or appointment as an attachment. |
| addFileAttachmentAsync(uri: string, attachmentName: string, options: Office.AsyncContextOptions & { isInline: boolean }, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds a file to a message or appointment as an attachment. | |
| addItemAttachmentAsync(itemId: any, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds an Exchange item, such as a message, as an attachment to the message or appointment. | |
| addItemAttachmentAsync(itemId: any, attachmentName: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<string>) => void) | Adds an Exchange item, such as a message, as an attachment to the message or appointment. | |
| bcc | Gets an object that provides methods to get or update the recipients on the Bcc (blind carbon copy) line of a message. | |
| body | Gets an object that provides methods for manipulating the body of an item. | |
| loadCustomPropertiesAsync(callback: (asyncResult: Office.AsyncResult<CustomProperties>) => void, userContext?: any) | Asynchronously loads custom properties for this add-in on the selected item. | |
| removeAttachmentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Removes an attachment from a message or appointment. | |
| removeAttachmentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Removes an attachment from a message or appointment. | |
| MessageRead | body | Gets an object that provides methods for manipulating the body of an item. |
| dateTimeModified | Gets the date and time that an item was last modified. | |
| displayReplyAllForm(formData: string | ReplyFormData) | Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the | |
| displayReplyForm(formData: string | ReplyFormData) | Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment. | |
| getEntities() | Gets the entities found in the selected item's body. | |
| getEntitiesByType(entityType: MailboxEnums.EntityType | string) | Gets an array of all the entities of the specified entity type found in the selected item's body. | |
| getFilteredEntitiesByName(name: string) | Returns well-known entities in the selected item that pass the named filter defined in an add-in only manifest file. | |
| getRegExMatches() | Returns string values in the selected item that match the regular expressions defined in an add-in only manifest file. | |
| getRegExMatchesByName(name: string) | Returns string values in the selected item that match the named regular expression defined in an add-in only manifest file. | |
| loadCustomPropertiesAsync(callback: (asyncResult: Office.AsyncResult<CustomProperties>) => void, userContext?: any) | Asynchronously loads custom properties for this add-in on the selected item. | |
| AttachmentType | Cloud | The attachment is stored in a cloud location, such as OneDrive. |
| File | The attachment is a file. | |
| Item | The attachment is an Exchange item. | |
| RecipientType | DistributionList | Specifies the recipient is a distribution list containing a list of email addresses. |
| ExternalUser | Specifies the recipient is an SMTP email address that isn't on the Exchange server. | |
| Other | Specifies the recipient isn't one of the other recipient types. | |
| User | Specifies the recipient is an SMTP email address on the Exchange server. | |
| Recipients | addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Adds a recipient list to the existing recipients for an appointment or message. |
| addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Adds a recipient list to the existing recipients for an appointment or message. | |
| getAsync(callback: (asyncResult: Office.AsyncResult<EmailAddressDetails[]>) => void) | Gets a recipient list for an appointment or message. | |
| getAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<EmailAddressDetails[]>) => void) | Gets a recipient list for an appointment or message. | |
| setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback: (asyncResult: Office.AsyncResult<void>) => void) | Sets a recipient list for an appointment or message. | |
| setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<void>) => void) | Sets a recipient list for an appointment or message. | |
| ReplyFormAttachment | inLine | If true, indicates that the attachment will be shown inline in the message body and shouldn't be displayed in the attachment list. |
| itemId | The EWS item ID of the attachment. | |
| name | A string that contains the name of the attachment, up to 255 characters in length. | |
| type | Indicates the type of attachment. | |
| url | The URI of the location for the file. | |
| ReplyFormData | callback | When the reply display call completes, the function passed in the callback parameter is called with a single parameter, |
| htmlBody | A string that contains text and HTML and that represents the body of the reply form. | |
| options | An object literal that contains the asyncContext property. |
|
| RoamingSettings | get(name: string) | Retrieves the specified setting. |
| remove(name: string) | Removes the specified setting. | |
| saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void) | Saves the settings. | |
| set(name: string, value: any) | Sets or creates the specified setting. | |
| Subject | getAsync(callback: (asyncResult: Office.AsyncResult<string>) => void) | Gets the subject of an appointment or message. |
| getAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void) | Gets the subject of an appointment or message. | |
| setAsync(subject: string, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Sets the subject of an appointment or message. | |
| setAsync(subject: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Sets the subject of an appointment or message. | |
| Time | getAsync(callback: (asyncResult: Office.AsyncResult<Date>) => void) | Gets the start or end time of an appointment. |
| getAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<Date>) => void) | Gets the start or end time of an appointment. | |
| setAsync(dateTime: Date, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Sets the start or end time of an appointment. | |
| setAsync(dateTime: Date, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void) | Sets the start or end time of an appointment. |
See also
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins