port-nimara-client-portal/docs/email-system-fixes.md

# Email System Fixes

## Issues Addressed

### 1. Email Credentials Not Found Errors
- **Problem**: The system was trying to fetch emails even when no credentials were present
- **Solution**: 
  - Added session ID check in `EmailThreadView` before attempting to fetch emails
  - Modified `fetch-thread` API to return empty results instead of throwing errors when credentials are missing
  - Added proper session cleanup in `EmailCommunication` component

### 2. 502 Gateway Timeout Errors
- **Problem**: Email fetching was causing timeouts, especially when editing/saving interest cards
- **Solution**:
  - Reduced email fetch limit from 50 to 20 emails
  - Added 15-second timeout for IMAP connections
  - Prevented unnecessary email fetches when no session exists

### 3. EOI Generation Issues
- **Problem**: EOI generation was failing due to missing Address field and configuration issues
- **Solution**:
  - Made Address field optional with default value "Not Provided"
  - Added environment variable validation for `NUXT_DOCUMENSO_API_KEY` and `NUXT_DOCUMENSO_BASE_URL`
  - Improved error messages to indicate when configuration is missing or fields need to be filled
  - Required fields are now: Full Name, Email Address, Yacht Name, Length, Width, Depth

### 4. Interest Save Failures
- **Problem**: Interest updates were failing with authentication errors
- **Solution**:
  - Updated `update-interest.ts` API to accept both x-tag headers ("094ut234" and "pjnvü1230")
  - Now both authenticated and unauthenticated users can save interest updates

### 5. Email Signature Formatting
- **Problem**: Logo was appearing below the signature details
- **Solution**:
  - Moved Port Nimara logo to the top of the signature
  - Logo now appears above the name with proper spacing

### 6. Email Refresh Not Showing New Emails
- **Problem**: New emails from clients weren't appearing after refresh
- **Solution**:
  - Enhanced IMAP search to include CC and BCC fields
  - Now searches in multiple folders: INBOX, Sent, Sent Items, Sent Mail
  - Better email detection for comprehensive thread retrieval

### 7. EOI Document Generation Issues
- **Problem**: EOI documents were created but stuck in draft status with non-working links
- **Solution**:
  - Fixed response structure to match actual Documenso API response
  - Added proper document send step to move from draft to active
  - Changed `sendEmail` to `true` to ensure recipients receive signing emails
  - Correctly extract signing URLs from the response

### 8. 502 Bad Gateway on Container Restart
- **Problem**: Getting 502 errors when refreshing after container restart
- **Solution**:
  - Added better session validation in `fetch-thread` API
  - Added try-catch for decryption failures (session invalid after restart)
  - Client-side now detects 502 errors and clears invalid sessions
  - No error toast shown - just resets to empty email state

## Required Environment Variables

Make sure these are set in your `.env` file:

```env
# Email Configuration
NUXT_EMAIL_ENCRYPTION_KEY=your-32-character-encryption-key
NUXT_EMAIL_IMAP_HOST=mail.portnimara.com
NUXT_EMAIL_IMAP_PORT=993
NUXT_EMAIL_SMTP_HOST=mail.portnimara.com
NUXT_EMAIL_SMTP_PORT=587
NUXT_EMAIL_LOGO_URL=https://portnimara.com/logo.png

# Documenso Configuration (REQUIRED for EOI generation)
NUXT_DOCUMENSO_API_KEY=your-actual-api-key
NUXT_DOCUMENSO_BASE_URL=https://signatures.portnimara.dev
```

## How It Works Now

1. **Email Session Management**:
   - Sessions are stored in browser's sessionStorage
   - If no session exists, email features are gracefully disabled
   - Users can connect/disconnect at any time

2. **Email Fetching**:
   - Only attempts to fetch when valid session exists
   - Limited to 20 emails to prevent timeouts
   - Falls back to cached emails from MinIO if IMAP fails
   - 15-second timeout prevents hanging connections

3. **EOI Generation**:
   - Validates all required fields before attempting generation
   - Checks for Documenso configuration
   - Returns clear error messages if configuration is missing
   - Inserts client's signing link directly into email body

## Troubleshooting

If you're still experiencing issues:

