smoothschedule/frontend/PLAN_EMAIL_WIZARD.md

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