Troubleshooting Guide

Common issues and solutions for the email system.

Domain Verification Issues

DNS Records Not Verifying

Symptoms:

• Domain status stuck on "Pending Verification"
• Verification fails repeatedly

Solutions:

1. Check DNS Propagation:

   • DNS changes can take up to 48 hours to propagate
   • Use DNS checker tools to verify records are live
   • Wait 24-48 hours after adding records

2. Verify Record Values:

   • Ensure DNS records match exactly (case-sensitive)
   • Check for trailing spaces or extra characters
   • Verify record type (TXT, MX, etc.)

3. Check DNS Provider:

   • Some providers have delays in DNS updates
   • Verify records are saved correctly in DNS panel
   • Try removing and re-adding records

4. Use Check Status:

   • Click "Check Status" to refresh without triggering verification
   • Click "Verify" to actively check verification

Domain Verification Failed

Symptoms:

• Domain status shows "Verification Failed"
• DNS records appear correct

Solutions:

1. Re-check DNS Records:

   • Verify all required records are present
   • Check record values are correct
   • Ensure records have propagated

2. Wait for Propagation:

   • DNS changes can take time
   • Wait 24-48 hours before re-verifying

3. Contact Support:

   • If records are correct and propagated, contact support
   • Provide domain name and DNS record screenshots

Email Delivery Issues

Emails Not Sending

Symptoms:

• Workflow executes but no email sent
• Email logs show "failed" status

Solutions:

1. Check SMTP Configuration:

   • Verify SMTP credentials are correct
   • Use Test Connection button in Settings to verify SMTP settings
   • Review enhanced error messages for specific guidance:
     • Authentication errors: Check username/password, use app passwords for Gmail/Outlook
     • Connection timeout: Verify host/port, check firewall settings
     • SSL/TLS errors: Toggle Secure setting, try different ports
   • Check SMTP server allows sending from your IP

2. Enhanced Error Messages:

   • When SMTP connection fails, you'll see detailed error messages with:
     • Specific Error: What went wrong (e.g., "SMTP authentication failed")
     • Actionable Steps: Step-by-step instructions to resolve
     • Documentation Links: Direct links to setup guides
   • Follow the resolution steps provided in the error message

3. Check Email Logs:

   • Review email_logs table for error messages
   • Check for rate limiting or authentication errors
   • Verify from email address is valid

4. Check SMTP Priority:

   • Verify correct SMTP config is being used
   • Check Emailit credentials if using custom domain
   • Verify default SMTP is configured if no tenant config

Emails Going to Spam

Symptoms:

• Emails sent but not received
• Emails in spam folder

Solutions:

1. SPF/DKIM Records:

   • Ensure SPF records are configured
   • Add DKIM records if available
   • Verify domain reputation

2. From Address:

   • Use verified domain for from address
   • Avoid generic addresses (noreply@)
   • Use recognizable sender name

3. Email Content:

   • Avoid spam trigger words
   • Include unsubscribe links
   • Use proper email formatting

Workflow Issues

Workflow Not Matching

Symptoms:

• Emails not processed by expected workflow
• General inquiry workflow matching instead

Solutions:

1. Check Workflow Status:

   • Verify workflow is Active
   • Check workflow priority
   • Ensure workflow goal matches email content

2. Check Priority:

   • Higher priority workflows checked first
   • General inquiry should have low priority (0)
   • Specific workflows should have higher priority (5-10)

3. Check Goal Matching:

   • Verify email contains keywords for goal type
   • Lead capture: pricing, quote, interested, budget
   • Helpdesk: support, help, issue, problem
   • General inquiry matches all emails

4. Test Matching:

   • Use Test Match feature in workflow editor or conversation details
   • Enter sample email subject/body to see which workflow would match
   • Review matching explanation and keywords that triggered match
   • Check competing workflows and why they didn't match
   • Adjust priority or goal type based on test results

Workflow Not Executing

Symptoms:

• Workflow matches but no response sent
• Steps not executing

Solutions:

1. Check Workflow Steps:

   • Verify steps are configured correctly
   • Check step conditions (if any)
   • Ensure "Send Response" step is present

2. Check Auto-Response:

   • Verify workflow has auto_respond enabled
   • Check "Send Response" step is configured
   • Verify response template or AI is working

3. Check Logs:

   • Review webhook_logs for errors
   • Check conversation logs for execution details
   • Look for error messages in logs

AI Response Not Generating

Symptoms:

• Template response used instead of AI
• Error messages about AI generation

Solutions:

1. Check API Keys:

   • Verify OpenAI API key is configured
   • Check API key is valid and has credits
   • Verify API key has correct permissions

2. Check Context:

   • Ensure workflow context is provided
   • Verify context library entries are active
   • Check context is not too long (may hit token limits)

3. Check AI Service:

   • Verify AI service is accessible
   • Check for rate limiting
   • Review API error messages in logs

IMAP Polling Issues

Emails Not Being Polled

Symptoms:

• Emails in mailbox but not processed
• No conversations created

Solutions:

1. Check IMAP Configuration:

   • Verify IMAP settings are correct
   • Test IMAP connection
   • Check IMAP is enabled

2. Check Polling Status:

   • Verify IMAP worker is running
   • Check polling interval
   • Review worker logs for errors

3. Check Email Forwarding:

   • Verify emails are forwarded to webhook
   • Check webhook endpoint is accessible
   • Review webhook logs for errors

IMAP Connection Errors

Symptoms:

• IMAP connection fails
• Polling stops working

Solutions:

