📧 Gmail → Exchange 365 Migrator

A complete, production-ready application for migrating emails, attachments, and folders from Gmail to Microsoft Exchange 365 (Office 365).

✨ Features

• ✅ Full Email Migration: Migrates emails with all metadata (from, to, cc, bcc, subject, date)
• ✅ Attachment Support: Preserves all email attachments
• ✅ Folder/Label Mapping: Automatically maps Gmail labels to Exchange folders
• ✅ OAuth Authentication: Secure OAuth 2.0 login for both Google and Microsoft
• ✅ Progress Tracking: Real-time progress bar and detailed logs
• ✅ Batch Processing: Configurable batch sizes to handle large migrations
• ✅ Rate Limiting: Built-in delays to respect API rate limits
• ✅ Error Handling: Automatic retry with exponential backoff
• ✅ Pause/Resume: Control migration flow with pause and resume
• ✅ Modern UI: Beautiful, responsive web interface
• ✅ Electron Support: Optional desktop app wrapper
• ✅ TypeScript: Fully typed codebase for maintainability

🚀 Quick Start

Option 1: Run with npx (Easiest - No Installation)

npx gmail-to-exchange365

This will:

• Automatically create a .env template file
• Guide you through setup
• Start the migration server

Option 2: Install Globally

npm install -g gmail-to-exchange365
gmail-to-exchange365

Option 3: Install Locally

npm install gmail-to-exchange365
npx gmail-to-exchange365

Prerequisites

• Node.js 20+ installed
• Google Cloud Project with Gmail API enabled
• Microsoft Azure App Registration with Mail API permissions

First-Time Setup

When you run the tool for the first time, it will create a .env file template. You need to:

1. Get Google OAuth Credentials (see SETUP.md for details)

   • Go to Google Cloud Console
   • Enable Gmail API
   • Create OAuth 2.0 credentials
   • Add redirect URI: http://localhost:3000/google/callback

2. Get Microsoft OAuth Credentials (see SETUP.md for details)

   • Go to Azure Portal
   • Create App Registration
   • Add API permissions: Mail.Read, Mail.ReadWrite, MailboxSettings.ReadWrite
   • Add redirect URI: http://localhost:3000/ms/callback

3. Edit the .env file with your credentials:

# Google OAuth Credentials
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here
GOOGLE_REDIRECT=http://localhost:3000/google/callback

# Microsoft OAuth Credentials
MS_CLIENT_ID=your_ms_client_id_here
MS_CLIENT_SECRET=your_ms_client_secret_here
MS_TENANT_ID=common
MS_REDIRECT=http://localhost:3000/ms/callback

# Session Configuration
SESSION_SECRET=your_random_session_secret_here

# Server Configuration
PORT=3000

Setting up OAuth Credentials

Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API
4. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
5. Set application type to Web application
6. Add authorized redirect URI: http://localhost:3000/google/callback
7. Copy the Client ID and Client Secret to your .env file

Microsoft OAuth Setup

1. Go to Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Click New registration
4. Set redirect URI: http://localhost:3000/ms/callback
5. Go to API permissions → Add:
   • Mail.Read
   • Mail.ReadWrite
   • MailboxSettings.ReadWrite
   • offline_access
6. Go to Certificates & secrets → Create a new client secret
7. Copy the Application (client) ID and Client secret to your .env file

🎯 Usage

Simple Usage

Just run:

npx gmail-to-exchange365

Or if installed globally:

gmail-to-exchange365

The tool will:

1. ✅ Check/create .env file automatically
2. ✅ Validate your OAuth credentials
3. ✅ Start the web server
4. ✅ Open http://localhost:3000 in your browser

Web Interface

1. The server starts automatically when you run the command above

2. Open your browser

Navigate to http://localhost:3000 (or the URL shown in the terminal)

3. Connect accounts

   • Click Connect Google and authorize the app
   • Click Connect Microsoft and authorize the app

