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

9. All Interest and Berth APIs Authentication Fixed

• Problem: APIs were only accepting one auth header, causing failures for unauthenticated users
• Solution: Updated ALL APIs to accept both headers ("094ut234" and "pjnvü1230"):
  • create-interest.ts - Create new interests
  • update-interest.ts - Update existing interests
  • delete-interest.ts - Delete interests
  • get-interests.ts - List all interests
  • get-interest-by-id.ts - Get single interest
  • get-berths.ts - Get all berths
  • get-interest-berths.ts - Get berths linked to interest
  • link-berths-to-interest.ts - Link berths to interest
  • unlink-berths-from-interest.ts - Unlink berths from interest
  • link-berth-recommendations-to-interest.ts - Link berth recommendations
  • unlink-berth-recommendations-from-interest.ts - Unlink berth recommendations
  • Added comprehensive logging to all APIs for better debugging

10. EOI Status Dropdown Updated

• Problem: Missing "Waiting for Signatures" status option
• Solution:
  • Added "Waiting for Signatures" as option 2 in EOI Status
  • New order: "Awaiting Further Details" → "Waiting for Signatures" → "Signed"

11. 404 Errors for Newly Created Records

• Problem: Newly created records sometimes show 404 when immediately updating/linking
• Solution:
  • Added retry mechanism with exponential backoff to updateInterest function
  • Will retry up to 3 times with increasing delays (1s, 2s, 3s)
  • get-interest-berths returns empty list instead of throwing error for new records
  • This handles NocoDB synchronization delays where records need time to propagate
  • After 3 retries, provides detailed error message explaining possible causes

Required Environment Variables

Make sure these are set in your .env file:

# 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