Back

Microsoft Exchange API Essential Guide

Aug 2, 20246 minute read

What type of API does Microsoft Exchange provide?

Microsoft Exchange supports multiple types of APIs, including:

REST API

Microsoft Graph is the recommended REST API for accessing Exchange Online data. It provides REST APIs for mail, calendars, and contacts. New applications designed to access Exchange Online data should use Microsoft Graph.

SOAP API

Exchange Web Services (EWS) is a SOAP-based API that has been widely used for Exchange development. While still supported, Microsoft recommends using Microsoft Graph for new development.

Other APIs

  • Exchange ActiveSync - For mobile device access
  • Exchange Management Shell - For PowerShell-based management
  • EWS Managed API - A .NET client library for accessing EWS

Key Points

  • Microsoft Graph (REST) is the recommended API for new Exchange Online development
  • EWS (SOAP) is still supported but being phased out in favor of Microsoft Graph
  • Multiple API options exist depending on the specific use case and client technology

Best Practices

  • Use Microsoft Graph for new Exchange Online applications
  • Consider EWS for on-premises Exchange or legacy applications
  • Choose the appropriate API based on your specific requirements and client platform

In summary, while Exchange has historically supported SOAP via EWS, Microsoft is moving towards REST APIs with Microsoft Graph as the recommended approach for new Exchange Online development. The choice of API depends on factors like on-premises vs cloud deployment, client platform, and specific functionality needed.

Does the Microsoft Exchange API have webhooks?

Exchange Online (Office 365)

  1. Exchange Online supports webhooks through the Microsoft Graph API.

  2. You can use the Graph API to subscribe to change notifications for events.

  3. The webhook functionality for Exchange Online is available through this endpoint: https://learn.microsoft.com/en-us/graph/api/subscription-post-subscriptions?view=graph-rest-1.0&tabs=http.

On-Premises Exchange (Exchange 2016, 2019)

  1. On-premises Exchange does not support webhooks directly.

  2. For on-premises Exchange, you need to use Exchange Web Services (EWS) notifications.

  3. EWS supports three types of notifications: push, pull, and streaming.

  4. You can read more about EWS notifications here: https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/notification-subscriptions-mailbox-events-and-ews-in-exchange.

Events and Subscriptions

  1. For Exchange Online (using Graph API), you can subscribe to various events, including changes to calendars, emails, and other mailbox items.

  2. With EWS (for on-premises Exchange), you can subscribe to mailbox events, but the notifications are more limited compared to Graph API.

  3. EWS notifications generally just inform you that something has been modified, without providing detailed delta information.

Best Practices and Considerations

  1. If you're building a new application and all your clients are on Office 365, it's recommended to use Graph API for webhooks and delta queries.

  2. If you have a mix of on-premises and Office 365 mailboxes, you may need to implement both EWS (for on-premises) and Graph API (for Office 365) solutions.

  3. While you can use EWS against Exchange Online, it's not recommended and may be discontinued in the future.

  4. For calendar synchronization, Graph API provides a more advanced implementation that handles recurrence better than EWS.

In summary, the official Microsoft Exchange API does have webhook support, but it depends on whether you're using Exchange Online (Office 365) or on-premises Exchange. Exchange Online supports webhooks through the Graph API, allowing you to subscribe to various mailbox events. On-premises Exchange relies on EWS notifications, which are more limited but still provide event notification capabilities.

Rate Limits and other limitations

Here are the key points about API rate limits for the Microsoft Exchange API and Microsoft Graph:

General Limits

  • Microsoft Graph has a global limit of 130,000 requests per 10 seconds per app across all tenants.

  • For Outlook/Exchange resources specifically, there are limits applied per mailbox:

    • 10,000 API requests in a 10 minute period
    • 4 concurrent requests
    • 150 MB upload in a 5 minute period

Per-User Limits

  • The general throttling limit for Microsoft Graph API is 10,000 requests every 10 minutes per user per app.

  • This limit applies to each user separately, even if using the same user to access multiple mailboxes.

  • So if you are using one signed-in user to access multiple mailboxes, the 10,000 request limit applies in total across all mailboxes accessed by that user, not per individual mailbox.

Other Relevant Limits

  • For Microsoft Teams, there are limits like 30 requests per second per app.

  • OneNote has limits of 120-240 requests per minute depending on context.

  • Identity and access reports have a limit of 5 requests per 10 seconds per app per tenant.

Best Practices

  • Monitor your application's usage and implement caching, query optimization, etc. to avoid hitting limits.

  • For large data sets, use filtering and pagination to limit data returned per request.

  • Implement proper error handling for 429 (Too Many Requests) responses.

  • Consider using multiple user accounts to distribute load if accessing many mailboxes.

