Search for answers or browse our knowledge base.
Microsoft EWS Retirement – Migrating Epicor ECM and IDC Email Imports to Microsoft Graph API
Overview
Microsoft is retiring Exchange Web Services (EWS) in Exchange Online. Organizations using Microsoft 365 / Exchange Online mailboxes with Epicor ECM or Epicor IDC email imports will need to migrate applicable mailbox connections from EWS to Microsoft Graph API.
Microsoft has announced that EWS will begin being disabled globally in Exchange Online in October 2026, with EWS fully disabled in April 2027.
This change may affect Microsoft 365 email imports configured in any of the following locations:
- Epicor ECM Client Service
- Epicor IDC Client Service
- Epicor IDC Web UI email batch import configuration
Throughout this article, these components may collectively be referred to as Epicor Client Services or Epicor email imports.
IMPORTANT – Existing EWS Mailbox Configurations
When migrating an existing Epicor email import from EWS to Microsoft Graph API, do not simply change the existing EWS configuration from EWS to Graph API.
The mailbox/email import configuration should be recreated using Graph API as the connection type. Epicor has identified that required Graph-specific configuration options may not appear or populate correctly when an existing EWS configuration is simply changed to Graph API.
This is an important step when migrating an existing EWS email import.
The migration consists of two primary parts:
- Microsoft 365 / Microsoft Entra configuration – Completed by the customer’s Microsoft 365 administrator or IT provider.
- Epicor email import configuration – Recreate the applicable ECM and/or IDC mailbox import using Microsoft Graph API and the information provided by the Microsoft administrator.
Why Is This Change Required?
Microsoft is retiring EWS in Exchange Online and recommends that applications accessing Exchange Online data migrate to Microsoft Graph.
According to Microsoft’s current retirement timeline:
- October 2026 – Microsoft begins globally disabling EWS for Exchange Online organizations.
- April 2027 – EWS is fully disabled in Exchange Online.
Customers should prepare their Microsoft 365 environment and migrate applicable Epicor email imports to Microsoft Graph before EWS becomes unavailable.
Microsoft EWS Retirement Documentation
Microsoft Learn – Deprecation of Exchange Web Services in Exchange Online
Microsoft Learn – Migrate Exchange Web Services (EWS) apps to Microsoft Graph
What Is Microsoft Graph?
Microsoft Graph is Microsoft’s API platform for accessing Microsoft 365 services and data, including Exchange Online mailboxes.
For Epicor email imports, Microsoft Graph replaces the EWS connection previously used to access Microsoft 365 mailboxes.
Existing EWS Connection:
Epicor Email Import → EWS → Microsoft 365 Mailbox
Microsoft Graph Connection:
Epicor Email Import → Microsoft Graph → Microsoft 365 Mailbox
Microsoft Graph allows Epicor ECM and IDC to continue accessing designated Microsoft 365 mailboxes for email and document attachment imports after EWS is retired.
Microsoft Learn – Microsoft Graph Overview
Part 1 – Microsoft 365 / Microsoft Entra Preparation
Before an Epicor email import can use Microsoft Graph API, the customer’s Microsoft 365 environment must be configured to allow the Epicor application to authenticate and access the required mailbox.
This configuration must be completed by the customer’s Microsoft 365 / Microsoft Entra administrator or IT provider.
Support Boundary
Mosaic Support does not configure or administer the customer’s Microsoft 365 / Microsoft Entra tenant. The customer’s Microsoft administrator or IT provider should complete the Microsoft-side configuration using Microsoft’s documentation linked throughout this article.
1. Microsoft Entra Application Registration
According to Epicor’s Graph API requirements, a valid Microsoft Entra ID application registration must exist for the Epicor integration to authenticate with Microsoft 365.
The customer’s Microsoft administrator should verify the application configuration and provide the information required by the Epicor Graph connection, including:
- Application (Client) ID
- Directory (Tenant) ID
- Valid application credential / Client Secret, where applicable
- Access to the Microsoft 365 mailbox being monitored
If a Client Secret is being used, it must be valid and must not be expired.
Microsoft Learn – Register an application with the Microsoft identity platform
2. Microsoft Graph API Permissions
The Microsoft Entra application must have the Microsoft Graph permissions required for the Epicor email import.
Epicor identifies commonly required permissions as:
- Mail.Read – Allows the application to read mail.
- Mail.ReadWrite – May be required when the Epicor process needs to move, modify, or delete processed emails.
- User.Read – May be required depending on the authentication and Epicor configuration.
Epicor indicates these permissions are typically configured as Application Permissions and require Microsoft administrator consent.
The exact permissions and access model should be reviewed by the customer’s Microsoft administrator based on the Epicor configuration and the organization’s Microsoft 365 security requirements.
Microsoft Learn – Microsoft Graph Permissions Reference
Microsoft Learn – Configure an application to access a web API
3. Grant Microsoft Administrator Consent
Required Microsoft Graph permissions may require administrator consent before the Epicor application can access the mailbox.
Epicor identifies the general location within Microsoft Entra as:
Microsoft Entra ID → App Registrations → Selected Application → API Permissions → Grant Admin Consent
The customer’s Microsoft 365 administrator should verify that the required permissions have been granted the appropriate administrator consent.
Without the required permissions and consent, the Graph API mailbox connection may fail even when the Tenant ID, Client ID, and other connection information are correct.
Microsoft Learn – Configure an application to access a web API
4. Verify Mailbox Access
The application must be permitted to access the Microsoft 365 mailbox used by the Epicor email import.
For example, an organization may use a dedicated mailbox such as:
The customer’s Microsoft administrator should ensure that the application is permitted to access the required mailbox and determine whether mailbox-level access restrictions should be implemented based on the organization’s security policies.
Microsoft provides additional information regarding application access to Exchange Online here:
Microsoft Learn – Role Based Access Control for Applications in Exchange Online
Part 2 – Identify Your Epicor Email Imports
Once the Microsoft-side configuration has been completed, review the Microsoft 365 email imports configured throughout the Epicor environment.
Email imports may be configured in one or more of the following locations.
Epicor ECM Client Service
Epicor ECM may use the ECM Client Service to monitor a Microsoft mailbox and import emails, attachments, or documents into ECM.
Any Microsoft 365 email imports currently configured to use EWS will need to be migrated to Microsoft Graph API.
Epicor IDC Client Service
Epicor IDC may use the IDC Client Service to monitor a Microsoft mailbox and create email batch imports for Intelligent Data Capture.
Any Microsoft 365 email imports currently configured to use EWS will need to be migrated to Microsoft Graph API.
Epicor IDC Web UI
Some IDC environments configure email batch imports through the IDC Web UI rather than through the locally installed IDC Client Service.
These configurations must also be reviewed for EWS-based Microsoft mailbox connections.
Customers Using Both ECM and IDC
Many customers use both Epicor ECM and Epicor IDC. Review both applications for Microsoft email imports.
Updating an ECM mailbox connection does not automatically update an IDC email batch import, or vice versa.
Part 3 – Recreate the Epicor Email Import Using Microsoft Graph API
IMPORTANT – Recreate the Mailbox Configuration
Do not simply edit an existing EWS mailbox/email import and change the connection type from EWS to Graph API.
Epicor has identified that a configuration converted from EWS may not automatically expose or populate all settings required by Graph API.
Recreate the mailbox/email import using Graph API as the connection type from the beginning.
Once the customer’s Microsoft administrator has completed the Microsoft-side requirements, recreate each applicable Epicor email import using the Microsoft Graph API connection type.
Depending on your environment, this may need to be completed within:
- Epicor ECM Client Service
- Epicor IDC Client Service
- Epicor IDC Web UI email batch import configuration
Graph API Configuration Information
The exact fields displayed may vary depending on the Epicor product, version, and configuration.
Epicor identifies the following as common Graph API configuration values:
- Tenant ID
- Client ID
- Client Secret
- Mailbox address being monitored
- Folder name – such as Inbox or a custom mail folder
- Authentication type expected by the Epicor configuration
Not every field will necessarily appear in every Epicor version or configuration.
The Tenant ID, Client ID, credentials, permissions, and mailbox access must correspond to the Microsoft Entra application prepared by the customer’s Microsoft administrator.
Microsoft Mailbox Authorization
When recreating the email import using Microsoft Graph API, you may be required to sign in to Microsoft and authorize the mailbox connection again.
Complete the Microsoft authentication/authorization process if prompted.
An existing EWS connection being authorized and functional does not mean the newly created Microsoft Graph connection is automatically authorized.
Part 4 – Test the New Graph API Email Import
After creating the new Microsoft Graph API email import, test the connection before considering the migration complete.
For each recreated Graph API email import:
- Confirm that the Graph API configuration can successfully connect to the Microsoft 365 mailbox.
- Send a test email to the monitored mailbox.
- Include a supported document attachment, such as a PDF.
- Confirm that Epicor detects the email.
- Confirm that the attachment is successfully retrieved.
- Confirm that the document enters the expected ECM or IDC process.
- Confirm that the document completes the expected batch, capture, or workflow processing.
- If the configuration moves, modifies, or deletes processed emails, verify that behavior as well.
Customers with multiple Microsoft email imports should test each Graph API connection individually.
Troubleshooting Graph API Email Imports
If a newly created Graph API email import does not process mail, first verify both the Microsoft configuration and the Epicor configuration.
Verify the Microsoft Configuration
Have your Microsoft 365 administrator verify:
- The Microsoft Entra application registration exists.
- The correct Tenant ID is being used.
- The correct Client ID is being used.
- The Client Secret or other credential is valid and has not expired.
- The required Microsoft Graph permissions are configured.
- Administrator consent has been granted where required.
- The application has access to the mailbox being monitored.
Verify the Epicor Configuration
Verify:
- The email import was created/recreated as a Graph API connection rather than simply changing an existing EWS connection.
- The correct mailbox address is configured.
- The correct mailbox folder is configured.
- The Tenant ID and Client ID match the Microsoft Entra application.
- The required authentication information has been entered.
- The Microsoft authorization/sign-in process has been completed if required.
Review Logs
If the Microsoft and Epicor configurations appear correct but the import still fails, review the available Epicor and Windows logs.
Depending on the product and environment, this may include:
- Batch Processing / Client Service logs
- ECM application logs
- IDC application or batch logs
- Windows Event Viewer for applicable on-premises components
Common Microsoft Graph authentication or authorization errors may indicate:
- Invalid or expired Client Secret
- Incorrect Tenant ID
- Incorrect Client ID
- Insufficient Microsoft Graph permissions
- Administrator consent has not been granted
- Application does not have access to the requested mailbox
- Microsoft authentication/authorization has not been completed
Information to Provide to Mosaic Support
If the Microsoft configuration has been reviewed by your Microsoft 365 administrator and the Graph API email import still does not process successfully, please provide Mosaic Support with the following:
- A screenshot of the applicable Graph API email import configuration.
- Confirmation that a Microsoft Entra application registration has been created.
- The Microsoft Graph permissions configured for the application.
- Confirmation that the required Admin Consent has been granted.
- Any error messages appearing in the Epicor Batch Processing, Client Service, ECM, or IDC logs.
- Whether the email import is configured through the ECM Client Service, IDC Client Service, or IDC Web UI.
- Confirmation that the mailbox/email import was recreated using Graph API rather than converting the existing EWS configuration.
Security Notice
Please remove or obscure Client Secrets, passwords, access tokens, certificates, or other sensitive authentication information from screenshots.
Do not send Client Secrets, passwords, access tokens, certificates, or other sensitive credentials through an unsecured support ticket or email.
Recommended Migration Process
For each Microsoft 365 email import used by Epicor ECM and/or IDC:
- Identify the Microsoft 365 email imports used by Epicor ECM and IDC.
- Identify which connections currently use EWS.
- Provide this article and the linked Microsoft documentation to your Microsoft 365 administrator or IT provider.
- Have your Microsoft administrator create or validate the Microsoft Entra application registration.
- Have your Microsoft administrator configure the required Microsoft Graph permissions and administrator consent.
- Have your Microsoft administrator verify application access to the required Microsoft 365 mailbox.
- Recreate the applicable Epicor email import using Graph API as the connection type. Do not simply change the existing EWS connection to Graph API.
- Enter the Graph configuration information provided by your Microsoft administrator.
- Sign in and authorize the Microsoft mailbox again if required.
- Test the new Graph API email import using an email containing a supported attachment.
- Verify the complete ECM/IDC processing path, including any expected email post-processing.
- Repeat the process for every applicable email import in ECM and IDC.
Microsoft Documentation
The following Microsoft documentation should be used by your Microsoft 365 administrator when preparing your environment.
EWS Retirement
Microsoft Learn – Deprecation of Exchange Web Services in Exchange Online
Migrating from EWS to Microsoft Graph
Microsoft Learn – Migrate Exchange Web Services (EWS) apps to Microsoft Graph
Microsoft Graph Overview
Microsoft Learn – Microsoft Graph Overview
Register an Application
Microsoft Learn – Register an application with the Microsoft identity platform
Configure API Permissions
Microsoft Learn – Configure an application to access a web API
Microsoft Graph Permissions
Microsoft Learn – Microsoft Graph Permissions Reference
Application-Only Authentication
Microsoft Learn – Get access without a user
Restricting Application Access to Exchange Online Mailboxes
Microsoft Learn – Role Based Access Control for Applications in Exchange Online
Important Notes
This Microsoft EWS retirement applies to Exchange Online / Microsoft 365. Microsoft states that the retirement does not apply to EWS in on-premises Exchange Server.
This article covers both sides of the migration process: the Microsoft 365 prerequisites required for Microsoft Graph and the applicable Epicor ECM/IDC email import configuration.
Mosaic Support does not configure or administer the customer’s Microsoft 365 / Microsoft Entra tenant. Microsoft-side configuration, including application registration, Microsoft Graph permissions, administrator consent, credentials, and mailbox access, should be completed by the customer’s Microsoft 365 administrator or IT provider using Microsoft’s documentation.
Once the required Microsoft-side configuration has been completed, the applicable Epicor email imports must be recreated using Microsoft Graph API instead of EWS.
Do not simply change the connection type on an existing EWS mailbox configuration to Graph API. Required Graph-specific options may not appear or populate correctly. Create/recreate the mailbox email import using Graph API as the connection type.
Depending on the customer’s environment, affected email imports may exist in the Epicor ECM Client Service, Epicor IDC Client Service, IDC Web UI, or a combination of these locations.
When recreating an email import using Microsoft Graph API, the Microsoft mailbox may need to be signed into and authorized again. Complete the Microsoft authentication/authorization process if prompted.
After creating the Graph API connection, test the email import from end to end to confirm that Epicor can access the mailbox, retrieve email attachments, and successfully process the documents through the expected ECM or IDC process.
Customers with multiple Microsoft 365 email imports should review, recreate, authorize, and test each applicable connection individually before EWS is retired.