1. **Check Docker logs**: `docker logs <container-name>`
2. **Verify environment variables are set correctly**
3. **Ensure Documenso API credentials are valid**
4. **Try disconnecting and reconnecting email credentials**
Fix email system error handling and remove hardcoded credentials - Handle missing email sessions gracefully without throwing errors - Clear partial session data when no valid session exists - Return empty results instead of 401 errors for missing credentials - Remove hardcoded Documenso API key and require env variables - Reduce email fetch limit from 50 to 20 for performance - Add documentation for email system fixes 2025-06-09 22:50:06 +02:00			`# Email System Fixes`

			`## Issues Addressed`

			`### 1. Email Credentials Not Found Errors`
			`- Problem: The system was trying to fetch emails even when no credentials were present`
			`- Solution:`
			- Added session ID check in `EmailThreadView` before attempting to fetch emails
			- Modified `fetch-thread` API to return empty results instead of throwing errors when credentials are missing
			- Added proper session cleanup in `EmailCommunication` component

			`### 2. 502 Gateway Timeout Errors`
			`- Problem: Email fetching was causing timeouts, especially when editing/saving interest cards`
			`- Solution:`
			`- Reduced email fetch limit from 50 to 20 emails`
			`- Added 15-second timeout for IMAP connections`
			`- Prevented unnecessary email fetches when no session exists`

			`### 3. EOI Generation Issues`
Fix EOI generation and interest update authentication - Make Address field optional in EOI document generation with "Not Provided" default - Accept both x-tag headers ("094ut234" and "pjnvü1230") for interest updates - Update required fields validation to exclude Address - Improve error messages to guide users on updating missing fields 2025-06-09 22:56:10 +02:00			`- Problem: EOI generation was failing due to missing Address field and configuration issues`
Fix email system error handling and remove hardcoded credentials - Handle missing email sessions gracefully without throwing errors - Clear partial session data when no valid session exists - Return empty results instead of 401 errors for missing credentials - Remove hardcoded Documenso API key and require env variables - Reduce email fetch limit from 50 to 20 for performance - Add documentation for email system fixes 2025-06-09 22:50:06 +02:00			`- Solution:`
Fix EOI generation and interest update authentication - Make Address field optional in EOI document generation with "Not Provided" default - Accept both x-tag headers ("094ut234" and "pjnvü1230") for interest updates - Update required fields validation to exclude Address - Improve error messages to guide users on updating missing fields 2025-06-09 22:56:10 +02:00			`- Made Address field optional with default value "Not Provided"`
Fix email system error handling and remove hardcoded credentials - Handle missing email sessions gracefully without throwing errors - Clear partial session data when no valid session exists - Return empty results instead of 401 errors for missing credentials - Remove hardcoded Documenso API key and require env variables - Reduce email fetch limit from 50 to 20 for performance - Add documentation for email system fixes 2025-06-09 22:50:06 +02:00			- Added environment variable validation for `NUXT_DOCUMENSO_API_KEY` and `NUXT_DOCUMENSO_BASE_URL`
Fix EOI generation and interest update authentication - Make Address field optional in EOI document generation with "Not Provided" default - Accept both x-tag headers ("094ut234" and "pjnvü1230") for interest updates - Update required fields validation to exclude Address - Improve error messages to guide users on updating missing fields 2025-06-09 22:56:10 +02:00			`- Improved error messages to indicate when configuration is missing or fields need to be filled`
			`- Required fields are now: Full Name, Email Address, Yacht Name, Length, Width, Depth`

			`### 4. Interest Save Failures`
			`- Problem: Interest updates were failing with authentication errors`
			`- Solution:`
			- Updated `update-interest.ts` API to accept both x-tag headers ("094ut234" and "pjnvü1230")
			`- Now both authenticated and unauthenticated users can save interest updates`
