Share via

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

  • Article

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

Note

Version 2.0 of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. The v2.0 REST endpoint will be fully decommissioned in March 2024, and the v2.0 documentation will be removed shortly afterwards. 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 v2.0 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/v2.0/$metadata).

Attachment

A file or item (contact, event or message) attached to an event, message, or task. The corresponding fileAttachment, itemAttachment, and referenceAttachment resources are 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
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
BusinessAddress PhysicalAddress The contact's business address. Yes Yes
BusinessHomePage String The business home page of the contact. Yes Yes
BusinessPhones Collection(String) The contact's business phone numbers. Yes No
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
Department String The contact's department. Yes Yes
CreatedDateTime datetimeoffset The time the contact was created. No Yes
LastModifiedDateTime datetimeoffset The time the contact was modified. No 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
Generation String The contact's generation. Yes Yes
GivenName String The contact's given name. Yes Yes
HomeAddress PhysicalAddress The contact's home address. Yes Yes
HomePhones Collection(String) The contact's home phone numbers. Yes No
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
Manager String The name of the contact's manager. Yes Yes
MiddleName String The contact's middle name. Yes Yes
MobilePhone1 String The contact's mobile phone number. Yes Yes
NickName String The contact's nickname. Yes Yes
OfficeLocation String The location of the contact's office. Yes Yes
OtherAddress PhysicalAddress Other addresses for the contact. 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
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
YomiCompanyName String The phonetic Japanese company name of the contact. Yes No
YomiGivenName String The phonetic Japanese given name (first name) of the contact. Yes No
YomiSurname String The phonetic Japanese surname (last name) of the contact. 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
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
LastModifiedDateTime datetimeoffset The date and time that the event was last modified. No Yes
End DateTimeTimeZone The end time of the event. 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
Location Location The location of the event. 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 = 0, Personal = 1, Private = 2, Confidential = 3. Yes Yes
SeriesMasterId String The categories assigned to the item. Yes No
ShowAs FreeBusyStatus The status to show: Free = 0, Tentative = 1, Busy = 2, Oof = 3, WorkingElsewhere = 4, Unknown = -1. Yes Yes
Start DateTimeTimeZone The start time of the event. Yes Yes
Type EventType The event type: SingleInstance = 0, Occurrence = 1, Exception = 2, SeriesMaster = 3. 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?
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
MeetingMessageType MeetingMessageType The type of event message: None = 0, MeetingRequest = 1, MeetingCancelled = 2, MeetingAccepted = 3, MeetingTentativelyAccepted = 4, MeetingDeclined = 5 No Yes

EventMessageRequest (preview)

This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.

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 v2.0, 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
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
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/v2.0/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 which 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 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)

This feature is currently available in only beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.

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 Writable? 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 the email belongs to. No Yes 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
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 Yes
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
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
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
SentDateTime datetimeoffset The date and time the message was sent. No 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
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)

This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.

OutlookCategory (preview)

This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.

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 and ItemAttachment 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
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.Recipient

Property Type Description
Status ResponseStatus The response (none, accepted, declined, etc.) and time.
Type AttendeeType The type of the attendee. Possible values are: Required, Optional, Resource.

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.

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.

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.

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

The location of an event.

Type: Microsoft.OutlookServices.Location

Property Type Description
DisplayName String The name associated with the location.
Address PhysicalAddress The physical address of the location.
Coordinates GeoCoordinates The geographic coordinates and elevation of the location.
LocationEmailAddress String Optional email address of the location.

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.

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.

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.

PatternedRecurrence

The recurrence pattern and range.

Type: Microsoft.OutlookServices.PatternedRecurrence

Property Type Description
Pattern RecurrencePattern The frequency of an event.
Range RecurrenceRange The duration of an event.

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.

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.

Enumerations

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

DayOfWeek

The set of days of the week.

Supported values:

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

ExternalAudienceScope

The set of external audience to send the ExternalReplyMessage to.

Supported values:

  • All
  • ContactsOnly
  • None

FreeBusyStatus

Specifies the availability status of an attendee for a meeting.

Supported values:

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

InferenceClassificationType

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

Supported values:

  • Focused
  • Other

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

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/v2.0/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/v2.0/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/v2.0/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/v2.0/me/messages?$search=%22pizza%22
GET https://outlook.office.com/api/v2.0/me/messages?$search=%22subject:pizza%22
GET https://outlook.office.com/api/v2.0/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 in 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/v2.0/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/v2.0/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/v2.0/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/v2.0/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/v2.0/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/v2.0/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/v2.0/me/events?$filter=Start/DateTime%20ge%20%272016-04-01T08:00%27
GET https://outlook.office.com/api/v2.0/me/events?$filter=Subject%20eq%20%27Mega%20Charity%20Bash%27
GET https://outlook.office.com/api/v2.0/me/messages?$filter=IsRead%20eq%20false
GET https://outlook.office.com/api/v2.0/me/messages?$filter=HasAttachments%20eq%20true
GET https://outlook.office.com/api/v2.0/me/messages?$filter=ReceivedDateTime%20ge%202014-09-01
GET https://outlook.office.com/api/v2.0/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/v2.0/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/v2.0/me/messages?$orderby=ReceivedDateTime desc

The same example with URL encoding:

GET https://outlook.office.com/api/v2.0/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/v2.0/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/v2.0/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/v2.0/me/messages/$count

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

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

The same example with URL encoding.

GET https://outlook.office.com/api/v2.0/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/v2.0/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/v2.0/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/v2.0/me/messages?$filter=Importance%20eq%20%27High%27&select=Subject,Sender,ReceivedDateTime&$top=5

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

See also