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 Existing Records During Updates - FIXED

• Problem: Records that exist in the database return 404 when trying to update them
• Root Cause: Webhook objects were being sent in the request body
• Solution: Now filtering out all object fields, only sending primitives

What we've fixed:

• Now skipping all object fields (including webhook fields) during updates
• Only sending primitive values (strings, numbers, nulls) to the API
• Removed webhook fields from the allowed fields list
• Added retry mechanism with exponential backoff
• Including Id field in request body to identify the record

Confirmed Working Format:

// URL: /api/v2/tables/mbs9hjauug4eseo/records (no ID in URL)
// Body: { Id: 459, "Full Name": "...", "Extra Comments": "..." }

Test Results:

• ✅ PATCH with single object: { Id: 459, ... } - WORKS
• ✅ PATCH with array: [{ Id: 459, ... }] - WORKS
• ❌ PATCH with ID in URL: /records/459 - 404 ERROR
• ❌ PATCH with where parameter - 404 ERROR

IMPORTANT: Server Restart Required The code is now correct, but you need to:

1. Restart your Docker container or development server
2. Verify the API token in your .env file matches the working one
3. Try updating a record again

The 404 errors should be resolved once the server is running with the latest code that filters out webhook objects.

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

12. EOI Management System

• Added EOI Section Component: New component to manage EOI document generation and signature links
• Features Implemented:
  • Generate EOI button that creates documents via Documenso API
  • Checks for existing EOI before generating new one (prevents duplicates)
  • Displays all 3 signature links (Client, CC, Developer) with copy-to-clipboard functionality
  • Shows EOI status badge (Awaiting Further Details, Waiting for Signatures, Signed)
  • Regenerate option for non-signed documents
• Auto-Updates on EOI Generation:
  • EOI Status → "Waiting for Signatures"
  • Sales Process Level → "LOI and NDA Sent"
  • EOI Time Sent → Current timestamp
  • Extra Comments → Appends "EOI Sent [timestamp]"
• Database Storage: Links stored in new columns:
  • Signature Link Client
  • Signature Link CC
  • Signature Link Developer

13. Auto-Save Functionality

• Implemented: Interest details now auto-save after 2 seconds of inactivity
• Features:
  • Debounced save to prevent excessive API calls
  • Silent save without success notifications
  • Automatically triggers parent refresh to keep data in sync
  • Cancels pending saves on component unmount

14. IMAP BCC Search Fix

• Problem: IMAP search was failing with "Cannot read properties of null"
• Cause: BCC search criteria not supported by all IMAP servers
• Solution: Removed BCC from search criteria, now only searches FROM, TO, and CC fields

15. MinIO Private Bucket Authentication Fix

• Problem: Email caching failed when MinIO buckets were set to private
• Cause: Frontend was trying to fetch presigned URLs which failed with CORS/auth issues
• Solution:
  • Now reading cached emails directly on server using MinIO client
  • No presigned URLs needed - server has full authentication
  • Works perfectly with private buckets

16. Email Fetching & Caching Improvements

• Optimizations:
  • Date-based IMAP search (last 30 days) to reduce email count
  • Increased timeout from 15s to 30s
  • Now caching ALL emails (both sent and received)
  • Fire-and-forget caching to avoid slowing down email fetch
  • Proper IMAP date format (e.g., "1-Jan-2024")

17. Date Display Fix

• Problem: EOI dates showing wrong format/timezone
• Solution:
  • Enhanced date parsing to handle ISO dates, DD-MM-YYYY, and YYYY-MM-DD
  • Now displays in DD/MM/YYYY HH:mm format
  • Properly handles timezones

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