Share via

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

  • Article

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

Note

Version 1.0 of the Outlook REST API is deprecated.

As announced in October 2017, version 1.0 of the Outlook REST API has been deprecated. The v1.0 REST endpoint will be fully decommissioned, and the v1.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 v1.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/v1.0/$metadata).

Attachment

A file or item (contact, event or message) attached to an event or message. The corresponding fileAttachment and itemAttachment 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?
Name String The calendar name. Yes 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
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

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
DateTimeCreated datetimeoffset The time the contact was created. No Yes
DateTimeLastModified 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
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. 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

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

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 and ItemAttachment 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
DateTimeCreated datetimeoffset The date and time that the event was created. No Yes
DateTimeLastModified datetimeoffset The date and time that the event was last modified. No Yes
End datetimeoffset The date and time that the event ends.

By default, the end time is in UTC. You can specify an optional time zone in EndTimeZone, express the end time in that time zone, and include a time offset from UTC. Note that if you use EndTimeZone, you must specify a value for StartTimeZone as well.

This example specifies February 25, 2015, 9:34pm in Pacific Standard Time: "2015-02-25T21:34:00-08:00".		 Yes Yes
EndTimeZone String Identifies the meeting's time zone for the meeting end time (see the End property). This property is set with the time zone name as it is stored in Windows. You can get the time zone names by calling System.TimeZoneInfo.GetSystemTimeZones().

This property is optional for v1.0. However, this property must be used if the StartTimeZone property is used.

See TimeZone for more information.		 Yes No
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
Location Location The location of the event. Yes Yes
Organizer Recipient The organizer of the event. Yes Yes
Recurrence PatternedRecurrence The recurrence pattern for the event. 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 datetimeoffset The start time of the event.

By default, the start time is in UTC. You can specify an optional time zone in StartTimeZone, express the start time in that time zone, and include a time offset from UTC. Note that if you use StartTimeZone, you must specify a value for EndTimeZone as well.

This example specifies February 25, 2015, 7:34pm in Pacific Standard Time: "2015-02-25T19:34:00-08:00".		 Yes Yes
StartTimeZone String Identifies the meeting's time zone for the meeting start time (see the Start property). This property makes it so the service handles time zone changes instead of the client. This property is set with the time zone name as it is stored in Windows. You can get the time zone names by calling System.TimeZoneInfo.GetSystemTimeZones().

This property is optional for v1.0. However, this property must be used if the EndTimeZone property is used.

An example value for this property is "Pacific Standard Time". See TimeZone for more information.		 Yes No
Subject String The text of the event's subject line. 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

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

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

FileAttachment

A file (such as a text file or Word document) attached to a message or event. 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
DateTimeLastModified datetimeoffset The date and time when the attachment was last modified. No
Id String The attachment ID. No
IsContactPhoto boolean Obsolete. Yes
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 versions after v1.0, the Folder entity and type 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.Folder

A Folders 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(Folder) 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

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/v1.0/me/folders/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

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

InferenceClassificationOverride

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

ItemAttachment

A message, contact, or event that's attached to another message or event. 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
DateTimeLastModified 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
DateTimeCreated datetimeoffset The date and time the message was created. No Yes No
DateTimeLastModified datetimeoffset The date and time the message was last changed. No Yes No
DateTimeReceived datetimeoffset The date and time the message was received. No Yes Yes
DateTimeSent datetimeoffset The date and time the message was sent. No Yes No
From Recipient The mailbox owner and sender of the message. Yes Yes Yes
HasAttachments boolean Indicates whether the message has attachments. Yes 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
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
ParentFolderId String The unique identifier for the message's parent folder. No No No
ReplyTo Collection (Recipient) The email addresses to use when replying. Yes No No
Sender Recipient The account that is actually used to generate the message. Yes Yes Default
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

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

ReferenceAttachment

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.

Task

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

TaskFolder

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

TaskGroup

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

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
Folders Collection(Folder) The folders in a mailbox or folder. Navigation property. No No
Id String The unique identifier for the user. No No
MailboxGuid guid The GUID assigned to the user's mailbox. No Yes
Messages Collection(Message) The messages in a mailbox or folder. Navigation property. No No
RootFolder Folder 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: Required, Optional, Resource.

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.

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.

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.

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

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

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/v1.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/v1.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/v1.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/v1.0/me/messages?$search=%22pizza%22
GET https://outlook.office.com/api/v1.0/me/messages?$search=%22subject:pizza%22
GET https://outlook.office.com/api/v1.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 DateTimeReceived gt 2014-09-01T00:00:00Z
ge Greater than or equal DateTimeLastModified ge 2014-09-01T00:00:00Z
lt Less than DateTimeReceived lt 2014-09-01T00:00:00Z
le Less than or equal DateTimeLastModified 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 calendar with a specific subject, you can filter on the Subject property.

GET https://outlook.office.com/api/v1.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/v1.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/v1.0/me/messages?$filter=HasAttachments eq true

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

GET https://outlook.office.com/api/v1.0/me/messages?$filter=DateTimeReceived 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/v1.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/v1.0/me/events?$filter=Subject%20eq%20%27Mega%20Charity%20Bash%27
GET https://outlook.office.com/api/v1.0/me/messages?$filter=IsRead%20eq%20false
GET https://outlook.office.com/api/v1.0/me/messages?$filter=HasAttachments%20eq%20true
GET https://outlook.office.com/api/v1.0/me/messages?$filter=DateTimeReceived%20ge%202014-09-01
GET https://outlook.office.com/api/v1.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 DateTimeReceived properties for all messages in the Inbox.

GET https://outlook.office.com/api/v1.0/me/messages?$select=Subject,Sender,DateTimeReceived

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 DateTimeReceived property in descending order.

GET https://outlook.office.com/api/v1.0/me/messages?$orderby=DateTimeReceived desc

The same example with URL encoding:

GET https://outlook.office.com/api/v1.0/me/messages?$orderby=DateTimeReceived%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/v1.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/v1.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/v1.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/v1.0/me/messages/$count?$filter=IsRead eq false

The same example with URL encoding.

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

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

See also