4. Configure migration

   • Set batch size (default: 10 emails per batch)
   • Set delay between batches (default: 1000ms)

5. Start migration

   • Click Start Migration
   • Monitor progress in real-time
   • Use Pause, Resume, or Stop as needed

Electron Desktop App

# In one terminal, start the server
npm start

# In another terminal, start Electron
npm run electron

Or use the combined command:

npm run electron:dev

📁 Project Structure

gmail-to-exchange365/
├── src/
│   ├── index.ts                 # Application entry point
│   ├── server/
│   │   ├── app.ts              # Express app configuration
│   │   ├── routes.ts            # API routes
│   │   ├── types.ts            # TypeScript type definitions
│   │   ├── googleAuth.ts       # Google OAuth handling
│   │   ├── msAuth.ts           # Microsoft OAuth handling
│   │   ├── gmailFetcher.ts     # Gmail API integration
│   │   ├── exchangePusher.ts   # Exchange API integration
│   │   ├── folderMapper.ts     # Folder/label mapping
│   │   └── migrator.ts         # Migration coordinator
│   └── ui/
│       ├── index.html          # Main UI
│       ├── app.js              # Frontend JavaScript
│       └── styles.css          # Styling
├── electron/
│   └── main.js                 # Electron main process
├── package.json
├── tsconfig.json
└── README.md

🔧 Configuration Options

Migration Options

You can configure migration behavior via the UI or by modifying the API call:

• batchSize: Number of emails to process per batch (default: 10)
• delayBetweenBatches: Delay in milliseconds between batches (default: 1000)
• retryAttempts: Number of retry attempts for failed emails (default: 3)
• retryDelay: Delay in milliseconds before retry (default: 5000)

🛠️ Development

Development Mode

npm run dev

This runs the server with auto-reload on file changes.

Building

npm run build

Compiles TypeScript to JavaScript in the dist/ directory.

📝 API Endpoints

• GET / - Main UI
• GET /google/auth - Initiate Google OAuth
• GET /google/callback - Google OAuth callback
• GET /ms/auth - Initiate Microsoft OAuth
• GET /ms/callback - Microsoft OAuth callback
• GET /api/status - Check authentication status
• POST /api/migrate - Start migration (returns Server-Sent Events)
• POST /api/migrate/pause - Pause migration
• POST /api/migrate/resume - Resume migration
• POST /api/migrate/stop - Stop migration
• POST /api/logout - Clear session

⚠️ Important Notes

1. Rate Limits: Both Gmail and Microsoft Graph APIs have rate limits. The app includes built-in delays, but for very large migrations, you may need to increase delays.

2. Large Migrations: For accounts with thousands of emails, the migration may take several hours. The app supports pause/resume functionality.

3. Session Storage: Sessions are stored in the sessions/ directory. Make sure this directory is writable.

4. Security: In production, use HTTPS and secure session storage. Never commit your .env file.

5. Permissions: Ensure your OAuth apps have the correct scopes:

   • Google: gmail.readonly, gmail.labels
   • Microsoft: Mail.Read, Mail.ReadWrite, MailboxSettings.ReadWrite

🐛 Troubleshooting

"Missing required environment variables"

Make sure your .env file exists and contains all required variables. See .env.example for reference.

"OAuth error" or "Authentication failed"

• Verify your OAuth credentials are correct
• Check that redirect URIs match exactly (including http:// vs https://)
• Ensure APIs are enabled in your cloud consoles

"Rate limit exceeded"

• Increase the delayBetweenBatches value
• Reduce the batchSize
• Wait and retry later

Migration stops or fails

• Check the logs in the UI
• Verify both accounts are still connected
• Check network connectivity
• Review API quotas in Google Cloud Console and Azure Portal

📄 License

MIT License - feel free to use this project for your email migrations.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For issues, questions, or feature requests, please open an issue on the repository.

Happy Migrating! 🚀