1. Check Credentials:

   • Verify username and password are correct
   • Check for special characters in password
   • Use Test IMAP Connection button to verify settings
   • Review enhanced error messages for specific guidance:
     • Authentication errors: Verify username/password, use app passwords
     • Connection timeout: Check host/port settings
   • Try re-entering credentials

2. Enhanced Error Messages:

   • When IMAP connection fails, you'll see detailed error messages with:
     • Specific Error: What went wrong
     • Actionable Steps: Step-by-step instructions to resolve
     • Documentation Links: Direct links to setup guides
   • Follow the resolution steps provided in the error message

3. Check Server Settings:

   • Verify IMAP host and port are correct
   • Check if SSL/TLS is required
   • Test connection from email client

4. Check Firewall:

   • Ensure IMAP port is not blocked
   • Check for IP restrictions
   • Verify network connectivity

Cross-Channel Context Issues

Context Not Appearing

Symptoms:

• Previous conversations not referenced
• AI doesn't mention past interactions

Solutions:

1. Check Contact Matching:

   • Verify email/phone matches across channels
   • Check contact_data is extracted correctly
   • Ensure conversations are linked properly

2. Check Context Generation:

   • Verify AI API keys are configured
   • Check context generation is not failing
   • Review logs for context generation errors

3. Check Time Window:

   • Context only includes last 90 days
   • Older conversations not included
   • Check conversation dates

Performance Issues

Slow Email Processing

Symptoms:

• Emails take long time to process
• Delayed responses

Solutions:

1. Check Workflow Complexity:

   • Simplify workflow steps
   • Reduce context size
   • Optimize step conditions

2. Check AI Response Time:

   • AI generation can take 5-10 seconds
   • Consider using templates for faster responses
   • Check AI service status

3. Check Database Performance:

   • Review database query performance
   • Check for slow queries
   • Optimize database indexes

Agent-Related Issues

No Agent Assigned to Email

Symptoms:

• Email processed but no response sent
• Error message: "No agent available to process email"

Solutions:

1. Check Default Email Agent:

   • Navigate to Assistants page
   • Ensure at least one agent is marked as "Default for Email"
   • Or ensure a general default assistant exists

2. Check Workflow Agent Assignment:

   • If using workflows, verify workflow has an agent assigned
   • Or ensure routing rules are configured

3. Verify Agent Configuration:

   • Ensure agents have valid system prompts
   • Check agents are active and not deleted

Agent Responses Not Natural

Symptoms:

• Responses sound too template-like
• Responses don't adapt to email content

Solutions:

1. Review System Prompt:

   • Ensure system prompt encourages natural, conversational responses
   • Avoid overly prescriptive instructions
   • Include examples of desired tone

2. Check Workflow Context:

   • Workflow context should be guidance, not a template
   • Avoid using template variables in context
   • Let agent adapt context naturally

3. Review Response Template:

   • Templates are guidance, not literal templates
   • Agent should adapt template tone/structure
   • Don't expect exact template variable substitution

Emails Not Being Sent (Queued)

Symptoms:

• Responses generated but not received
• Emails stuck in queue

Solutions:

1. Check Email Queue Worker:

   • Verify email queue worker is running
   • Check worker logs for errors
   • Restart worker if needed: npm run worker in api directory

2. Check Queue Status:

   • Review email_queue table for pending emails
   • Check scheduled_at times (should be 5-15 minutes from creation)
   • Verify status is 'pending' not 'failed'

3. Check SMTP Configuration:

   • Verify SMTP settings are correct
   • Test SMTP connection
   • Check for rate limiting or blocking

Agent Handoffs Not Working

Symptoms:

• Routing rules not triggering handoffs
• Emails not transferred to correct agent

Solutions:

1. Verify Routing Rules:

   • Check routing rules include 'email' in channels
   • Verify trigger keywords match email content
   • Check rule priority and active status

2. Check Agent Availability:

   • Ensure target agent exists and is active
   • Verify agent belongs to same tenant
   • Check agent has valid configuration

3. Review Handoff History:

   • Check conversation metadata for handoff history
   • Verify handoff messages are being sent
   • Review handoff reasons in conversation details

Signature Issues

Symptoms:

• Signatures missing from emails
• Duplicate signatures
• Incorrect agent name

Solutions:

1. Check Agent Configuration:

   • Verify agent name is set correctly
   • Check email_signature field if using custom signature
   • Ensure agent is assigned to conversation

2. Review Signature Generation:

   • Signatures are automatically appended
   • Don't include signature in system prompt
   • Custom signature is optional

Delayed Responses Not Working

Symptoms:

• Emails sent immediately instead of delayed
• No delay between receiving and sending

Solutions:

1. Check Queue Worker:

   • Verify email queue worker is running
   • Check worker is processing queue
   • Review worker logs for errors

2. Check Queue Configuration:

   • Verify emails are being queued (check email_queue table)
   • Check scheduled_at times are in future
   • Ensure status is 'pending'

3. Verify Delay Calculation:

   • Delays are random between 5-15 minutes
   • Check scheduled_at is 5-15 minutes after created_at
   • Review queue service logs

Getting Additional Help

If issues persist:

1. Check Logs:

   • Review webhook_logs table
   • Check application logs
   • Look for error messages
   • Review email_queue table for queued emails

2. Review Documentation:

   • AI Agents Guide - Agent configuration and usage
   • Workflows Guide - Workflow setup and configuration
   • Overview - System architecture
   • API Reference - Technical details

3. Contact Support:

   • Provide error messages
   • Include relevant logs
   • Describe steps to reproduce
   • Include agent and workflow configurations