Skip to content

Migrating from IMAP/SMTP to Graph API

This guide walks you through migrating an existing email account from IMAP/SMTP backend to Microsoft Graph API backend. The Graph API backend provides better performance, reliability, and feature support compared to IMAP/SMTP, making it the recommended backend for Microsoft 365 accounts.

Outlook/Microsoft 365 Only

This migration guide applies only to Outlook/Microsoft 365 accounts. Graph API cannot be used with Gmail or other email providers. Those providers must continue using IMAP/SMTP.

Prerequisites

This migration requires coordination between two parties:

IT Department / System Administrator (for Entra Admin Center):

  • Access to Entra Admin Center to manage OAuth app permissions.

Lime CRM Expert Services (for Lime Admin):

  • Access to Lime Admin to configure OAuth apps and email accounts.

Optional for Testing:

  • A test account set up in Entra and configured in Lime Admin to verify that Graph API works correctly in your environment before migrating production accounts. When testing, follow the same steps below using the test account's email address in step 3, and skip step 4 to keep your production account active.

Migration Steps

1. Update OAuth App Permissions in Entra

Navigate to your existing OAuth app in Entra Admin Center and verify the following Microsoft Graph API permissions are present:

Required Delegated Permissions:

  • User.Read (added by default).
  • User.ReadBasic.All.
  • Mail.ReadWrite.
  • Mail.ReadWrite.Shared.
  • Mail.Send.
  • Mail.Send.Shared.
  • offline_access.

Permission Management

  • Do not remove any other existing permissions that may be in use.
  • You can remove old IMAP/SMTP-specific permissions later, after verifying the migration is successful.

2. Create New OAuth App in Lime Admin

In Lime Admin → Settings → Email Integration → OAuth2 Applications:

  1. Click Create new OAuth app.
  2. As Display name, the suggested approach is to use the same name as you used for the IMAP & SMTP app but add (Graph API) to the name in order to distinguish it from the IMAP OAuth app.
  3. For the fields Redirect URI, Application (client) ID and Directory (tenant) ID, copy the values from existing IMAP & SMTP app configuration.
  4. Generate a new OAuth Client Secret in Entra Admin Center (see Client secret instructions) and paste it in Client secret.
  5. Set Base scope to API.
  6. Save the OAuth app.

3. Create New API-Based Account

In Lime Admin → Settings → Email Integration → Email Accounts:

  1. Click Add shared account → OAuth.
  2. Uncheck the box Enable email processing (to prevent it from processing emails immediately).
  3. Use the same email address as your existing IMAP account.
  4. For Authentication provider, select the new API-scoped OAuth app created in step 2.
  5. Before saving, copy all configuration settings from the IMAP account: Groups with send access, Language, Timezone, Automatic reply message, Email signature, Aliases, etc.
  6. Click Continue and log in when prompted to verify the account.

4. Switch Accounts

  1. Deactivate the IMAP account.
  2. Activate the API account.
  3. The account will immediately start processing emails.
  4. Navigate to Email Integration → Conversation parent limetypes → Monitored email accounts and change configuration to the Account you created in step 3.

5. Verify Migration

Test the following functionality:

  • Incoming emails: Send a test email to the account and verify it's imported to Lime CRM correctly.
  • Outgoing emails: Send a test email from Lime CRM.
  • Attachments: Send and receive emails with attachments and verify they can be downloaded by the recipient.
  • Conversations: Send replies to existing emails and verify that messages in the same thread are grouped into the same conversation in Lime CRM.
  • Auto-replies: Test automatic reply functionality (if enabled).

6. Complete or Rollback Migration

If everything works correctly:

  1. Delete the old IMAP account from Lime Admin.
  2. Delete the old IMAP OAuth app from Lime Admin.
  3. Optional: Remove IMAP-specific permissions from the OAuth app in Entra Admin Center (if no longer needed).
  4. Optional: Remove IMAP-specific settings from the shared mailbox in Microsoft 365 (if no longer needed).
  5. Optional: Remove IMAP and SMTP protocol access for the user account that Lime CRM uses to authenticate to the mailbox in Microsoft 365 (if no longer needed).

If you encounter problems:

  1. Deactivate the API account.
  2. Activate the IMAP account.
  3. Revert configuration: If you updated the configuration in step 4, roll back to the previous configuration version using the Version Handling Drop-down.
  4. Investigate the issues (check the Troubleshooting section below, review logs, or contact support).

Troubleshooting

Authentication Fails

  • Verify all required permissions are added to the OAuth app in Entra Admin Center.
  • Check that the OAuth Client ID is correct and/or recreate an OAuth Client Secret.

Shared Mailbox Issues