Mailbox Import/Export Microsoft Graph APIs Now Generally Available

What's Changing

Microsoft has announced general availability (GA) of the mailbox import and export Microsoft Graph APIs, marking the completion of a modern replacement for the deprecated Exchange Web Services (EWS). These APIs provide full-fidelity mailbox data migration capabilities with granular permission controls and support for primary and shared mailboxes in Exchange Online.

The APIs moved from preview to GA with minimal breaking changes, meaning organizations who pilot-tested the preview will find the API contract largely stable for production deployment.

Who's Affected & When

This GA release affects all organizations with Exchange Online subscriptions. The APIs are:

• Now available: All tenants can use the mailbox import and export APIs immediately
• Opt-in: APIs are not auto-enabled; you must register an application in Microsoft Entra ID and request the appropriate Graph permissions
• Supported mailbox types (GA): Primary mailboxes and shared mailboxes only
• NOT yet supported: Archive mailboxes, public folders, and group mailboxes (roadmap pending)
• Regional availability: Worldwide for all Exchange Online regions
• License requirement: Exchange Online subscription required

There is no deprecation deadline announced yet for EWS, but Microsoft guidance indicates new development should target the Graph APIs for all future mailbox automation.

What This Means for Your Environment

The GA release removes the preview designation and opens these APIs for production use. If you have EWS scripts or applications performing mailbox migrations, data exports, or folder management, you now have a supported, modern alternative.

Immediate Impact

Migration and automation workflows: You can now confidently build production integrations using the Graph APIs for primary and shared mailbox operations. The API contract is stable and won't change in breaking ways.

Permission model: The APIs use fine-grained Microsoft Graph permission scopes (e.g., Mail.ReadWrite, Mail.ReadWrite.Shared). You must grant these explicitly at the application level or user delegation level—there's no blanket "access everything" permission.

Data export format: When you export mailbox items, you receive an opaque binary stream. This stream is only valid for re-import back into Exchange Online. You cannot parse it, convert it to XML/JSON, or move it to other systems. This is a deliberate design to ensure full-fidelity preservation of all item metadata.

Archive and public folder gap: If your organization relies on archive mailbox migrations or public folder management, these remain unsupported. You must continue using EWS or other legacy tools for those workloads until the APIs mature.

What You Should Do Now

1. Inventory current EWS usage: Document all scripts, applications, and scheduled tasks that depend on EWS. Prioritize mailbox import/export and folder management operations.
2. Test in non-production: Register an Entra ID application, grant Graph permissions, and run import/export operations against test mailboxes before production rollout.
3. Validate permission scopes: Ensure your application has only the scopes it needs. Use Mail.ReadWrite for general mailbox access, Mail.ReadWrite.Shared if accessing shared mailboxes.
4. Implement retry logic: The APIs use standard Outlook throttling (429 Too Many Requests). Code exponential backoff and respect the Retry-After header.
5. Plan archive/public folder strategy: If you use these mailbox types, do not plan an EWS migration yet. Stay informed via the Microsoft 365 developer blog for GA announcements on those features.

Technical Implementation Essentials

Authentication & Permissions

To use the APIs, your application must authenticate with a Microsoft Entra ID access token and request one or more of these permission scopes:

// Sample: Authenticate and obtain access token (Client Credentials flow)
// Register app in Entra ID, configure certificate or client secret

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={app-id}
&client_secret={secret-or-certificate}
&scope=https://graph.microsoft.com/.default

Core API Operations

The mailbox import/export APIs center on two main jobs:

GET /me/mailFolders

// Returns folder list with IDs, displayName, childFolderCount
// Use folder ID in subsequent export operations

POST /me/mailboxes/{mailbox-id}/exportJobs
Content-Type: application/json

{
  "sourceFolder": "Inbox",
  "targetRootFolder": null
}

// Response: binary stream with full-fidelity item data
// IMPORTANT: Do not parse or modify this stream

POST /me/mailboxes/{mailbox-id}/importJobs
Content-Type: application/octet-stream

[binary export stream from previous export job]

// Response: import job ID and status
// Monitor job completion via GET /importJobs/{id}

POST /me/mailFolders
Content-Type: application/json

{
  "displayName": "Archived 2024"
}

// Create subfolders:
POST /me/mailFolders/{parent-folder-id}/childFolders
Content-Type: application/json

{
  "displayName": "Q1 2024"
}

Critical Caveats & Common Mistakes

Throttling Behavior

The APIs consume Outlook resource quotas. If you hit throttling limits (HTTP 429), you'll receive a Retry-After header. Implement exponential backoff starting at 2 seconds, doubling up to a maximum of 60 seconds between retries.

// Pseudo-code: Retry with exponential backoff
let retryCount = 0;
const maxRetries = 5;
const baseDelay = 2000; // 2 seconds

while (retryCount < maxRetries) {
  try {
    const response = await exportMailbox(mailboxId);
    if (response.status === 429) {
      const retryAfter = response.headers['Retry-After'] || baseDelay * Math.pow(2, retryCount);
      await sleep(retryAfter);
      retryCount++;
      continue;
    }
    return response; // Success
  } catch (error) {
    throw error;
  }
}

Migration Path from EWS

If you currently use EWS for mailbox operations, here's a phased migration strategy:

Production Readiness Checklist

Before deploying to production, verify:

• ✓ Application registered in Microsoft Entra ID
• ✓ Graph permissions (Mail.ReadWrite, Mail.ReadWrite.Shared, Mailbox.Migration) granted by tenant admin
• ✓ Tested export on a primary mailbox in non-production
• ✓ Tested export on a shared mailbox in non-production
• ✓ Export stream preserved and re-imported successfully without modification
• ✓ Exponential backoff retry logic implemented for 429 responses
• ✓ Error handling for 403, 404, 429, and general export/import failures
• ✓ Throttling monitoring enabled (X-RateLimit-* headers logged)
• ✓ Audit logging configured for all export/import operations
• ✓ Backup/recovery strategy documented (export streams stored securely)
• ✓ Stakeholders informed of archive/public folder limitations

Key Takeaways

The mailbox import and export Microsoft Graph APIs are now production-ready for primary and shared mailbox operations. The APIs provide a modern, permission-scoped replacement for EWS with full-fidelity data preservation. However, treat the export stream as a black box—never parse, transform, or manipulate it. The unsupported mailbox types (archive, public folder, group) remain on the product roadmap; plan your migration strategy accordingly.

Start testing today in non-production. Begin with shared mailboxes (lower risk), validate that import restores data without loss, then phase in primary mailbox migrations. Monitor the Microsoft 365 developer blog for GA announcements on archive and public folder support.