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 may fail due to missing Documenso configuration
• Solution:
  • Added environment variable validation for NUXT_DOCUMENSO_API_KEY and NUXT_DOCUMENSO_BASE_URL
  • Improved error messages to indicate when configuration is missing

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