# Email Configuration Wizard Plan

## Overview

Create a step-by-step wizard for configuring email settings with:
1. Auto-detection of IMAP/SMTP settings from email address
2. OAuth support for Gmail accounts
3. Manual configuration fallback

## Wizard Steps

### Step 1: Email Address Entry
- User enters their support email address (e.g., support@company.com)
- System extracts domain and attempts auto-detection
- Shows detected provider (Gmail, Outlook, Yahoo, custom domain)

### Step 2: Authentication Method Selection
- **For Gmail**: Show "Connect with Google" OAuth button
- **For Outlook/Microsoft 365**: Show "Connect with Microsoft" OAuth button
- **For others**: Show manual configuration option

### Step 3a: OAuth Flow (Gmail/Microsoft)
- Redirect to OAuth provider
- Request mail scopes (IMAP, SMTP access)
- Store OAuth tokens for authentication
- Auto-configure IMAP/SMTP settings

### Step 3b: Manual Configuration
- Pre-fill detected IMAP/SMTP settings
- Allow user to modify if needed
- Password/app-specific password entry

### Step 4: Test & Verify
- Test IMAP connection
- Test SMTP connection
- Show success or troubleshooting steps

### Step 5: Additional Settings
- From name configuration
- Check interval
- Delete after processing toggle

## Email Provider Database

Common providers with auto-detection:

| Domain | Provider | IMAP Host | IMAP Port | SMTP Host | SMTP Port | OAuth |
|--------|----------|-----------|-----------|-----------|-----------|-------|
| gmail.com | Gmail | imap.gmail.com | 993 | smtp.gmail.com | 587 | Yes |
| googlemail.com | Gmail | imap.gmail.com | 993 | smtp.gmail.com | 587 | Yes |
| outlook.com | Microsoft | outlook.office365.com | 993 | smtp.office365.com | 587 | Yes |
| hotmail.com | Microsoft | outlook.office365.com | 993 | smtp.office365.com | 587 | Yes |
| live.com | Microsoft | outlook.office365.com | 993 | smtp.office365.com | 587 | Yes |
| yahoo.com | Yahoo | imap.mail.yahoo.com | 993 | smtp.mail.yahoo.com | 587 | No |
| icloud.com | Apple | imap.mail.me.com | 993 | smtp.mail.me.com | 587 | No |
| aol.com | AOL | imap.aol.com | 993 | smtp.aol.com | 587 | No |

For custom domains: Use MX record lookup to detect if hosted by Gmail/Microsoft

## Backend Changes

### New API Endpoints

1. `POST /api/tickets/email-settings/detect/`
   - Input: `{ email: "support@company.com" }`
   - Output: Detected provider info and suggested settings

2. `POST /api/tickets/email-settings/oauth/google/`
   - Initiate Google OAuth flow for Gmail access

3. `POST /api/tickets/email-settings/oauth/google/callback/`
   - Handle OAuth callback, store tokens

4. `POST /api/tickets/email-settings/oauth/microsoft/`
   - Initiate Microsoft OAuth flow

5. `POST /api/tickets/email-settings/oauth/microsoft/callback/`
   - Handle Microsoft OAuth callback

### Model Changes

Add to TicketEmailSettings:
- `oauth_provider`: CharField (google, microsoft, null)
- `oauth_access_token`: TextField (encrypted)
- `oauth_refresh_token`: TextField (encrypted)
- `oauth_token_expiry`: DateTimeField
- `use_oauth`: BooleanField

### OAuth Scopes Required

**Google Gmail API:**
- `https://mail.google.com/` (full mail access for IMAP/SMTP)
- OR use Gmail API directly instead of IMAP

**Microsoft Graph API:**
- `https://outlook.office.com/IMAP.AccessAsUser.All`
- `https://outlook.office.com/SMTP.Send`

## Frontend Components

### EmailConfigWizard.tsx
Main wizard component with step navigation

### Steps:
1. EmailAddressStep - Email input with domain detection
2. AuthMethodStep - OAuth vs manual selection
3. OAuthConnectStep - OAuth flow handling
4. ManualConfigStep - IMAP/SMTP form fields
5. TestConnectionStep - Connection testing
6. FinalSettingsStep - Additional options

## Implementation Order

1. Backend: Email provider detection endpoint
2. Frontend: Wizard UI with steps
3. Backend: Google OAuth integration
4. Frontend: OAuth flow handling
5. Backend: Microsoft OAuth integration
6. Testing and refinement

## Questions to Resolve

1. Should we use IMAP/SMTP with OAuth tokens, or switch to Gmail/Graph API?
   - IMAP/SMTP with XOAUTH2 is simpler, works with existing code
   - API approach is more modern but requires rewriting email fetcher

2. Store OAuth tokens in TicketEmailSettings or separate model?
   - Same model is simpler
   - Separate model allows multiple OAuth connections

3. How to handle token refresh?
   - Background task to refresh before expiry
   - Refresh on-demand when making email requests