Share via

[DEPRECATED] Resource reference for the Mail, Calendar, Contacts, and Task REST APIs (beta)

  • Article

Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Note

The beta version of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. Consequently, the beta REST endpoint is also deprecated and will be fully decommissioned in November 2022. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

This article describes the REST API entities, properties, complex types, enumerations, and OData query parameters that you can use with the Outlook Mail, Calendar, Contacts, and Task API to access user mailbox data in Office 365, Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.

Note

For simplicity of reference, the rest of this article uses Outlook.com to include these Microsoft account domains.

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.

Not interested in the beta version of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.

Tip

You can view the complete metadata document for the Mail, Calendar, Contacts, and Task entity data model by navigating to the $metadata endpoint in a web browser (example: https://outlook.office.com/api/beta/$metadata).

Attachment

A file, item (contact, event or message), or link to a file or folder, which is attached to an event, message, or task. The corresponding fileAttachment, itemAttachment, and referenceAttachment resources are all derived from the Attachment resource.

Type: Microsoft.OutlookServices.Entity

Property Type Description Writable? Filterable?
ContentType String The MIME type of the attachment. Yes No
IsInline Boolean true if the attachment is an inline attachment; otherwise, false. Yes Yes
LastModifiedDateTime DateTimeOffset The date and time when the attachment was last modified. The date and time use ISO 8601 format and is always in UTC time.

For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'		 No Yes
Name String The display name of the attachment. This does not need to be the actual file name. Yes Yes
Size Int32 The length of the attachment in bytes. No No

Calendar

A calendar that is a container for events.

Type: Microsoft.OutlookServices.Calendar

A Calendar collection returns an array of calendars in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/calendars/$count

See Calendar operations for supported actions.

Property Type Description Writable? Filterable?
CanEdit Boolean True if the user can write to the calendar, false otherwise. This property is true for the user who created the calendar. This property is also true for a user who has been shared a calendar and granted write access. No Yes
CanShare Boolean True if the user has the permission to share the calendar, false otherwise. Only the user who created the calendar can share it. No Yes
CanViewPrivateItems Boolean True if the user can read calendar items that have been marked private, false otherwise. No Yes
ChangeKey String Identifies the version of the calendar object. Every time the calendar is changed, ChangeKey changes as well. This allows Exchange to apply changes to the correct version of the object. No No
Color CalendarColor Specifies the color theme to distinguish the calendar from other calendars in a UI. The property values are: LightBlue=0, LightGreen=1, LightOrange=2, LightGray=3, LightYellow=4, LightTeal=5, LightPink=6, LightBrown=7, LightRed=8, MaxColor=9, Auto=-1 Yes Yes
Id String The calendar's unique identifier. No No
IsDefaultCalendar Boolean True if this calendar is the user's default calendar, false otherwise. Yes Yes
IsShared Boolean True if the user has shared the calendar with other users, false otherwise. Since only the user who created the calendar can share it, IsShared and IsSharedWithMe cannot be true for the same user. No Yes
IsSharedWithMe Boolean True if the user has been shared this calendar, false otherwise. This property is always false for a calendar owner. No Yes
Name String The calendar name. Yes Yes
Owner EmailAddress If set, this represents the user who created or added the calendar. For a calendar that the user created or added, the Owner property is set to the user. For a calendar shared with the user, the Owner property is set to the person who shared that calendar with the user. No Yes
CalendarView Collection(Event) The calendar view for the calendar. Navigation property. No No
Events Collection(Event) The events in the calendar. Navigation property. No No
MultiValueExtendedProperties A collection A collection of multi-value extended properties of type MultiValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes
SingleValueExtendedProperties A collection A collection of single-value extended properties of type SingleValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes

CalendarGroup

A group of calendars.

Note

Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut. You cannot delete that calendar group.

Type: Microsoft.OutlookServices.CalendarGroup

A CalendarGroup collection returns an array of calendar groups in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/calendargroups/$count

See CalendarGroup operations for supported actions.

Property Type Description Writable? Filterable?
Name String The group name. Yes Yes
ChangeKey String Identifies the version of the calendar group. Every time the calendar group is changed, ChangeKey changes as well. This allows Exchange to apply changes to the correct version of the object. No No
ClassId String The class identifier. No Yes
Id String The calendar group's unique identifier. No No
Calendars Collection(Calendar) The calendars in the calendar group. Navigation property. No No

Contact

A contact, which is an item in Outlook for users to organize and save information about the people and organizations that they communicate with. Contacts are contained in contact folders.

Type: Microsoft.OutlookServices.Contact

A Contact collection returns an array of contacts in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/contacts/$count

See Contact operations for supported actions.

Property Type Description Writable? Filterable?
AssistantName String The name of the contact's assistant. Yes Yes
Birthday datetimeoffset The contact's birthday. Yes Yes
Categories Collection(String) The categories associated with the contact. Yes No
ChangeKey String Identifies the version of the contact. Every time the contact is changed, ChangeKey changes as well. This allows Exchange to apply changes to the correct version of the object. No No
Children Collection(String) The names of the contact's children. Yes Yes
CompanyName String The name of the contact's company. Yes Yes
CreatedDateTime datetimeoffset The time the contact was created. No Yes
Department String The contact's department. Yes Yes
DisplayName String The contact's display name. Yes Yes
EmailAddresses Collection(EmailAddress) The contact's email addresses. Yes No
Extensions Collection(Extension) The collection of open type data extensions defined for the contact. Navigation property. No Yes
FileAs String The name the contact is filed under. Yes Yes
Flag FollowupFlag Information about any follow-up on the contact. Yes Yes
Gender String The contact's gender. Yes Yes
Generation String The contact's generation. Yes Yes
GivenName String The contact's given name. Yes Yes
Id String The contact's unique identifier. No No
ImAddresses Collection(String) The contact's instant messaging (IM) addresses. Yes No
Initials String The contact's initials. Yes Yes
JobTitle String The contact's job title. Yes Yes
LastModifiedDateTime datetimeoffset The time the contact was modified. No Yes
Manager String The name of the contact's manager. Yes Yes
MiddleName String The contact's middle name. Yes Yes
NickName String The contact's nickname. Yes Yes
OfficeLocation String The location of the contact's office. Yes Yes
ParentFolderId String The ID of the contact's parent folder. No No
PersonalNotes String The user's notes about the contact. Yes Yes
Phones Collection(Phone) Phone numbers associated with the contact, for example, home phone, mobile phone, and business phone. Yes Yes
PostalAddresses PhysicalAddress collection Addresses associated with the contact, for example, home address and business address. Yes No
Profession String The contact's profession. Yes Yes
SpouseName String The name of the contact's spouse. Yes Yes
Surname String The contact's surname. Yes Yes
Title String The contact's title. Yes No
Websites Collection(Website) Web sites associated with the contact. Yes No
WeddingAnniversary Date The contact's wedding anniversary. Yes Yes
YomiCompanyName String The phonetic Japanese company name of the contact. This property is optional. Yes No
YomiGivenName String The phonetic Japanese given name (first name) of the contact. This property is optional. Yes No
YomiSurname String The phonetic Japanese surname (last name) of the contact. This property is optional. Yes No

The navigation properties MultiValueExtendedProperties and SingleValueExtendedProperties are also available for this resource, to represent collections of respective types of extended properties defined for a resource instance. For more information, see Extended Properties REST API.

ContactFolder

A folder that contains contacts.

Type: Microsoft.OutlookServices.ContactFolder

A ContactFolder collection returns an array of contact folders in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/contactfolders/$count

See ContactFolder operations for supported actions.

Property Type Description Writable? Filterable?
ChildFolders Collection(ContactFolder) The collection of child folders in the folder. Navigation property. No No
Contacts Collection(Contact) The contacts in the folder. Navigation property. No No
DisplayName String The folder's display name. Yes Yes
Id String Unique identifier of the contact folder. No No
ParentFolderId String The ID of the folder's parent folder. No No
WellKnownName String The name of the folder if the folder is a recognized folder. Currently contacts is the only recognized contacts folder. No No
MultiValueExtendedProperties A collection A collection of multi-value extended properties of type MultiValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes
SingleValueExtendedProperties A collection A collection of single-value extended properties of type SingleValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes

Event

An event in a calendar.

Type: Microsoft.OutlookServices.Event

An Event collection returns an array of events in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/events/$count

See Event operations for supported actions.

Property Type Description Writable? Filterable?
Attachments Collection(Attachment) The collection of FileAttachment, ItemAttachment, and ReferenceAttachment attachments for the event. Navigation property. No No
Attendees Collection(Attendee) The collection of attendees for the event. Yes No
Body ItemBody The body of the message associated with the event. Yes No
BodyPreview String The preview of the message associated with the event. No No
Calendar Calendar The calendar that contains the event. Navigation property. No No
Categories Collection(String) The categories associated with the event. Yes No
ChangeKey String Identifies the version of the event object. Every time the event is changed, ChangeKey changes as well. This allows Exchange to apply changes to the correct version of the object. No No
CreatedDateTime datetimeoffset The date and time that the event was created. No Yes
End DateTimeTimeZone The date and time that the event ends. Yes Yes
Extensions Collection(Extension) The collection of open type data extensions defined for the event. Navigation property. No Yes
HasAttachments boolean Set to true if the event has attachments. No Yes
Id String The unique identifier of the event. No No
Importance Importance The importance of the event: Low, Normal, High. Yes Yes
Instances Collection(Event) The instances of the event. Navigation property. No No
iCalUID String A unique identifier that is shared by all instances of an event across different calendars. No Yes
IsAllDay boolean Set to true if the event lasts all day. Adjusting this property requires adjusting the Start and End properties of the event as well. Yes Yes
IsCancelled boolean Set to true if the event has been canceled. Yes Yes
IsOrganizer boolean Set to true if the message sender is also the organizer. Yes Yes
IsReminderOn Boolean Set to true if an alert is set to remind the user of the event. Yes Yes
LastModifiedDateTime datetimeoffset The date and time that the event was last modified. No Yes
Location Location Location information of the event. Yes Yes
Locations Collection(Location) The locations where the event is held or attended from. Yes Yes
OnlineMeetingUrl String A URL for an online meeting. Yes No
Organizer Recipient The organizer of the event. Yes Yes
OriginalEndTimeZone String The end time zone that was set when the event was created. See DateTimeTimeZone for a list of valid time zones. No Yes
OriginalStartTimeZone String The start time zone that was set when the event was created. See DateTimeTimeZone for a list of valid time zones. No Yes
Recurrence PatternedRecurrence The recurrence pattern for the event. Yes No
ReminderMinutesBeforeStart Int32 The number of minutes before the event start time that the reminder alert occurs. Yes No
ResponseRequested boolean Set to true if the sender would like a response when the event is accepted or declined. Yes Yes
ResponseStatus ResponseStatus Indicates the type of response sent in response to an event message. No Yes
Sensitivity Sensitivity Indicates the level of privacy for the event: Normal, Personal, Private, Confidential. Yes Yes
SeriesMasterId String The categories assigned to the item. Yes No
ShowAs FreeBusyStatus The status to show: Free, Tentative, Busy, Oof, WorkingElsewhere, Unknown. Yes Yes
Start DateTimeTimeZone The start time of the event. Yes Yes
Subject String The text of the event's subject line. Yes Yes
Type EventType The event type: SingleInstance, Occurrence, Exception, SeriesMaster. Yes Yes
WebLink String The URL to open the event in Outlook Web App.

The event will open in the browser if you are logged in to your mailbox via Outlook Web App. You will be prompted to login if you are not already logged in with the browser.

This URL can be accessed from within an iFrame.		 No No

The navigation properties MultiValueExtendedProperties and SingleValueExtendedProperties are also available for this resource, to represent collections of respective types of extended properties defined for a resource instance. For more information, see Extended Properties REST API.

EventMessage

A message that represents a meeting request, meeting cancel message, meeting accept message, meeting tentatively accept message, or meeting declined message.

Base type: Message

An EventMessage instance is typically found in the Inbox folder where it arrives as the results of either an event organizer creating a meeting or by an attendee responding to a meeting request. You act on event messages in the same way that you act on Message, with some minor differences described in the following table.

Action/Verb Permission Description
Create an event message (POST) N/A Not allowed. Will result in a 400 response code.
Update an event message (PATCH) Mail.Write You may update the From, Sender, ToRecipients, CcRecipients, BccRecipients, ReplyTo, IsDeliveryReceiptRequested, IsReadReceiptRequested, IsDraft, IsRead, Subject, Body, Importance and Categories properties.
Delete an event message (DELETE) Mail.Write Same action as for a Message.
Move an event message (POST) Mail.Write Same action as for a Message.
Copy an event message (POST) Mail.Write Same action as for a Message.
Create draft reply message (POST) Mail.Write Same action as for a Message.
Create draft reply all message (POST) Mail.Write Same action as for a Message.
Create a reply (POST) Mail.Write Same action as for a Message.
Create a reply all (POST) Mail.Write Same action as for a Message.
Send an existing event message (POST) Mail.Write You can only send an event message where the IsDraft property has a value of true. A copy of the message is saved in the Sent Items folder.
Create a draft forward event message Mail.Write Same action as for a Message.
Forward an event message Mail.Write Same action as for a Message.

An EventMessage instance includes properties of the base type Message, and the properties in the following table.

Property Type Description Writable? Filterable?
EndDateTime DateTimeTimeZone The date and time that the associated event ends. Yes Yes
Event Event The event associated with the event message. The assumption for attendees or room resources is that the Calendar Attendant is set to automatically update the calendar with an event when meeting request event messages arrive. Navigation property. No No
IsAllDay Boolean Indicates whether the event lasts the entire day. Adjusting this property requires adjusting the StartDateTime and EndDateTime properties of the event as well. Yes Yes
IsOutOfDate Boolean Indicates whether this meeting request has been made out-of-date by a more recent request. No No
Location Location The location of the associated event. Yes Yes
MeetingMessageType MeetingMessageType The type of event message: None = 0, MeetingRequest = 1, MeetingCancelled = 2, MeetingAccepted = 3, MeetingTentativelyAccepted = 4, MeetingDeclined = 5 No Yes
Recurrence PatternedRecurrence The recurrence pattern for the associated event. Yes No
StartDateTime DateTimeTimeZone The start time of the associated event. Yes Yes
Type EventType The type of the associated event: SingleInstance = 0, Occurrence = 1, Exception = 2, SeriesMaster = 3. Yes Yes

EventMessageRequest (preview)

A message that represents a meeting request.

Base type: EventMessage

Property Type Description Writable? Filterable?
PreviousEndDateTime DateTimeTimeZone The previous end date and time of the requested meeting. No Yes
PreviousLocation Location The previous location of the requested meeting. No Yes
PreviousStartDateTime DateTimeTimeZone The previous start date and time of the requested meeting. No Yes

Extended properties

You can create a custom property on an entity as a MultiValueLegacyExtendedProperty or SingleValueLegacyExtendedProperty, depending on the values intended for the property.

MultiValueLegacyExtendedProperty

An extended property that can contain a collection of multiple values.

Type: Microsoft.OutlookServices.MultiValueLegacyExtendedProperty

Property Type Description Writable? Filterable?
Value Collection(String) A collection of property values. Yes No
PropertyId String The property ID. This is used to identify the property. No No

SingleValueLegacyExtendedProperty

An extended property that contains a single value.

Type: Microsoft.OutlookServices.SingleValueLegacyExtendedProperty

Property Type Description Writable? Filterable?
Value String A property value. Yes No
PropertyId String The property ID. This is used to identify the property. No Yes

When creating an extended property, there are various ways to specify the PropertyId. See PropertyId Formats for details.

See the Extended Properties REST API reference for the related operations you can use.

FileAttachment

A file (such as a text file or Word document) attached to a message, event, or task. The ContentBytes property contains the base64-encoded contents of the file. Derived from the Attachment entity.

Type: Microsoft.OutlookServices.FileAttachment

Base type: Microsoft.OutlookServices.Attachment

Property Type Description Writable?
ContentBytes binary The binary contents of the file. No
ContentId String The ID of the attachment in the Exchange store. No
ContentLocation String The Uniform Resource Identifier (URI) that corresponds to the location of the content of the attachment. No
ContentType String The content type of the attachment. Yes
LastModifiedDateTime datetimeoffset The date and time when the attachment was last modified. No
Id String The attachment ID. No
IsInline boolean Set to true if this is an inline attachment. Yes
Name String The name representing the text that is displayed below the icon representing the embedded attachment.This does not need to be the actual file name. Yes
Size Int32 The size in bytes of the attachment. No

Folder / MailFolder

Note

In the beta version, the entity and type previously known as Folder have been renamed as MailFolder.

A folder in a user's mailbox, such as Inbox, Drafts, and Sent Items. Folders can contain messages and other folders.

Type: Microsoft.OutlookServices.MailFolder

A MailFolders collection returns an array of folders in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/folders/$count

See Folder operations for supported actions.

Property Type Description Writable? Filterable?
ChildFolderCount Int32 The number of folders in the folder. No Yes
ChildFolders Collection(MailFolder) The collection of child folders in the folder. Navigation property. No No
DisplayName String The folder's display name. Yes Yes
Id String The folder's unique identifier. You can use the following well-known names to access the corresponding folder: Inbox, Drafts, SentItems, DeletedItems. No No
MessageRules Collection(MessageRule) The collection of rules that apply to the Inbox folder. Navigation property. No No
Messages Collection(Message) The collection of messages in the folder. Navigation property. No No
ParentFolderId String The unique identifier for the folder's parent folder. No No
TotalItemCount Int32 The number of items in the folder. No Yes
UnreadItemCount Int32 The number of items in the folder marked as unread. No Yes
WellKnownName String The folder's well-known name, such as clutter, deleteditems, drafts, inbox, junkemail, outbox, or sentitems. No Yes
MultiValueExtendedProperties A collection A collection of multi-value extended properties of type MultiValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes
SingleValueExtendedProperties A collection A collection of single-value extended properties of type SingleValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes

Access item counts efficiently

The TotalItemCount and UnreadItemCount properties of a folder allow you to conveniently compute the number of read items in the folder. They let you avoid queries like the following that can incur significant latency:

https://outlook.office.com/api/beta/me/mailfolders/inbox/messages?$count=true&$filter=isread%20eq%20false

Folders in Outlook can contain more than one type of items, for example, the Inbox can contain meeting request items that are distinct from mail items. TotalItemCount and UnreadItemCount include items in a folder irrespective of their item types.

InferenceClassification

Classification of a user's messages to enable focus on those that are more relevant or important to the user.

Type: Microsoft.OutlookServices.InferenceClassification

Property Type Description Writable?
Overrides Collection(InferenceClassificationOverride) A set of overrides for a user to always classify messages from specific senders in certain ways, as supported by InferenceClassificationType. Navigation property. Yes

InferenceClassificationOverride

Represents a user's override for how incoming messages from a specific sender should always be classified as.

Type: Microsoft.OutlookServices.InferenceClassificationOverride

Property Type Description Writable?
ClassifyAs InferenceClassificationType Specifies how incoming messages from a specific sender should always be classified as. Focused=0, Other=1. Yes
Id String The unique identifier of the override. No
SenderEmailAddress EmailAddress The email address information of the sender for whom the override is created. Yes

ItemAttachment

A message, contact, or event that's attached to another message, event, or task. Derived from the Attachment entity.

Type: Microsoft.OutlookServices.ItemAttachment

Base type: Microsoft.OutlookServices.Attachment

Property Type Description Writable?
ContentType String The content type of the attachment. Yes
LastModifiedDateTime datetimeoffset The last time and date that the attachment was modified. No
Id String The attachment ID. No
Item Item The attached message or event. Navigation property. Yes
IsInline boolean Set to true if the attachment is inline, such as an embedded image within the body of the item. Yes
Name String The display name of the attachment. Yes
Size Int32 The size in bytes of the attachment. Yes

Mention (preview)

Represents a notification to a person based on the person's email address. This type of notification is also known as @-mentions.

The Message resource supports Mention. It include a MentionsPreview property which indicates whether the signed-in user is mentioned in that instance, and the Mentions navigation property which supports getting details of any mention in that instance.

When creating a message, an app can create a mention in the same POST request by including the mention in the Mentions property. Using a GET request with the $filter query parameter, an app can return all the messages in the signed-in user's mailbox that mention the user. A GET request with the $expand query parameter lets the app expand all mentions in a specific message.

This mechanism of letting an app set and get mentions in messages enables light-weight notifications, where the user making the mention can remain in the existing context (such as composing a message body) while the app sets the underlying Mentions property. Mentioned persons can easily find out if and where they are mentioned through GET requests with the $filter or $expand query parameter.

An example use case of the Mentions API is in Outlook, the mail client. When a user types @ while writing a message, Outlook lets the user simply select or enter a name to complete the @-mention, without having to step out of the context to call the person's attention. Beneath the covers, Outlook sets the Mentions property before actually creating and sending the message. Outlook also uses GET operations with $filter and $expand to let the signed-in user conveniently look up if and which messages mention the user, alerting the user to action items or discussions for quicker response.

Type: Microsoft.OutlookServices.Mention

Property Type Description Writable? Filterable?
Application String The name of the application where the mention is created. Optional. Not used and defaulted as null for Message. Yes No
ClientReference String A unique identifier that represents a parent of the resource instance. Optional. Not used and defaulted as null for Message. Yes Yes
CreatedBy EmailAddress The email information of the user who made the mention. Required. Yes No
CreatedDateTime DateTimeOffset The date and time that the mention is created on the client. No No
DeepLink String A deep web link to the context of the mention in the resource instance. Optional. Not used and defaulted as null for Message. Yes No
Id String The unique identifier of a mention in a resource instance. No No
Mentioned EmailAddress The email information of the mentioned person. Required. Yes No
MentionText String Content for the mention. Optional. Not used and defaulted as null for Message. Yes No
ServerCreatedDateTime DateTimeOffset The date and time that the mention is created on the server. Optional. Not used and defaulted as null for Message. No No

Message

A message in a mailbox folder.

Type: Microsoft.OutlookServices.Message

A Message collection returns an array of messages in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/messages/$count

See Message operations for supported actions.

Property Type Description Writeable? Filterable? Searchable?
Attachments Collection(Attachment) The FileAttachment and ItemAttachment attachments for the message. Navigation property. Yes No Yes
BccRecipients Collection (Recipient) The Bcc recipients for the message. Yes No Yes
Body ItemBody The body of the message. Yes No Default
BodyPreview String The first 255 characters of the message body content. No No Yes
Categories Collection (String) The categories associated with the message. Yes Yes Yes
CcRecipients Collection (Recipient) The Cc recipients for the message. Yes No Yes
ChangeKey String The version of the message. No No No
ConversationId String The ID of the conversation that the email belongs to. No Yes No
ConversationIndex Binary Indicates the relative position of the item within the conversation that the email belongs to. No No No
CreatedDateTime datetimeoffset The date and time the message was created. No Yes No
Extensions Collection(Extension) The collection of open type data extensions defined for the message. Navigation property. No Yes No
Flag FollowupFlag Information about any follow-up on the message. Yes Yes Yes
From Recipient The mailbox owner and sender of the message. Yes Yes Yes
HasAttachments boolean Indicates whether the message has attachments. No Yes Yes
Id String The unique identifier of the message. No No No
Importance Importance The importance of the message: Low = 0, Normal = 1, High = 2. Yes Yes Yes
InferenceClassification InferenceClassificationType The classification of this message for the user, based on inferred relevance or importance, or on an explicit override. Yes Yes No
InternetMessageId String The message ID in the format specified by RFC2822. No No No
InternetMessageHeaders Collection(InternetMessageHeader) The collection of internet message headers in the format specified by RFC2822. No No No
IsDeliveryReceiptRequested boolean Indicates whether a read receipt is requested for the message. Yes Yes No
IsDraft boolean Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet. No Yes No
IsRead boolean Indicates whether the message has been read. Yes Yes No
IsReadReceiptRequested boolean Indicates whether a read receipt is requested for the message. Yes Yes No
LastModifiedDateTime datetimeoffset The date and time the message was last changed. No Yes No
Mentions Collection (Mention) A collection of mentions in the message, ordered by the CreatedDateTime from the newest to the oldest. By default, a GET message does not return this property unless you apply $expand on the property. Navigation property. Yes No No
MentionsPreview MentionsPreview Information about mentions in the message. When processing a GET /messages request, the server sets this property and includes it in the response by default. The server returns null if there are no mentions in the message. Optional. No No No
MultiValueExtendedProperties A collection A collection of multi-value extended properties of type MultiValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes No
ParentFolderId String The unique identifier for the message's parent folder. No No No
ReceivedDateTime datetimeoffset The date and time the message was received. No Yes Yes
ReplyTo Collection (Recipient) The email addresses to use when replying. No No No
Sender Recipient The account that is actually used to generate the message. Yes Yes Default
SentDateTime datetimeoffset The date and time the message was sent. No Yes No
SingleValueExtendedProperties A collection A collection of single-value extended properties of type SingleValueLegacyExtendedProperty. This is a navigation property.

Find more information about extended properties.		 Yes Yes No
Subject String The subject of the message. Yes Yes Default
ToRecipients Collection (Recipient) The To recipients for the message. Yes No Yes
UniqueBody ItemBody The body of the message that is unique to the conversation. No No No
UnsubscribeData Collection (String) This contains the valid entries parsed from the List-Unsubscribe header. If the UnsubscribeEnabled property is true, this would contain the data for the mailto: command in the List-Unsubscribe header. The data must conform to RFC-2369. Use the Unsubscribe action to stop future messages sent to the corresponding distribution list. No No No
UnsubscribeEnabled boolean Indicates whether this message allows a recipient to unsubscribe and stop future messages that are sent according to an email distribution list. True if the List-Unsubscribe header conforms to RFC-2369. No No No
WebLink String The URL to open the message in Outlook Web App.

You can append an ispopout argument to the end of the URL to change how the message is displayed. If ispopout is not present or if it is set to 1, then the message is shown in a popout window. If ispopout is set to 0, then the browser will show the message in the Outlook Web App review pane.

The message will open in the browser if you are logged in to your mailbox via Outlook Web App. You will be prompted to login if you are not already logged in with the browser.

This URL can be accessed from within an iFrame.		 No Yes No

Removing script from the Body property

The message body can be either HTML or text. If the body is HTML, by default, any potentially unsafe HTML (for example, JavaScript) embedded in the Body property would be removed before the body content is returned in a REST response.

To get the entire, original HTML content, include the following HTTP request header:

Prefer: outlook.allow-unsafe-html

Setting the From and Sender properties

When a message is being composed, in most cases, the From and Sender properties represent the same signed-in user, unless either is updated as described in the following scenarios:

  • The From property can be changed if the Exchange administrator has assigned SendAs rights of the mailbox to some other users. The administrator can do this by selecting Mailbox Permissions of the mailbox owner in the Azure Management Portal, or by using the Exchange Admin Center or a Windows PowerShell Add-ADPermission cmdlet. Then, you can programmatically set the From property to one of these users who have SendAs rights for that mailbox.

  • The Sender property can be changed if the mailbox owner has delegated one or more users to be able to send messages from that mailbox. The mailbox owner can delegate in Outlook. When a delegate sends a message on behalf of the mailbox owner, the Sender property is set to the delegate’s account, and the From property remains as the mailbox owner. Programmatically, you can set the Sender property to a user who has got delegate right for that mailbox.

MessageRule (preview)

A rule that applies to messages in the Inbox of a user.

Type: Microsoft.OutlookServices.MessageRule

Property Type Description Writable?
Actions MessageRuleActions Actions to be taken on a message when the corresponding conditions are fulfilled. Yes
Conditions MessageRulePredicates Conditions that when fulfilled, will trigger the corresponding actions for that rule. Yes
DisplayName String The display name of the rule. Yes
Exceptions MessageRulePredicates Represents exception conditions for the rule. Yes
HasError Boolean Indicates whether the rule is in an error condition. No
IsEnabled Boolean Indicates whether the rule is enabled to be applied to messages. Yes
IsReadOnly Boolean Indicates if the rule is read-only and cannot be modified or deleted by the rules REST API. Yes
Sequence Int32 Indicates the order in which the rule is executed, among other rules. Yes

OutlookCategory (preview)

Type: Microsoft.OutlookServices.OutlookCategory

A category by which a user can group Outlook items such as messages and events in their mailbox.

Property Type Description Writable? Filterable?
DisplayName String A unique name for this category in the user's mailbox. No Yes
Color CategoryColor A pre-set constant that represents the mapped color for this category. Yes Yes

Photo

Type: Microsoft.OutlookServices.Photo

A photo accessed from Exchange Online. It's binary data not encoded in base-64.

Property Type Description Writable? Filterable?
Height int The height of the photo No No
Id String The unique identifier of the photo. No No
Width int The width of the photo. No No

ReferenceAttachment

Type: Microsoft.OutlookServices.ReferenceAttachment

Base type: Microsoft.OutlookServices.Attachment

A link to a file or folder, attached to a message, event, or task. Possible locations for the file or folder includes OneDrive, OneDrive for Business, and DropBox. Derived from the Attachment entity.

Property Type Description Writable? Filterable?
ContentType String The MIME type of the attachment. Optional. Yes No
Id String The unique identifier of the reference attachment. No No
IsFolder Boolean Specifies whether the attachment is a link to a folder. Must set this to true if SourceUrl is a link to a folder. Optional. Yes No
IsInline Boolean true if the attachment is an inline attachment; otherwise, false. Optional. Yes Yes
LastModifiedDateTime DateTimeOffset The date and time when the attachment was last modified. The date and time use ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'. Optional. No Yes
Name String The display name of the attachment. This does not need to be the actual file name. Required. Yes Yes
Permission ReferenceAttachmentPermissions Specifies the permissions granted for the attachment by the type of provider in ProviderType. Possible values are: Other, View, Edit, AnonymousView, AnonymousEdit, OrganizationView, OrganizationEdit. Optional. Yes No
PreviewUrl String Applies to only a reference attachment of an image - URL to get a preview image. Use ThumbnailUrl and PreviewUrl only when SourceUrl identifies an image file. Optional. Yes No
ProviderType ReferenceAttachmentProviders The type of provider that supports an attachment of this ContentType. Possible values are: Other, OneDriveBusiness, OneDriveConsumer, Dropbox. Optional. Yes Yes
Size Int32 The length of the attachment in bytes. Optional. No No
SourceUrl String URL to get the attachment content. If this is a URL to a folder, then for the folder to be displayed correctly in Outlook or Outlook on the web, set IsFolder to true. Required. Yes No
ThumbnailUrl String Applies to only a reference attachment of an image - URL to get a thumbnail image. Use ThumbnailUrl and PreviewUrl only when SourceUrl identifies an image file. Optional. Yes No

Task

Type: Microsoft.OutlookServices.Task

An Outlook item that can track a work item. You can use a task to track the start, due and actual completion dates and times, its progress or status, whether it's recurring, and requires reminding.

For each of the following date-related properties:

  • CompletedDateTime
  • CreatedDateTime
  • DueDateTime
  • LastModifiedDateTime
  • ReminderDateTime
  • StartDateTime

If the property is set, then, by default, the Task REST API returns it in UTC in a REST response. Find more information about setting StartDateTime and DueDateTime and returning date-related properties in a custom time zone.

Property Type Description Writable? Filterable?
AssignedTo String The name of the person who has been assigned the task. No Yes
Attachments Collection(Attachment) The collection of FileAttachment, ItemAttachment, and ReferenceAttachment attachments for the task. Navigation property. No No
Body ItemBody The task body that typically contains information about the task. Note that only HTML type is supported. Yes No
Categories Collection(String) The categories associated with the task. Yes Yes
ChangeKey String The version of the task. No No
CompletedDateTime DateTimeTimeZone The date in the specified time zone that the task was finished. Yes Yes
CreatedDateTime DateTimeOffset The date and time when the task was created. By default, it is in UTC. You can provide a custom time zone in the request header. No Yes
DueDateTime DateTimeTimeZone The date in the specified time zone that the task is to be finished. Yes Yes
HasAttachments boolean Set to true if the task has attachments. No Yes
Id String The unique identifier of the task. No No
Importance Importance The importance of the event: Low, Normal, High. Yes Yes
IsReminderOn boolean Set to true if an alert is set to remind the user of the task. Yes No
LastModifiedDateTime DateTimeOffset The date and time when the task was last modified. By default, it is in UTC. You can provide a custom time zone in the request header. No Yes
Owner String The name of the person who created the task. No Yes
ParentFolderId String The unique identifier for the task's parent folder. No No
Recurrence PatternedRecurrence The recurrence pattern for the task. Yes No
ReminderDateTime DateTimeTimeZone The date and time for a reminder alert of the task to occur. Yes No
Sensitivity Sensitivity Indicates the level of privacy for the event: Normal, Personal, Private, Confidential. Yes Yes
StartDateTime DateTimeTimeZone The date in the specified time zone when the task is to begin. Yes Yes
Status TaskStatus Indicates state or progress of the task: NotStarted, InProgress, Completed, WaitingOnOthers, Deferred. Yes Yes
Subject String A brief description or title of the task. Yes Yes

TaskFolder

Type: Microsoft.OutlookServices.TaskFolder

A folder that contains tasks. In Outlook, the default task group, My Tasks, contains a default task folder, Tasks, for the user's mailbox. You cannot rename or delete these default task group and folder, but you can create additional task groups and task folders.

Property Type Description Writable? Filterable?
ChangeKey String The version of the task folder. No No
Id String The unique identifier of the task folder. No No
IsDefaultFolder Boolean True if the folder is the default task folder. No Yes
Name String The name of the task folder. Yes Yes
ParentGroupKey Edm.Guid The unique GUID identifier for the task folder's parent group. No No
Tasks Collection(Task) The tasks in this task folder. Navigation property. No No

TaskGroup

Type: Microsoft.OutlookServices.TaskGroup

A group of folders that contain tasks. In Outlook, there is a default task group My Tasks which you cannot rename or delete. You can, however, create additional task groups.

Property Type Description Writable? Filterable?
ChangeKey String The version of the task group. No No
GroupKey Edm.Guid The unique GUID identifier for the task group. No No
Id String The unique identifier of the task group. No No
IsDefaultGroup Boolean True if the task group is the default task group. No Yes
Name String The name of the task group. Yes Yes
TaskFolders Collection(TaskFolder) The task folders in this task group. Navigation property. No No

User

A user in the system. The Me endpoint is provided as a shortcut for specifying the current user by SMTP address (users/sadie@contoso.com).

Type: Microsoft.OutlookServices.User

A Users collection returns an array of users in the value property of the OData response. Use $count to get the count of entities in the collection: .../me/users/$count

Note

The User entity includes many properties and relationships (navigation properties) that are augmented frequently. The following section describes only a subset. For current information, refer to the User definition in the corresponding metadata file for your version.

Property Type Description Writable? Filterable?
Alias String The user's alias. Typically the SMTP address of the user. Yes Yes
Calendar Calendar The user's primary calendar. Navigation property. No No
CalendarGroups Collection(CalendarGroup) The user's calendar groups. Navigation property. No No
Calendars Collection(Calendar) The user's calendars. Navigation property. No No
CalendarView Collection(Event) The calendar view for the calendar. Navigation property. No No
ContactFolders Collection(ContactFolder) The user's contacts folders. Navigation property. No No
Contacts Collection(Contact) The user's contacts. Navigation property. No No
DisplayName String The user's display name. Yes Yes
Events Collection(Event) The user's events. Default is to show Events under the Default Calendar. Navigation property. No No
Id String The unique identifier for the user. No No
InferenceClassification InferenceClassification Relevance classification of the user's messages based on explicit designations which override inferred relevance or importance. Navigation property. Yes Yes
MailboxGuid guid The GUID assigned to the user's mailbox. No Yes
MailboxSettings MailboxSettings Settings for the primary mailbox of the signed-in user. Yes No
MailFolders Collection(MailFolder) The folders in a mailbox. Navigation property. No No
MasterCategories Collection(OutlookCategory) The user's master list of categories. Navigation property. Yes Yes
Messages Collection(Message) The messages in a mailbox or folder. Navigation property. No No
RootFolder MailFolder The root folder of the user's mailbox. Navigation property. No No

Complex types

Attendee

An event attendee.

Type: Microsoft.OutlookServices.AttendeeBase

Property Type Description
Status ResponseStatus The response (none, accepted, declined, etc.) and time.

AttendeeAvailability

The type and availability of an attendee.

Type: Microsoft.OutlookServices.AttendeeAvailability

Property Type Description
Attendee AttendeeBase The type of attendee - whether it's a person, or a resource.
Availability FreeBusyStatus The availability status of the attendee.

AttendeeBase

The type of attendee.

Type: Microsoft.OutlookServices.Recipient

Property Type Description
Type AttendeeType The type of the attendee. Possible values are: Required, Optional, Resource. NOTE: If the attendee is a person, FindMeetingTimes always considers the person is of the Required type.

AutomaticRepliesMailTips (preview)

Mail tips about automatic replies set up on a mailbox.

Type: Microsoft.OutlookServices.AutomaticRepliesMailTips

Property Type Description
Message String The automatic reply message.
MessageLanguage LocaleInfo The language that the automatic reply message is in.
ScheduledStartTime DateTimeTimeZone The date and time that automatic replies are set to begin.
ScheduledEndTime DateTimeTimeZone The date and time that automatic replies are set to end.

AutomaticRepliesSetting

Configuration settings to automatically notify the sender of an incoming email with a message from the signed-in user. For example, an automatic reply to notify that the signed-in user is unavailable to respond to emails.

Type: Microsoft.OutlookServices.AutomaticRepliesSetting

Property Type Description
ExternalAudience ExternalAudienceScope The set of audience external to the signed-in user's organization who will receive the ExternalReplyMessage, if Status is AlwaysEnabled or Scheduled. Values are None = 0, ContactsOnly = 1, or All = 2.
ExternalReplyMessage String The automatic reply to send to the specified external audience, if Status is AlwaysEnabled or Scheduled.
InternalReplyMessage String The automatic reply to send to the audience internal to the signed-in user's organization, if Status is AlwaysEnabled or Scheduled.
ScheduledEndDateTime DateTimeTimeZone The date and time that automatic replies are set to end, if Status is set to Scheduled. You can set the time zone using the Prefer: outlook.timezone HTTP header in the Get operation.
ScheduledStartDateTime DateTimeTimeZone The date and time that automatic replies are set to begin, if Status is set to Scheduled. You can set the time zone using the Prefer: outlook.timezone HTTP header in the Get operation.
Status AutomaticRepliesStatus Configurations status for automatic replies: Disabled = 0, AlwaysEnabled = 1, Scheduled = 2.

DateTimeTimeZone

Describes the date, time, and time zone of a point in time.

Property Type Description
DateTime DateTime A single point of time in a combined date and time representation (<date>T<time>) according to ISO 8601 format
TimeZone String One of the following time zone names.

The TimeZone property can be set to any of the time zones supported by Windows, as well as the following time zones names. See TimeZone for more information.

Etc/GMT+12

Etc/GMT+11

Pacific/Honolulu

America/Anchorage

America/Santa_Isabel

America/Los_Angeles

America/Phoenix

America/Chihuahua

America/Denver

America/Guatemala

America/Chicago

America/Mexico_City

America/Regina

America/Bogota

America/New_York

America/Indiana/Indianapolis

America/Caracas

America/Asuncion

America/Halifax

America/Cuiaba

America/La_Paz

America/Santiago

America/St_Johns

America/Sao_Paulo

America/Argentina/Buenos_Aires

America/Cayenne

America/Godthab

America/Montevideo

America/Bahia

Etc/GMT+2

Atlantic/Azores

Atlantic/Cape_Verde

Africa/Casablanca

Etc/GMT

Europe/London

Atlantic/Reykjavik

Europe/Berlin

Europe/Budapest

Europe/Paris

Europe/Warsaw

Africa/Lagos

Africa/Windhoek

Europe/Bucharest

Asia/Beirut

Africa/Cairo

Asia/Damascus

Africa/Johannesburg

Europe/Kiev

Europe/Istanbul

Asia/Jerusalem

Asia/Amman

Asia/Baghdad

Europe/Kaliningrad

Asia/Riyadh

Africa/Nairobi

Asia/Tehran

Asia/Dubai

Asia/Baku

Europe/Moscow

Indian/Mauritius

Asia/Tbilisi

Asia/Yerevan

Asia/Kabul

Asia/Karachi

Asia/Tashkent

Asia/Kolkata

Asia/Colombo

Asia/Kathmandu

Asia/Almaty

Asia/Dhaka

Asia/Yekaterinburg

Asia/Rangoon

Asia/Bangkok

Asia/Novosibirsk

Asia/Shanghai

Asia/Krasnoyarsk

Asia/Singapore

Australia/Perth

Asia/Taipei

Asia/Ulaanbaatar

Asia/Irkutsk

Asia/Tokyo

Asia/Seoul

Australia/Adelaide

Australia/Darwin

Australia/Brisbane

Australia/Sydney

Pacific/Port_Moresby

Australia/Hobart

Asia/Yakutsk

Pacific/Guadalcanal

Asia/Vladivostok

Pacific/Auckland

Etc/GMT-12

Pacific/Fiji

Asia/Magadan

Pacific/Tongatapu

Pacific/Apia

Pacific/Kiritimati

EmailAddress

The name and email address of a contact or message recipient.

Type: Microsoft.OutlookServices.EmailAddress

Property Type Description
Name String The display name of the person or entity.
Address String The email address of the person or entity.

Error (preview)

An error that occurs during an action.

Type: Microsoft.OutlookServices.Error

Property Type Description
Message String The error message.
Code String The error code.

FollowUpFlag (preview)

Information about following up on a resource instance.

Type: Microsoft.OutlookServices.FollowupFlag

Property Type Description
CompletedDateTime DateTimeTimeZone The date and time that the follow-up finished.
DueDateTime DateTimeTimeZone The date and time that the follow-up is to be finished.
StartDateTime DateTimeTimeZone The date and time that the follow-up is to begin.
FlagStatus FollowupFlagStatus Represents whether the parent resource instance is flagged for follow-up, or its follow-up is finished.

GeoCoordinates

The geographic coordinates and elevation of the location.

Type: Microsoft.OutlookServices.GeoCoordinates

Property Type Description
Altitude double The altitude of the location.
Latitude double The latitude of the location.
Longitude double The longitude of the location.
Accuracy double The accuracy of the sensor providing the latitude and longitude.
AltitudeAccuracy double The accuracy of the sensor providing the altitude.

InternetMessageHeader (preview)

A key-value pair that represents an internet message header in the format specified by RFC2822 which provides details of the network path taken by a message from the sender to the recipient.

Type: Microsoft.OutlookServices.InternetMessageHeader

Property Type Description
Name String The key in the internet message header key-value pair.
Value String The value in the internet message header key-value pair.

ItemBody

The body content of a message or event.

Type: Microsoft.OutlookServices.ItemBody

Property Type Description
ContentType BodyType The content type: Text = 0, HTML = 1.
Content String The text or HTML content.

LocaleInfo

Information about the locale, including the preferred language and country/region, of the signed-in user.

Type: Microsoft.OutlookServices.LocaleInfo

Property Type Description
DisplayName String A name representing a locale by its natural language, for example, "English (United States)".
Locale String A locale representation which includes the language and country/region. For example, "en-us". The language component follows 2-letter codes as defined in ISO 639-1, and the country component follows 2-letter codes as defined in ISO 3166-1 alpha-2.

Location (preview)

The location of an event.

Type: Microsoft.OutlookServices.Location

Property Type Description
Address PhysicalAddress The physical address of the location.
Coordinates GeoCoordinates The geographic coordinates and elevation of the location.
DisplayName String The name associated with the location.
LocationEmailAddress String Optional email address of the location.
LocationUri String Optional URI representing the location.
LocationType LocationType The type of location: Default, ConferenceRoom, HomeAddress, BusinessAddress,GeoCoordinates, StreetAddress, Hotel, Restaurant, LocalBusiness, PostalAddress.

LocationConstraint

The conditions stated by a client for the location of a meeting.

Type: Microsoft.OutlookServices.LocationConstraint

Property Type Description
IsRequired boolean The client requests the service to include in the response a meeting location for the meeting.
SuggestLocation boolean The client requests the service to suggest one or more meeting locations.
Locations Collection(LocationConstraintItem) One or more locations that the client requests for a meeting.

LocationConstraintItem

The conditions stated by a client for checking the availability of each location of a meeting, and other information about the location.

Type: Microsoft.OutlookServices.Location

Property Type Description
ResolveAvailability boolean If set to true and the specified resource is busy, FindMeetingTimes looks for another resource that is free. If set to false and the specified resource is busy, FindMeetingTimes returns the resource best ranked in the user's cache without checking if it's free. Default is true.

MailTips (preview)

Informative messages displayed to users while they are composing a message. For example, an out-of-office message as an automatic reply for a message recipient.

Type: Microsoft.OutlookServices.MailTips

Property Type Description
EmailAddress EmailAddress The email address of the recipient to get mailtips for.
AutomaticReplies AutomaticRepliesMailTips Mail tips for automatic reply if it has been set up by the recipient.
MailboxFull Boolean The mailbox full status of the recipient.
CustomMailTip String A custom mail tip that can be set on the recipient's mailbox.
ExternalMemberCount Int32 The number of external members if the recipient is a distribution list.
TotalMemberCount Int32 The number of members if the recipient is a distribution list.
DeliveryRestricted Boolean Whether the recipient's mailbox is restricted, for example, accepting messages from only a predefined list of senders, rejecting messages from a predefined list of senders, or accepting messages from only authenticated senders.
IsModerated Boolean Whether sending messages to the recipient requires approval. For example, if the recipient is a large distribution list and a moderator has been set up to approve messages sent to that distribution list, or if sending messages to a recipient requires approval of the recipient's manager.
RecipientScope RecipientScopeType The scope of the recipient, such as internal, external, partner. For example, an administrator can set another organization to be its "partner". The scope is useful if an administrator wants certain mailtips to be accessible to certain scopes. It's also useful to senders to inform them that their message may leave the organization, helping them make the correct decisions about wording, tone and content.
RecipientSuggestions Collection(Recipient) Recipients suggested based on previous contexts where they appear in the same message.
MaxMessageSize Int32 The maximum message size that has been configured for the recipient's organization or mailbox.
Error Error Errors that occur during the GetMailTips action.

MailboxSettings

Settings for the primary mailbox of the user.

Type: Microsoft.OutlookServices.MailboxSettings

Property Type Description
AutomaticRepliesSetting AutomaticRepliesSetting Settings to configure automatically sending replies to incoming messages.
TimeZone String The default time zone for the user's mailbox.
Language LocaleInfo The locale information for the user, including the preferred language and country/region.
WorkingHours WorkingHours The days of the week and hours in a specific time zone that the user works.

MeetingTimeSuggestion

A meeting suggestion that includes information like meeting time, attendance likelihood, individual attendee availability, and available meeting locations.

Type: Microsoft.OutlookServices.MeetingTimeSuggestion

Property Type Description
MeetingTimeSlot TimeSlot A time period suggested for the meeting.
Confidence double A percentage that represents the likelihood of all the attendees attending.
OrganizerAvailability FreeBusyStatus Availability of the meeting organizer for this meeting suggestion: Free, Tentative, Busy, Oof, WorkingElsewhere, Unknown.
AttendeeAvailability Collection(AttendeeAvailability) An array that shows the availability status of each attendee for this meeting suggestion.
Locations Collection(Location) An array that specifies the name and geographic location of each meeting location for this meeting suggestion.
SuggestionReason String Describes the reasons for suggesting the meeting time.

The confidence of a meeting

The Confidence property of a MeetingTimeSuggestion ranges from 0% to 100%, and represents the chance that all the attendees attend the meeting, based on each of their individual free/busy status:

  • For each attendee, a free status for a specified meeting time period corresponds to 100% chance of attendance, unknown status 49%, and busy status 0%.
  • The confidence of a meeting time candidate is computed by averaging the chance of attendance over all the attendees specified for that meeting.
  • You can use the MinimumAttendeePercentage optional parameter for FindMeetingTimes to specify only meeting time slots of at least certain confidence level should be returned. For example, you can specify a MinimumAttendeePercentage of 80% if you want only suggestions that have an 80% chance or more that all the attendees are attending. If you do not specify MinimumAttendeePercentage, FindMeetingTimes assumes a value of 50%.
  • If there are multiple meeting time candidates, the FindMeetingTimes action first orders the candidates by their computed confidence value from high to low. If there are candidates with the same confidence, the action then orders these candidates chronologically.

As an example, if a meeting time slot involves 3 attendees with the following free/busy status:

Attendee Free/busy status % Chance of attendance
Dana Free 100%
John Unknown 49%
Fanny Busy 0%

Then the confidence of the meeting time slot, which is the average chance of attendance, is (100% + 49% + 0%)/3 = 49.66%.

If you specify a MinimumAttendeePercentage of 80% in a FindMeetingTimes operation, because 49.66% < 80%, the operation will not return this time slot in the response.

MeetingTimeSuggestionsResult

A collection of meeting suggestions if there is any, or the reason if there isn't.

Type: Microsoft.OutlookServices.MeetingTimeSuggestionsResult

Property Type Description
MeetingTimeSuggestions Collection(MeetingTimeSuggestion) An array of meeting suggestions.
EmptySuggestionsReason String A reason for not returning any meeting suggestions. Possible values are: AttendeesUnavailable, LocationsUnavailable, OrganizerUnavailable, AttendeesUnavailableOrUnknown, or Unknown.

Reasons for returning no meeting suggestions

The EmptySuggestionsReason property specifies one of the following reasons why the FindMeetingTimes action does not return any meeting suggestions. The property is an empty string if FindMeetingTimes does return any meeting suggestions.

Value Reasons
AttendeesUnavailable All of the attendees' availability is known, but not enough attendees are available to reach the meeting confidence threshold, which is 50% by default.
AttendeesUnavailableOrUnknown Some or all of the attendees have unknown availability, causing the meeting confidence to fall below the set threshold, which is 50% by default. Attendee availability can become unknown if the attendee is outside of the organization, or there is an error obtaining free/busy information.
LocationsUnavailable The IsRequired property of the LocationConstraint parameter is specified as mandatory, and yet there are no locations available at the calculated time slots.
OrganizerUnavailable The IsOrganizerOptional parameter is false and yet the organizer is not available during the requested time window.
Unknown The reason for not returning any meeting suggestions is not known.

MentionsPreview (preview)

Represents information about mentions in a resource instance.

Type: Microsoft.OutlookServices.MentionsPreview

Property Type Description
IsMentioned Boolean True if the signed-in user is mentioned in the parent resource instance. Read-only. Supports filter.

MessageRuleActions (preview)

Represents the set of actions that are available to a rule.

Type: Microsoft.OutlookServices.MessageRuleActions

Property Type Description
AssignCategories Collection (String) A list of categories to be assigned to a message.
CopyToFolder String The ID of a folder that a message is to be copied to.
Delete Boolean Indicates whether a message should be moved to the Deleted Items folder.
ForwardAsAttachmentTo Collection (Recipient) The email addresses of the recipients to which a message should be forwarded as an attachment.
ForwardTo Collection (Recipient) The email addresses of the recipients to which a message should be forwarded.
MarkAsRead Boolean Indicates whether a message should be marked as read.
MarkImportance Importance Sets the importance of the message, which can be: Low, Normal, High.
MoveToFolder String The ID of the folder that a message will be moved to.
PermanentDelete Boolean Indicates whether a message should be permanently deleted and not saved to the Deleted Items folder.
RedirectTo Recipient The email address to which a message should be redirected.
StopProcessingRules Boolean Indicates whether subsequent rules should be evaluated.

MessageRulePredicates (preview)

Represents the set of conditions and exceptions that are available for a rule.

Type: Microsoft.OutlookServices.MessageRulePredicates

Property Type Description
BodyContains Collection (String) Represents the strings that should appear in the body of an incoming message in order for the condition or exception to apply.
BodyOrSubjectContains Collection (String) Represents the strings that should appear in the body or subject of an incoming message in order for the condition or exception to apply.
Categories Collection (String) Represents the categories that an incoming message should be labeled with in order for the condition or exception to apply.
FromAddresses Collection (Recipient) Represents the specific sender email addresses of an incoming message in order for the condition or exception to apply.
HasAttachments Boolean Indicates whether an incoming message must have attachments in order for the condition or exception to apply.
HeaderContains Collection (String) Represents the strings that appear in the headers of an incoming message in order for the condition or exception to apply.
Importance Importance The importance that is stamped on an incoming message in order for the condition or exception to apply: Low, Normal, High.
IsApprovalRequest Boolean Indicates whether an incoming message must be an approval request in order for the condition or exception to apply.
IsAutomaticForward Boolean Indicates whether an incoming message must be automatically forwarded in order for the condition or exception to apply.
IsAutomaticReply Boolean Indicates whether an incoming message must be an auto reply in order for the condition or exception to apply.
IsEncrypted Boolean Indicates whether an incoming message must be encrypted in order for the condition or exception to apply.
IsMeetingRequest Boolean Indicates whether an incoming message must be a meeting request in order for the condition or exception to apply.
IsMeetingResponse Boolean Indicates whether an incoming message must be a meeting response in order for the condition or exception to apply.
IsNonDeliveryReport Boolean Indicates whether an incoming message must be a non-delivery report in order for the condition or exception to apply.
IsPermissionControlled Boolean Indicates whether an incoming message must be permission controlled (RMS-protected) in order for the condition or exception to apply.
IsReadReceipt Boolean Indicates whether an incoming message must be a read receipt in order for the condition or exception to apply.
IsSigned Boolean Indicates whether an incoming message must be S/MIME-signed in order for the condition or exception to apply.
IsVoicemail Boolean Indicates whether an incoming message must be a voice mail in order for the condition or exception to apply.
MessageActionFlag MessageActionFlag Represents the flag-for-action value that appears on an incoming message in order for the condition or exception to apply.
NotSentToMe Boolean Indicates whether the owner of the mailbox must not be a recipient of an incoming message in order for the condition or exception to apply.
ReceipentContains Collection (String) Represents the strings that appear in either the ToRecipients or CcRecipients properties of an incoming message in order for the condition or exception to apply.
SenderContains Collection (String) Represents the strings that appear in the From property of an incoming message in order for the condition or exception to apply.
Sensitivity Sensitivity Represents the sensitivity level that must be stamped on an incoming message in order for the condition or exception to apply. Possible values are: Normal, Personal, Private, Confidential.
SentCcMe Boolean Indicates whether the owner of the mailbox must be in the CcRecipients property of an incoming message in order for the condition or exception to apply.
SentOnlyToMe Boolean Indicates whether the owner of the mailbox must be the only recipient in an incoming message in order for the condition or exception to apply.
SentToAddresses Collection (Recipient) Represents the email addresses that an incoming message must have been sent to in order for the condition or exception to apply.
SentToMe Boolean Indicates whether the owner of the mailbox must be in the ToRecipients property of an incoming message in order for the condition or exception to apply.
SentToOrCcMe Boolean Indicates whether the owner of the mailbox must be in either a ToRecipients or CcRecipients property of an incoming message in order for the condition or exception to apply.
SubjectContains Collection (String) Represents the strings that appear in the subject of an incoming message in order for the condition or exception to apply.
WithinSizeRange SizeRange Represents the minimum and maximum sizes (in kilobytes) that an incoming message must fall in between in order for the condition or exception to apply.

PatternedRecurrence

The recurrence pattern and range.

Type: Microsoft.OutlookServices.PatternedRecurrence

Property Type Description
Pattern RecurrencePattern The frequency of an event.
RecurrenceTimeZone String The time zone of the start and end times. See the DateTimeTimeZone complex type for the list of supported time zones.
Range RecurrenceRange The duration of an event.

Phone

Represents a phone number.

Type: Microsoft.OutlookServices.Phone

Property Type Description
Number string The phone number.
Type String The type of phone number. Possible values are: Home, Business, Mobile, Other, Assistant, HomeFax, BusinessFax, OtherFax, Pager, Radio.

PhysicalAddress

The physical address of a contact.

Type: Microsoft.OutlookServices.PhysicalAddress

Property Type Description
Street String The street.
City String The city.
State String The state.
CountryOrRegion String The country or region. It's a free-format string value, for example, "United States".
PostalCode String The postal code.

Recipient

Represents information about a user in the sending or receiving end of an event or message.

Type: Microsoft.OutlookServices.Recipient

Property Type Description
EmailAddress EmailAddress The recipient's email address.

RecurrencePattern

The frequency of an event.

Type: Microsoft.OutlookServices.RecurrencePattern

Property Type Description
Type RecurrencePatternType The recurrence pattern type: Daily = 0, Weekly = 1, AbsoluteMonthly = 2, RelativeMonthly = 3, AbsoluteYearly = 4, RelativeYearly = 5.
Pattern rules:
- AbsoluteYearly. Must set the Month and DayOfMonth of the occurrence
- RelativeYearly. Must set the Month, DaysOfWeek, and FirstDayOfWeek index
- AbsoluteMonthly. Must set the DayOfMonth
- RelativeMonthly. Must set the FirstDayOfWeek index and the RecurrenceRange.NumberOfOccurrences
- Weekly. Must set the DaysOfWeek and the FirstDayOfWeek
- Daily. No additional pattern information needed.
Interval Int32 The number of units of a given recurrence type between occurrences.
DayOfMonth Int32 The day of month that the item occurs on.
Month Int32 The month that the item occurs on. This is a number from 1 to 12.
DaysOfWeek Collection(DayOfWeek) A collection of days of the week: Sunday = 0, Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6.
FirstDayOfWeek DayOfWeek The day of the week: Sunday = 0, Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6.
Index WeekIndex The week index: First = 0, Second = 1, Third = 2, Fourth = 3, Last = 4.

RecurrenceRange

The duration of an event.

Type: Microsoft.OutlookServices.RecurrenceRange

Property Type Description
Type RecurrenceRangeType The recurrence range: EndDate = 0, NoEnd = 1, Numbered = 2.
StartDate datetimeoffset Required: The start date of the series.
EndDate datetimeoffset Required for date bound patterns:The end date of the series. Must be after the start date.
NumberOfOccurrences Int32 Required for Numbered patterns: How many times to repeat the event.

ResponseStatus

The response status of a meeting request.

Type: Microsoft.OutlookServices.ResponseStatus

Property Type Description
Response ResponseType The response type: None, Organizer, TentativelyAccepted, Accepted, Declined, NotResponded.
Time datetimeoffset The date and time that the response was returned.

SizeRange (preview)

Specifies the maximum and minimum sizes (in kilobytes) that an incoming message must have in order for a condition or exception to apply.

Type: Microsoft.OutlookServices.SizeRange

Property Type Description
MaximumSize Int32 The maximum size (in kilobytes) that an incoming message must have in order for a condition or exception to apply.
MinimumSize Int32 The minimum size (in kilobytes) that an incoming message must have in order for a condition or exception to apply.

TimeConstraint

Restricts meeting time suggestions to certain hours and days of the week according to the specified nature of activity and open time slots.

Type: Microsoft.OutlookServices.TimeConstraint

Property Type Description
ActivityDomain ActivityDomain Optional, the nature of the activity: Work, Personal, Unrestricted, or Unknown.
Timeslots Collection(TimeSlot) An array of time periods.

TimeSlot

A time period.

Type: Microsoft.OutlookServices.TimeSlot

Property Type Description
Start DateTimeTimeZone The time a period begins.
End DateTimeTimeZone The time the period ends.

TimeZoneInformation (preview)

Represents a time zone. The supported formats are Windows and Internet Assigned Numbers Authority (IANA) time zone (also known as Olson time zone).

Type: Microsoft.OutlookServices.TimeZoneInformation

Property Type Description
Alias String An identifier for the time zone.
DisplayName String A display string that represents the time zone.

Website (preview)

Represents a website.

Type: Microsoft.OutlookServices.Website

Property Type Description
Address String The URL of the web site.
DisplayName String The display name of the web site.
Type WebsiteType The type of web site commonly associated with a contact. Possible values are: Blog, Home, Other, Profile, Work.

WorkingHours (preview)

Represents the days of the week and hours in a specific time zone that the user works.

Type: Microsoft.OutlookServices.WorkingHours

Property Type Description
DaysOfWeek Collection(DayOfWeek) A collection of days of the week on which the user works: Sunday = 0, Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6.
StartTime Edm.TimeOfDay The time of the day that the user starts working.
EndTime Edm.TimeOfDay The time of the day that the user stops working.
TimeZone String The time zone to which the working hours apply. See DateTimeTimeZone for a list of valid time zones.

Enumerations

DayOfWeek

The set of days of the week.

Supported values:

  • Sunday
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday

FreeBusyStatus

Specifies the availability status of an attendee for a meeting.

Supported values:

  • Busy
  • Free
  • Oof
  • Tentative
  • Unknown
  • WorkingElsewhere

ActivityDomain

The nature of an activity.

Supported values:

  • Work
  • Personal
  • Unrestricted
  • Unknown

AutomaticRepliesStatus

The configuration status for automatically sending a reply when the user's mailbox receives a message.

Supported values:

  • AlwaysEnabled
  • Disabled
  • Scheduled

CategoryColor (preview)

The color that characterizes a category in the user's mailbox. The actual color that each pre-set constant represents depends on the Outlook client being used to display the categories.

Supported value Color mapped to in Outlook desktop client
Preset0 Red
Preset1 Orange
Preset2 Brown
Preset3 Yellow
Preset4 Green
Preset5 Teal
Preset6 Olive
Preset7 Blue
Preset8 Purple
Preset9 Cranberry
Preset10 Steel
Preset11 DarkSteel
Preset12 Gray
Preset13 DarkGray
Preset14 Black
Preset15 DarkRed
Preset16 DarkOrange
Preset17 DarkBrown
Preset18 DarkYellow
Preset19 DarkGreen
Preset20 DarkTeal
Preset21 DarkOlive
Preset22 DarkBlue
Preset23 DarkPurple
Preset24 DarkCranberry
None No color mapped

ExternalAudienceScope

The set of external audience to send the ExternalReplyMessage to.

Supported values:

  • All
  • ContactsOnly
  • None

FollowupFlagStatus (preview)

Represents the status of the follow-up flag for a resource instance.

Supported values:

  • Complete
  • Flagged
  • NotFlagged

InferenceClassificationType

Represents the inferred relevance of a message for a user to focus on.

Supported values:

  • Focused
  • Other

LocationType (preview)

The possible types of locations.

Supported values:

  • Default
  • ConferenceRoom
  • HomeAddress
  • BusinessAddress
  • GeoCoordinates
  • StreetAddress
  • Hotel
  • Restaurant
  • LocalBusiness
  • PostalAddress

MailTipsType (preview)

A enumeration of flags that represents the requested mailtips.

Supported values:

  • AutomaticReplies
  • CustomMailTip
  • DeliveryRestriction
  • ExternalMemberCount
  • MailboxFullStatus
  • MaxMessageSize
  • ModerationStatus
  • RecipientScope
  • RecipientSuggestions
  • TotalMemberCount

MessageActionFlag (preview)

Specifies the action to be taken for a message.

Supported values:

  • Any
  • Call
  • DoNotForward
  • FollowUp
  • FYI
  • Forward
  • NoResponseNecessary
  • Read
  • Reply
  • ReplyToAll
  • Review

PhoneType (preview)

The type of phone numbers commonly associated with a contact.

Supported values:

  • Assistant
  • Business
  • BusinessFax
  • Home
  • HomeFax
  • Mobile
  • Other
  • OtherFax
  • Pager
  • Radio

RecipientScopeType (preview)

A enumeration of flags that represents the types of recipient scopes. Recipient scopes are used by administrators to specify certain mailtips to be accessible to only a certain scope.

Supported values:

  • None
  • Internal
  • External
  • ExternalPartner
  • ExternalNonPartner

ReferenceAttachmentPermissions

Access permissions for the file or folder of the reference attachment.

Supported values:

  • Other
  • View
  • Edit
  • AnonymousView
  • AnonymousEdit
  • OrganizationView
  • OrganizationEdit

ReferenceAttachmentProviders

Possible file storage providers for reference attachments.

Supported values:

  • Dropbox
  • OneDriveBusiness
  • OneDriveConsumer
  • Other

Sensitivity

Indicates the level of privacy.

Supported values:

  • Normal
  • Personal
  • Private
  • Confidential

TaskStatus

Specifies the state or progress of a task.

Supported values:

  • Completed
  • Deferred
  • InProgress
  • NotStarted
  • WaitingOnOthers

TimeZoneStandard (preview)

The format to express time zones.

Supported values:

  • Windows
  • Iana

WebsiteType (preview)

Specifies the type of web site commonly associated with a contact.

Supported values:

  • Blog
  • Home
  • Other
  • Profile
  • Work

OData query parameters

You can use standard OData v4.0 query parameters to filter data requests and sort and page results when working with the Mail, Calendar, and Contacts APIs. When specifying query parameters, make sure characters that are reserved for special meanings in an URI are appropriately encoded.

  • $search to search for specific criteria

  • $filter to filter for specific criteria

  • $select to request specific properties

  • $orderby to sort results

  • $top and $skip to page results

  • $expand to expand message attachments and event attachments

  • $count to get the count of entities in a collection. This parameter goes in the URL path: .../me/calendars/$count

Querying with the Mail, Calendar, and Contacts APIs always uses a shallow scope. Only items within the current folder are returned. Deep searches are not supported.

Search requests

You can use the $search parameter to restrict the results of a request to the messages that match a search expression. Search strings are expressed using Advanced Query Syntax (AQS). The results are sorted by the date and time that the message was sent.

Note

You can get up to 250 results from a $search request. You can use $search with only messages. Searching contacts and calendar events is not supported.

You cannot use $filter or $orderby in a search request. If you do, you will receive an error message like this one.

    {
      "error":
      {
        "code":"ErrorInvalidUrlQuery",
        "message":"The query parameter 'OrderBy' is invalid."
      }
    }
Property Description
Attachment Searches for the specified attachment by title.
Bcc Searches the Bcc field.
Body or Content Searches the Body field. Only supported with default searches.
Category Searches the Category field.
Cc Searches the Cc field.
From Searches the From field.
Has Searches the HasAttachments field.
Participants Searches the To, Cc, and Bcc fields.
Received Searches the Received field for a specific date expressed as MM/DD/YYYY.
Sender Searches the Sender field.
Subject Searches the Subject field.
To Searches the To field.

You search common fields by using the $search query parameter without specifying a property. A default search will search the Body, Sender, and Subject properities. The following search will return all messages in the Inbox that contains "pizza" in any of the three default properties.

Let's look at some examples. To make them easier to read, the URLs in the examples have not been URL encoded; however, if you try these examples make sure to URL encode them before you send them to the server.

To get all messages in the Inbox that contain the word "Pizza" in the From, Subject, or Body property, you can use this request.

GET https://outlook.office.com/api/beta/me/messages?$search="pizza"

To get all messages in the Inbox that contain the word "Pizza" in the Subject property, you can use this request.

GET https://outlook.office.com/api/beta/me/messages?$search="subject:pizza"

To get all messages in the Inbox that were sent from a specific person, you can use this request.

GET https://outlook.office.com/api/beta/me/messages?$search="from:help@contoso.com"

The examples above did not include URL encoding, here are the same examples URL encoded and ready to send to your server:

GET https://outlook.office.com/api/beta/me/messages?$search=%22pizza%22
GET https://outlook.office.com/api/beta/me/messages?$search=%22subject:pizza%22
GET https://outlook.office.com/api/beta/me/messages?$search=%22from:help@contoso.com%22

Filter requests

You can use the $filter query parameter to specify search criteria by using the following filter operators.

Not all properties support filtering. Only the resource properties marked "Yes" in the "Filterable?" column in their corresponding tables above can be used. If a property is not filterable, you will get an error message in response, like this one that is returned if you try to filter on the ChangeKey property:

    {
      "error":
      {
        "code":"ErrorInvalidProperty",
        "message":"The property 'ChangeKey' does not support filtering."
      }
    }

If you use a filtering method that is not supported, you will get an error message like this one that is returned when the startswith filter method is used on the Subject property:

    {
      "error":
      {
        "code":"ErrorInvalidUrlQueryFilter",
        "message":"'contains' and 'startswith' are not supported for filtering.  Use Search instead."
      }
    }
Operator Type Example
and Logical And (used to combine multiple criteria) TotalCount gt 0 and ChildFolderCount eq 0
or Logical Or (used to combine multiple criteria) TotalCount gt 0 or ChildFolderCount eq 0
eq Equals IsRead eq false
ne Not equals Importance ne Microsoft.Exchange.Services.OData.Model.Importance'High'
gt Greater than ReceivedDateTime gt 2014-09-01T00:00:00Z
ge Greater than or equal LastModifiedDateTime ge 2014-09-01T00:00:00Z
lt Less than ReceivedDateTime lt 2014-09-01T00:00:00Z
le Less than or equal LastModifiedDateTime le 2014-09-01T00:00:00Z

Use single quotes (') to delimit any String value within the filter criterion. Use %27 to URL-encode the single quote. The String itself is not case-sensitive.

Let's take a look at some examples. To make them easier to read, the URLs in the examples have not been URL encoded; however, if you try these examples make sure to URL encode them before you send them to the server.

To get all the events in the user's default calendar that start on or after a specific date, you can filter on the Start property.

GET https://outlook.office.com/api/beta/me/events?$filter=Start/DateTime ge '2016-04-01T08:00'

To get all the events in the user's calendar with a specific subject, you can filter on the Subject property.

GET https://outlook.office.com/api/beta/me/events?$filter=Subject eq 'Mega Charity Bash'

To get all unread messages in the Inbox, you can filter on the IsRead property.

GET https://outlook.office.com/api/beta/me/messages?$filter=IsRead eq false

To get all messages in the Inbox with attachments, you can filter on the HasAttachments property.

GET https://outlook.office.com/api/beta/me/messages?$filter=HasAttachments eq true

To get all messages in the Inbox received since September 1, 2014, you can filter on the ReceivedDateTime property.

GET https://outlook.office.com/api/beta/me/messages?$filter=ReceivedDateTime ge 2014-09-01

To get all messages in the Inbox sent from "hr@contoso.com", you can filter on the Sender property.

GET https://outlook.office.com/api/beta/me/messages?$filter=From/EmailAddress/Address eq 'hr@contoso.com'

The examples above did not include URL encoding, here are the same examples URL encoded and ready to send to your server:

GET https://outlook.office.com/api/beta/me/events?$filter=Start/DateTime%20ge%20%272016-04-01T08:00%27
GET https://outlook.office.com/api/beta/me/events?$filter=Subject%20eq%20%27Mega%20Charity%20Bash%27
GET https://outlook.office.com/api/beta/me/messages?$filter=IsRead%20eq%20false
GET https://outlook.office.com/api/beta/me/messages?$filter=HasAttachments%20eq%20true
GET https://outlook.office.com/api/beta/me/messages?$filter=ReceivedDateTime%20ge%202014-09-01
GET https://outlook.office.com/api/beta/me/messages?$filter=From/EmailAddress/Address%20eq%20%27hr@contoso.com%27

Select specific properties to be returned

You can use the $select query parameter to specify only the properties your app needs.

Note

When getting mail, calendar and contact items, always use $select to exclude unneeded properties in the response payload in order to maintain reasonable app performance. If you don't include a $select parameter, all properties for the items are returned.

The following example gets the Subject, Sender, and ReceivedDateTime properties for all messages in the Inbox.

GET https://outlook.office.com/api/beta/me/messages?$select=Subject,Sender,ReceivedDateTime

Sort results

You can sort results by using the $orderby query parameter. Set the value of this parameter to a property name and optionally specify ascending (default) or descending order. Remember, you can't use the $orderby query parameter with $search.

The following example without URL encoding gets all messages in the Inbox sorted by the ReceivedDateTime property in descending order.

GET https://outlook.office.com/api/beta/me/messages?$orderby=ReceivedDateTime desc

The same example with URL encoding:

GET https://outlook.office.com/api/beta/me/messages?$orderby=ReceivedDateTime%20desc

Page results

By default, a GET request on a Messages or ChildFolders property, a collection, or a CalendarView returns ten entries (maximum 50). You can change this behavior by using the $top query parameter to set a maximum number. The following example gets the first five messages in the Inbox.

GET https://outlook.office.com/api/beta/me/messages?$top=5

If there are more than five messages in the Inbox, the response includes an odata.nextLink property. The presence of this property indicates there are more items available on the server. The value of this property is a URI that can be used to get the next five items.

GET https://outlook.office.com/api/beta/me/messages?$top=5&$skip=5

Paging is achieved by using the $top parameter to specify a page size and the $skip parameter as a multiple of the page size. By incrementing the $skip parameter value by the page size you can request the next page in the set of results.

Count entities in a collection

You can get the count of entities in a collection by using the $count parameter. You can also filter the count request.

This example gets the count of messages in the Inbox.

GET https://outlook.office.com/api/beta/me/messages/$count

And this example without URL encoding gets the count of unread messages in the Inbox.

GET https://outlook.office.com/api/beta/me/messages/$count?$filter=IsRead eq false

The same example with URL encoding.

GET https://outlook.office.com/api/beta/me/messages/$count?$filter=IsRead%20eq%20false

Putting it all together

You can combine parameters to create complex queries. The following example refines a query of the messages in the Inbox in the following ways:

  • Return only items with Importance set to High.

  • Return only the Subject, Sender, and ReceivedDateTime properties.

  • Return only the first five messages.

Note

URL encoding isn't used and line breaks have been added to make the example easier to read.

https://outlook.office.com/api/beta/me/messages?
    $filter=Importance eq 'High'
    &$select=Subject,Sender,ReceivedDateTime
    &$top=5

When you specify $filter the server will infer a sort order for the results. If you use both $filter and $orderby, the properties in the $filter must be listed first in the $orderby before any other properties, and they must be listed in the order that they appear in the $filter parameter.

The following example shows a query filtered by both the Subject and Importance properties, and then sorted by the Subject, Importance, and Sender properties.

https://outlook.office.com/api/beta/me/messages?
    $filter=Subject eq 'Good Times' AND Importance eq 'High'&
    $orderby=Subject,Importance,Sender

Here's the same example with URL encoding and without line breaks.

https://outlook.office.com/api/beta/me/messages?$filter=Importance%20eq%20%27High%27&select=Subject,Sender,ReceivedDateTime&$top=5

https://outlook.office.com/api/beta/me/messages?$filter=Subject%20eq%20%27Good%20Times%27%20AND%20Importance%20eq%20%27High%27&$orderby=Subject,Importance,Sender

See also