The key takeaway is that the 10,000 request per 10 minute limit applies in total to the signed-in user across all mailboxes accessed, not individually per mailbox. Proper monitoring and optimization is important to stay within the limits when accessing multiple mailboxes.

Latest API Version

Based on the search results, here are the key points about the most recent version of the Microsoft Exchange API:

  1. The most recent version is Exchange Server Subscription Edition (Exchange Server SE), which is scheduled to be released in early Q3 2025 [1].

  2. Before Exchange Server SE, the latest version is Exchange Server 2019. The final Cumulative Update (CU) for Exchange Server 2019 - CU15 - will be released later in 2024 [1].

  3. Exchange Server SE will introduce several new features and changes, including:

    • Support for Transport Layer Security (TLS) 1.3
    • Reintroduction of certificate management in the Exchange admin center (EAC)
    • Support for Windows Server 2025
    • Removal of Outlook Anywhere
    • Introduction of an Admin API and deprecation of Remote PowerShell (RPS) [1]
  4. For developers, Microsoft Graph is now the recommended API for accessing Exchange Online data. New applications designed to access Exchange Online data should use Microsoft Graph [3].

  5. The Exchange Web Services (EWS) Managed API is still available but is no longer being actively developed. It includes two APIs: Microsoft.Exchange.WebServices.dll and Microsoft.Exchange.WebServices.Auth.dll [2].

  6. For PowerShell users, the latest version is the Exchange Online PowerShell V3 module (EXO V3 module), released in September 2022. This version uses REST API for all Exchange Online PowerShell cmdlets, eliminating the need for Basic authentication in WinRM [4].

In summary, while Exchange Server SE is the upcoming major release, Microsoft Graph is currently the most up-to-date and recommended API for new development targeting Exchange Online. For on-premises deployments, Exchange Server 2019 remains the current version until Exchange Server SE is released in 2025.

How to get a Microsoft Exchange developer account and API Keys?

1. Sign up for a Microsoft 365 Developer Program account

  • Go to the Microsoft 365 Developer Program website.
  • Sign up for a free developer account, which includes a Microsoft 365 E5 developer subscription.
  • This provides you with a sandbox environment to develop and test your integration.

2. Set up your development environment

  • Install Visual Studio (a free version is available).
  • Install the .NET Framework (version 3.5 or later).
  • Download and install the EWS Managed API if you plan to use it.

3. Register your application in Azure AD

  • Sign in to the Azure portal using your Microsoft 365 developer account.
  • Go to Azure Active Directory > App registrations > New registration.
  • Provide a name for your app and configure the settings.
  • After registering, note down the Application (client) ID and Directory (tenant) ID.

4. Configure API permissions

  • In your app registration, go to API permissions.
  • Add the necessary permissions for Exchange Online (e.g. Mail.Read, Mail.Send).
  • Grant admin consent for the permissions.

5. Get authentication credentials

  • In your app registration, go to Certificates & secrets.
  • Create a new client secret or upload a certificate to use for authentication.

6. Start developing your integration

What can you do with the Microsoft Exchange API?

Based on the search results provided, here is a list of data models that can be interacted with using the Microsoft Exchange API, along with what is possible for each:

Mailbox Storage

  • Hierarchical structure of folders, items, and properties
  • Perform queries on stored data
  • Access based on user and store permissions
  • Typically accessed using REST, EWS, or EWS Managed API

Message Transport

  • Send and receive messages
  • Use transport agents to process messages during delivery
  • Accessible via REST, EWS, and EWS Managed API

Calendar Items

  • Access and manipulate appointments and meetings
  • Manage recurrence patterns
  • Handle free/busy status

Contacts

  • Read and write contact information
  • Manage contact pictures

Tasks

  • Create and manage task items

Email Messages

  • Read and write email properties
  • Handle attachments
  • Manage categories

User Profiles

  • Access user information

Folders

  • Create, read, and write to folders

Rules

  • Manage mailbox rules

Accounts

  • Manage account information
  • Handle account changes and notifications
  • Perform searches across mailbox items

Custom Properties

  • Set and retrieve custom properties on items

Reminders

  • Manage reminders for various item types

Distribution Lists

  • Manage Exchange distribution lists

Stores

  • Access and manage message stores for accounts

Conversations

  • Work with conversation-based message groupings

Views

  • Customize and manage views of mailbox data

Each of these data models can be accessed and manipulated using various Exchange APIs, with the specific capabilities depending on the chosen API (e.g., REST, EWS, EWS Managed API, or MAPI) and the version of Exchange being targeted.