Email Configuration Guide

Complete guide to configuring domains, SMTP settings, and email options.

Domain Configuration

Adding a Domain

1. Navigate to Email Settings page
2. Enter domain name (without www or http://)
3. Click Add Domain
4. System will generate DNS records for verification

DNS Records

After adding a domain, you'll receive DNS records to add:

TXT Records: Used for domain verification

• Name: Usually @ or domain name
• Value: Verification string provided by system
• TTL: 3600 (or your DNS provider's default)

MX Records (if required): For email routing

• Priority: As specified in DNS records
• Value: Mail server hostname

Adding DNS Records:

1. Log into your domain registrar or DNS provider
2. Navigate to DNS management
3. Add each record with exact values provided
4. Save changes
5. Wait for propagation (can take up to 48 hours)

Domain Verification

Check Status:

• Click Check Status to refresh verification status without triggering verification
• Status updates automatically when DNS records propagate

Trigger Verification:

• Click Verify to actively check if DNS records are correctly configured
• System will update status: pending → verified or failed

Verification Status:

• Pending: DNS records not yet verified
• Verified: Domain verified and ready to use
• Failed: DNS records incorrect or not propagated

SMTP Credentials

Once domain is verified:

1. Click Create SMTP Credentials button
2. System generates username and password
3. Credentials are automatically encrypted and stored
4. Credentials are used automatically for sending emails

Credential Security:

• Passwords are encrypted in database
• Credentials are never displayed in full
• Only active credentials are used

SMTP Configuration

SMTP Priority System

The system uses a three-tier priority for SMTP configuration:

1. Emailit Credentials (Highest Priority)

   • Used if domain is verified via Emailit
   • Automatically configured after credential creation
   • Uses verified domain for from address

2. Tenant Custom SMTP (Medium Priority)

   • Configured in System → Settings → Email
   • Supports any SMTP server
   • Password is encrypted before storage

3. Default Platform SMTP (Fallback)

   • Configured via environment variables
   • Used if no tenant-specific config exists
   • Includes tenant branding in from address

Custom SMTP Setup

System → Settings → Email:

1. Enter From Email Address (e.g., your-email@gmail.com)
   • The system can auto-detect SMTP settings from your email domain
   • Click Detect Settings to automatically fill SMTP/IMAP configuration
   • Supported providers: Gmail, Outlook/Office365, Yahoo, iCloud, Zoho, and more
2. If auto-detection doesn't work, manually enter:
   • SMTP Host (e.g., smtp.gmail.com)
   • Port:
     • 587 for STARTTLS (recommended)
     • 465 for SSL
     • 25 for unencrypted (not recommended)
   • Username (usually your email address)
   • Password (use app password for Gmail/Outlook)
3. Click Test Connection to verify settings
4. Review any error messages for specific guidance
5. Click Save once test passes

Smart SMTP Defaults:

The system automatically detects email provider settings when you enter a "From Email" address:

• Gmail: Auto-fills smtp.gmail.com:587 and imap.gmail.com:993
• Outlook/Office365: Auto-fills smtp.office365.com:587 and outlook.office365.com:993
• Yahoo: Auto-fills smtp.mail.yahoo.com:587 and imap.mail.yahoo.com:993
• iCloud: Auto-fills smtp.mail.me.com:587 and imap.mail.me.com:993
• Zoho: Auto-fills smtp.zoho.com:587 and imap.zoho.com:993

Click Detect Settings next to the From Email field to auto-fill configuration, or let the system detect automatically as you type.

Validation & Testing:

• The system validates all SMTP fields before saving
• Required fields are highlighted with error messages if invalid
• Use Test Connection button to verify SMTP settings before saving
• Test results show success or enhanced error messages with:
  • Specific error descriptions
  • Actionable resolution steps
  • Links to setup guides
  • Step-by-step troubleshooting
• Invalid configurations are prevented from being saved

Enhanced Error Messages:

If SMTP connection fails, you'll see detailed error messages with:

• Specific Error: What went wrong (e.g., "Authentication failed")
• Actionable Guidance: What to do (e.g., "Verify your SMTP password")
• Resolution Steps: Step-by-step instructions to fix the issue
• Documentation Links: Direct links to relevant setup guides

Common SMTP Providers:

• Gmail: smtp.gmail.com:587 (requires app password)
• Outlook: smtp.office365.com:587 (or smtp-mail.outlook.com:587)
• Yahoo: smtp.mail.yahoo.com:587
• SendGrid: smtp.sendgrid.net:587
• Mailgun: smtp.mailgun.org:587

Email Context Library

The context library provides reusable business information across all workflows.

Adding Context

1. Navigate to Email Workflows page
2. Click Context Library button
3. Enter context key (e.g., company_info)
4. Enter context value (e.g., business description)
5. Click Add

Using Context

Context entries are automatically included in all workflow executions. They're merged with workflow-specific context and provided to the AI.

Best Practices:

• Use descriptive keys (e.g., pricing_tiers, service_areas)
• Keep values concise but informative
• Update context when business information changes

IMAP Configuration (Advanced)

For receiving emails via IMAP instead of webhooks:

1. Navigate to System → Settings → Email
2. Scroll to Custom IMAP Mailbox section
3. Enable Use custom IMAP mailbox toggle
4. Enter:
   • IMAP host (e.g., imap.gmail.com)
   • Port (usually 993 for SSL, 143 for STARTTLS)
   • Username (usually your full email address)
   • Password (use app password for Gmail)
   • Mailbox (usually INBOX)
5. Click Test IMAP Connection to verify settings
6. Click Save SMTP Configuration to save

Validation & Testing:

• All IMAP fields are validated before saving
• Required fields show error messages if invalid
• Test IMAP Connection button verifies credentials and connectivity
• Test must pass before configuration can be saved
• Last polled timestamp shows when mailbox was last checked

IMAP Polling:

• System polls mailbox every 60 seconds (configurable)
• Emails are automatically forwarded to workflow system
• Supports both admin mailbox and per-tenant mailboxes
• Connection status is displayed in the UI

Next Steps

• Workflows Guide - Configure email processing workflows
• Troubleshooting - Resolve configuration issues