gmail-to-exchange365/README.md

Complete Gmail to Exchange 365 migration tool with UI - Migrate emails, attachments, and folders seamlessly

# 📧 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)

```bash
npx gmail-to-exchange365
```

This will:
- Automatically create a `.env` template file
- Guide you through setup
- Start the migration server

### Option 2: Install Globally

```bash
npm install -g gmail-to-exchange365
gmail-to-exchange365
```

### Option 3: Install Locally

```bash
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](SETUP.md) for details)
   - Go to [Google Cloud Console](https://console.cloud.google.com/)
   - Enable Gmail API
   - Create OAuth 2.0 credentials
   - Add redirect URI: `http://localhost:3000/google/callback`

2. **Get Microsoft OAuth Credentials** (see [SETUP.md](SETUP.md) for details)
   - Go to [Azure Portal](https://portal.azure.com/)
   - 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:

```env
# 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](https://console.cloud.google.com/)
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](https://portal.azure.com/)
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:

```bash
npx gmail-to-exchange365
```

Or if installed globally:

```bash
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

```bash
# In one terminal, start the server
npm start

# In another terminal, start Electron
npm run electron
```

Or use the combined command:

```bash
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

```bash
npm run dev
```

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

### Building

```bash
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! 🚀**