Fix email system error handling and remove hardcoded credentials - Handle missing email sessions gracefully without throwing errors - Clear partial session data when no valid session exists - Return empty results instead of 401 errors for missing credentials - Remove hardcoded Documenso API key and require env variables - Reduce email fetch limit from 50 to 20 for performance - Add documentation for email system fixes 2025-06-09 22:50:06 +02:00
Fix email signature layout and enhance email thread fetching - Move logo to top of email signature for better formatting - Enhance IMAP search to include CC/BCC fields and multiple folders - Fix EOI document generation to properly send and extract signing URLs - Update documentation with all email system fixes 2025-06-09 23:09:32 +02:00			`### 5. Email Signature Formatting`
			`- Problem: Logo was appearing below the signature details`
			`- Solution:`
			`- Moved Port Nimara logo to the top of the signature`
			`- Logo now appears above the name with proper spacing`

			`### 6. Email Refresh Not Showing New Emails`
			`- Problem: New emails from clients weren't appearing after refresh`
			`- Solution:`
			`- Enhanced IMAP search to include CC and BCC fields`
			`- Now searches in multiple folders: INBOX, Sent, Sent Items, Sent Mail`
			`- Better email detection for comprehensive thread retrieval`

			`### 7. EOI Document Generation Issues`
			`- Problem: EOI documents were created but stuck in draft status with non-working links`
			`- Solution:`
			`- Fixed response structure to match actual Documenso API response`
			`- Added proper document send step to move from draft to active`
			- Changed `sendEmail` to `true` to ensure recipients receive signing emails
			`- Correctly extract signing URLs from the response`

Fix 502 errors on container restart and expand API authentication - Handle 502 Gateway Timeout errors by clearing invalid sessions - Add graceful session validation failure handling in fetch-thread API - Expand x-tag authentication to accept additional valid token - Add debug logging to berth-related API endpoints - Document the 502 error fix in email system documentation 2025-06-09 23:29:24 +02:00			`### 8. 502 Bad Gateway on Container Restart`
			`- Problem: Getting 502 errors when refreshing after container restart`
			`- Solution:`
			- Added better session validation in `fetch-thread` API
			`- Added try-catch for decryption failures (session invalid after restart)`
			`- Client-side now detects 502 errors and clears invalid sessions`
			`- No error toast shown - just resets to empty email state`

Fix email system error handling and remove hardcoded credentials - Handle missing email sessions gracefully without throwing errors - Clear partial session data when no valid session exists - Return empty results instead of 401 errors for missing credentials - Remove hardcoded Documenso API key and require env variables - Reduce email fetch limit from 50 to 20 for performance - Add documentation for email system fixes 2025-06-09 22:50:06 +02:00			`## Required Environment Variables`

			Make sure these are set in your `.env` file:

			```env
			`# Email Configuration`
			`NUXT_EMAIL_ENCRYPTION_KEY=your-32-character-encryption-key`
			`NUXT_EMAIL_IMAP_HOST=mail.portnimara.com`
			`NUXT_EMAIL_IMAP_PORT=993`
			`NUXT_EMAIL_SMTP_HOST=mail.portnimara.com`
			`NUXT_EMAIL_SMTP_PORT=587`
			`NUXT_EMAIL_LOGO_URL=https://portnimara.com/logo.png`

			`# Documenso Configuration (REQUIRED for EOI generation)`
			`NUXT_DOCUMENSO_API_KEY=your-actual-api-key`
			`NUXT_DOCUMENSO_BASE_URL=https://signatures.portnimara.dev`
			```

			`## How It Works Now`

			`1. Email Session Management:`
			`- Sessions are stored in browser's sessionStorage`
			`- If no session exists, email features are gracefully disabled`
			`- Users can connect/disconnect at any time`

			`2. Email Fetching:`
			`- Only attempts to fetch when valid session exists`
			`- Limited to 20 emails to prevent timeouts`
			`- Falls back to cached emails from MinIO if IMAP fails`
			`- 15-second timeout prevents hanging connections`

			`3. EOI Generation:`
			`- Validates all required fields before attempting generation`
			`- Checks for Documenso configuration`
			`- Returns clear error messages if configuration is missing`
			`- Inserts client's signing link directly into email body`

			`## Troubleshooting`

			`If you're still experiencing issues:`

			1. Check Docker logs: `docker logs <container-name>`
			`2. Verify environment variables are set correctly`
			`3. Ensure Documenso API credentials are valid`
			`4. Try disconnecting and reconnecting email credentials`