Email Migration with Microsoft Graph API: What IT Administrators Need to Know

Microsoft has now officially deprecated Exchange Web Services (EWS) for Exchange Online, meaning that EWS requests for non-Microsoft applications will begin to be blocked from October 1st, 2026, with full retirement completed by April 2027.

This poses a serious risk to all organizations that have custom-built scripts and tools or use third-party solutions which rely on EWS for mailbox migration, discovery, or backup. Microsoft’s only recommended alternative is Microsoft Graph API.

Overview of Microsoft Graph API

Microsoft Graph API is a unified API endpoint allowing developers to access and manage all Microsoft 365 services. In terms of email migration, Graph API allows you to migrate mailbox content, including emails, attachments, calendar data, contacts, & folder structures between Exchange Online mailboxes, using the mailbox import and export APIs that replace the equivalent EWS functionality.

It can be used to complement traditional migration methods or replace them with more secure and effective alternatives such as Outlook or EWS (which is deprecated).

Reasons to Consider Microsoft Graph API For Email Migration

Microsoft Graph API is recommended and designed to be the future-proof way to migrate mailboxes because:

• EWS relies heavily on basic authentication, whereas Microsoft Graph mandates OAuth 2.0 via Microsoft Entra ID.

• Graph API can be used with application-only permission to migrate thousands of mailboxes at once without interacting with end-users.

• Microsoft Graph preserves all message headers, To, Cc, Bcc addresses, read/unread status, attachments, categories, and folder hierarchy when migrating emails.

  Prerequisites for Email Migration with Microsoft Graph API

The following information must be available before you start writing code using a Graph-based migration utility:

1.    Microsoft Entra ID (Azure AD) Application Registration

To access Microsoft 365 data, an application must be registered in Entra ID, which will provide the following credentials:

• Client ID

• Tenant ID

• Client secret or certificate

2.    Microsoft Graph Permissions

Permissions (Mail.ReadWrite, Mail.Send, MailboxSettings.Read, User.Read.All, Calendars.ReadWrite & Contacts.ReadWrite) must be granted to the application for it to be able to access emails, calendars, contacts, and other mailbox data. Also, Admin Consent must be granted for all these permissions.

How Does Email Migration with Microsoft Graph API Work?

An email migration that uses Microsoft Graph API typically works in the following way:

1. Authentication: The migration application authenticates against the Microsoft Entra ID server using the OAuth 2.0 client credentials grant type (Delegated Permissions or Application Permissions).

2. Sending the Request: The app sends a standard HTTP request to https://graph.microsoft.com, attaching the access token as a “Bearer” token in the HTTP header.

3. Workload Routing: The Microsoft Graph API serves as a reverse proxy, processing the incoming request and validating the permissions of the token before routing the command to the relevant backend Microsoft 365 microservice.

4. Response Delivery: The backend service processes the command and routes the data back through the Graph gateway in a standard JSON format.

Challenges of Email Migration with Microsoft Graph API

Although Graph API is a powerful tool for email migration, IT administrators should consider the following challenges before doing a large-scale mailbox migration:

• Throttling: Microsoft Graph employs aggressive request throttling and rate limiting to prevent application overload. Microsoft Graph only allows 10,000 requests per 10 minutes per application per mailbox.

• Preserving Message Metadata: When you create a new email message in Graph, it will have the current date and time as its received time.

• Delta Migration: Email migration projects typically require incremental or delta migration to synchronize changes between source and target mailboxes.

• Label & Compliance Mapping: If you are migrating emails from a non-Microsoft source mailbox such as Gmail or Zimbra or an IMAP server, you will need to handle label and compliance tag migration.

IT Administrators Checklist When Working with Microsoft Graph API

Consider the following best practices when using Microsoft Graph API for email migration:

• User application access policies: When configuring mailbox access applications, avoid using administrator accounts or granting access to all mailboxes.

• Plan for throttling: Plan your Graph API migration in such a way that you can complete the migration of 50-100 mailboxes every hour.

• Test with pilot batch: Always perform a trial Graph API mailbox migration with 5-10 mailboxes and confirm the folder hierarchy, number of migrated emails, and metadata before full-scale migration.

• Enable auditing and logging: Use Graph API’s auditing and logging features to track migration activities and troubleshoot any issues.

• Notify users: Even though Graph API mailbox migrations have zero downtime, it is always a good idea to notify users prior to migration.

Last Say

As of now, Microsoft Graph API is the only viable option for email migration to Microsoft 365. It is the future of email migration, as it is more reliable and secure than legacy migration methods and should be considered by all IT administrators. However, working with Graph API can be challenging, especially when performing large-scale mailbox migrations. As such, it is advisable to use professional Graph API-based migration tools for email migration to Microsoft 365.