7b0cf62019
- Add OAuthCredential model for storing Google/Microsoft OAuth tokens - Add email provider auto-detection endpoint (Gmail, Outlook, Yahoo, etc.) - Add EmailConfigWizard frontend component with step-by-step setup - Add OAuth flow endpoints for Google and Microsoft XOAUTH2 - Update production settings to make AWS, Sentry, Mailgun optional - Update Traefik config for wildcard subdomain routing - Add logo resize utility script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# 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
|