Exchange Web Services (EWS) in Exchange 2010
Last modified: September 21, 2010
Applies to: Exchange Server 2007 | Exchange Server 2010
In this article
Exchange Web Services Features
Versioning
Public Folder Access
Folder-Level Permissions
Identifier Conversion
Related Sections
Exchange Web Services (EWS) provides the functionality to enable client applications to communicate with the Exchange server. EWS provides access to much of the same data that is made available through Microsoft OfficeOutlook. EWS clients can integrate Outlook data into Line-of-Business (LOB) applications. SOAP provides the messaging framework for messages sent between the client application and the Exchange server. The SOAP messages are sent by HTTP.
EWS is described by three files:
Services.wsdl Describes the contract between client and server.
Messages.xsd Defines the request and response SOAP messages.
Types.xsd Defines the elements used in the SOAP messages.
These schema files are located in the IIS virtual directory that hosts Exchange Web Services of the computer that is running Microsoft Exchange Server that has the Client Access server role installed.
Exchange Web Services Features
EWS provides the following types of operations:
Availability
Bulk Transfer (new in Exchange 2010)
Conversations (new in Exchange 2010)
Delegate Management
Exchange Store Search
Exchange Search (new in Exchange 2010)
Federated Sharing (new in Exchange 2010)
Folder
Inbox Rules (new in Exchange 2010)
Item
Mail Tips (new in Exchange 2010)
Messaging Records Management
Message Tracking (new in Exchange 2010)
Notification
Service Configuration (new in Exchange 2010)
Synchronization
Unified Messaging (new in Exchange 2010)
User Configuration (new in Exchange 2010)
Utility
Availability Operations
The Availability operations improve information workers' calendar and free/busy sharing experience by providing secure, up-to-date, and rich free/busy information. This information enables developers to create sophisticated collaboration and scheduling applications.
The Availability Web service provides tools to create enhanced Exchange Server 2010 client applications by doing the following:
Retrieving live free/busy information for Exchange 2010 mailboxes.
Retrieving live free/busy information from other Exchange 2010 forests.
Retrieving published free/busy information from public folders.
Retrieving suggested meeting times.
Supplying up-to-date free/busy data so that users and resources can be scheduled with more confidence.
Supplying more specific data that describes the status of users and resources, such as the start times and the end times of individual appointments, subjects, locations, work hours, and so on.
Securing the distribution of free/busy data by specifying the level of detail to share with specified users.
In addition, the Availability operations enable the user to share their calendar information in more granular ways. For each target person/group, the user can select one of four levels of sharing:
Share nothing
Share their free/busy information
Share more detail including subject, location, and timing
Share full calendar details
Exchange 2010 includes new operations that allow you to find available rooms for meetings.
Bulk Transfer Operations
The Bulk Transfer operations enable the streaming of items into and out of a mailbox.
Conversations Operations
The Conversations operations enable the finding and managing of e-mail messages that are grouped based on the conversation.
Delegate Management Operations
The Delegate Management operations enable clients to add, update, get, and remove delegates from their mailbox. Four Exchange Web Services operations provide delegate management functionality. These operations enable you to do the following:
Add new delegates.
Retrieve and update existing delegate permissions.
Remove existing delegates.
Delegate access supports the following types of scenarios:
Delegates can open the folders of a principal and manipulate items based on folder-level permissions.
Delegates can create and send meeting messages on behalf of the principal.
Delegates can receive meeting messages that are forwarded by the principal and respond to them for the principal.
Users who have owner rights on a shared mailbox can open the mailbox and act as the owner.
Delegates can create notification subscriptions on folders in the mailbox of the principal.
Federated Sharing Operations
The Federated Sharing operations enable clients to share calendar data or contacts data. These operations are new in Exchange 2010.
Folder Operations
The Folder operations provide access to folders in the Exchange data store. A client application can create, update, delete, copy, find, get, and move folders that are associated with a mailbox user. Folders are used to gain access to items in the store, and provide a reference container for items in the store.
The folder operations enable client applications to do the following:
Get the identity of a single folder.
Identify which folder properties are returned by a request.
Enumerate the items or folders that are descendants of a single folder.
Access data fields in an item or folder.
Search a folder hierarchy.
Use search restrictions to narrow the response set.
Create search folders.
Provide support for delegate and administrative access to items and folders in the store.
Empty the contents of a folder in a single operation.
Inbox Rules Operations
Inbox Rules operations provide for sets of conditions and associated actions that enable a user to automatically organize, categorize, and act on messages as the messages are delivered to a folder.
Inbox Rules enable you to create, update, and delete rules on a user’s mailbox. The following is a partial list of actions that can be performed on a rule:
MoveToFolder — When a message arrives that meets the conditions of the rule, move the message to a specified folder.
CopyToFolder — When a message arrives that meets the conditions of the rule, copy the message to a specified folder.
MarkImportance — When a message arrives that meets the conditions of the rule, mark the message with a low, normal, or high importance flag.
Delete — When a message arrives that meets the conditions of the rule, delete the message
Item Operations
The Item operations provide access to items in the Exchange data store. By using these operations, a client application can create, update, delete, copy, get, move, and send items. The Item operations work on the following item types:
Message Items Message items are XML representations of the Internet Message Format defined in [RFC2822] that are defined in e-mail messages.
Contact Items Contact items are a set of properties that represent contacts that are located either in the Active Directory directory service or in private contact stores. It is important to note that, while these two types of contacts are similar in data content, they differ in the types of operations that you can perform on them.
Task Items Task items are the Outlook Personal Information Manager (PIM) objects that can be accessed by the Task pane. Tasks can be single items or recurring activities.
Calendar Items Calendar items identify the location, resources, recurrence, and attendees involved at a discrete time. Calendar items are represented by Meetings, Appointments, Meeting Invitations, and Invitation-handling objects. Meeting organizers can create, update, and delete both individual and recurring meetings. Organizers can also send out meeting invitations. Meeting attendees can accept, decline, and acknowledge the receipt of invitations and counter-propose a time or recurring schedule for a meeting.
Mail Tips Operations
The Mail Tips operations enable clients to request information from the server regarding recipient mailboxes when an author is composing a message. These operations are new in Exchange 2010.
Messaging Records Management Operations
The Messaging Records Management operation enables the assignment of managed custom folders to mailbox users. Client applications that consume this Web service give users the ability to add managed custom folders to their mailbox instead of having an administrator perform the task. Administrators in large organizations do not have the resources to set up user subscriptions to policy folders. Frequently, administrators do not know which policy folders an individual user should use. Users can subscribe to individual policy folders. This works in addition to policy folders assigned to groups of users by the administrators.
Message Tracking Operations
The Message Tracking operations enable clients to find messages that meet specified criteria and to get detailed tracking information about each message in a message tracking report. These operations are new in Exchange 2010.
Notification Operations
The Notification operations notify client systems of events and changes in mailboxes on computers that are running Exchange 2010. Clients subscribe for notifications to the Event Notifications subsystem, and specify the types of events to monitor on the specified mailboxes. The Notification operations provide push and pull subscriptions from the Exchange 2010 computer that is running the Client Access server role. The following are the events that are monitored by the Event Notification subsystem:
Mail arrival
Item creation
Item deletion
Item modification
Item movement
Item copied
Mail submission
Service Configuration Operations
The Service Configuration operations enable clients to retrieve service configuration data (for mail tips, Unified Messaging, and protection rules). These operations are new in Exchange 2010.
Synchronization Operations
The Synchronization operations provide a one-way, synchronized cached copy of a user's folders and items. This Web service provides the following forms of synchronization:
Folder Hierarchy A client synchronizes the folder hierarchy of a whole mailbox or any subfolder hierarchy within the mailbox.
Folder Items A client synchronizes all items in a folder.
Clients can also explicitly ignore items so that they are not synchronized, and specify how many items should be synchronized between server and client.
Unified Messaging Operations
The Unified Messaging operations enable clients to read information about Unified Messaging properties, and play voice mails over the telephone. These operations are new in Exchange 2010.
In Exchange 2010, we recommend that you use the Unified Messaging operations that are available in Exchange Web Services (EWS) instead of the Unified Messaging Web service, for the following reasons:
The EWS-based Unified Messaging features have first class support in the Microsoft Exchange Web Services Managed API.
In the future, all new Unified Messaging features will be added to EWS but not to the Unified Messaging Web service.
User Configuration Operations
The User Configuration operations enable clients to create, delete, retrieve, and update user configuration information. These operations are new in Exchange 2010.
Utility Operations
The Utility operations enable client applications to resolve ambiguous names, return the membership of a distribution list, and get a list of time zone definitions that are supported by the Exchange server. The GetServerTimeZones operation is new in Exchange 2010.
Versioning
Exchange 2010 includes a SOAP header element that is used to version SOAP requests. The SOAP header is required to identify a client as Exchange 2010 compliant.
Public Folder Access
You can use the Exchange Web Services operations to access public folders. This includes the following functionality:
Access to the public folder hierarchy
Access to detailed information about public folders
Access to detailed information about public folder items
The ability to post items
The ability to synchronize public folder items
Subscription notifications for public folders
Folder-Level Permissions
Exchange Web Services provides folder-level permissions. You can access and set these permissions by using the CreateFolder, GetFolder, UpdateFolder, and SyncFolderHierarchy operations. This includes the following functionality:
Clients can query and configure the sharing of permissions on the folder.
Clients can retrieve the effective rights to get the effective permission for the logon user.
Free/busy calendar folder permissions are exposed.
Identifier Conversion
In EWS, you can use the ConvertId operation to convert different item identifiers. The ConvertId operation supports public folders, mailbox folders, and item identifiers. The following are the supported identifier formats:
The initial release of Exchange 2007 Exchange Web Services identifiers. These are the identifiers that Exchange Web Services creates and consumes for folders and items in Exchange 2007.
Exchange Web Services 2007 SP1 or Exchange Web Services 2010 identifiers. These are the identifiers that Exchange Web Services creates and consumes for folders and items in Exchange 2007 SP1 and Exchange 2010.
EntryID identifiers. These are provided by MAPI components.
Outlook Web App identifiers. These are the identifiers that are created by Outlook Web App and offered to consumers in the query string of the Outlook Web App URL.
Availability Calendar ID identifiers. These identifiers are hexadecimal-encoded entry IDs that are used by the Availability feature to represent calendar items in a GetUserAvailability response.
Note
Exchange 2007 SP1 and Exchange 2010 use the same identifier format, and this identifier format is different than the identifier format that the initial release version of Exchange 2007 uses.