Email Integration

BotServer provides email integration capabilities through IMAP/SMTP protocols, allowing bots to read, send, and manage emails.

Overview

Email integration in BotServer enables reading emails via IMAP, sending emails via SMTP, email account management, draft creation and management, folder organization, and email-based automation workflows.

Configuration

Environment Variables

Email configuration requires these environment variables:

# IMAP Settings
EMAIL_IMAP_SERVER=imap.gmail.com
EMAIL_IMAP_PORT=993
EMAIL_USERNAME=your-email@example.com
EMAIL_PASSWORD=your-app-password

# SMTP Settings
EMAIL_SMTP_SERVER=smtp.gmail.com
EMAIL_SMTP_PORT=587
EMAIL_FROM=your-email@example.com

Feature Flag

Email functionality requires the email feature flag during compilation:

cargo build --features email

Email Module Structure

The email module is located in src/email/ and contains mod.rs with the email service implementation, account management functionality, message handling logic, and IMAP/SMTP client implementations.

Database Schema

User Email Accounts

The user_email_accounts table stores email account configurations with encrypted password storage. Users can configure multiple accounts, each with its own IMAP and SMTP server details.

Email Drafts

The email_drafts table provides draft management including To, CC, and BCC addresses, subject and body content, attachment metadata, and auto-save support for work in progress.

Email Folders

The email_folders table handles folder organization with IMAP folder mapping, message counts, unread tracking, and hierarchical structure support for nested folders.

BASIC Keywords for Email

SEND MAIL

Send emails from BASIC scripts:

SEND MAIL "recipient@example.com", "Subject", "Email body content"

# With variables
let to = "user@example.com"
let subject = "Meeting Reminder"
let body = "Don't forget our meeting at 2 PM"
SEND MAIL to, subject, body

Email Automation

# Check for new emails
let new_emails = GET_EMAILS("INBOX", "UNSEEN")

# Process each email
FOR EACH email IN new_emails {
    let sender = email.from
    let subject = email.subject
    let body = email.body
    
    # Auto-reply logic
    if (subject CONTAINS "urgent") {
        SEND MAIL sender, "Re: " + subject, "I'll get back to you soon."
    }
}

Email Operations

Reading Emails

The system can connect to IMAP servers, fetch message headers, download full messages, search by various criteria, mark messages as read or unread, and move messages between folders.

Sending Emails

SMTP operations include authentication with the mail server, sending plain text and HTML emails, reply and forward functionality, and bulk sending with configurable limits. Attachment support is planned for a future release.

Security

Password Storage

Email passwords are encrypted using AES-GCM and never stored in plaintext. Passwords are decrypted only when needed for authentication and memory is cleared after use to prevent credential leakage.

Connection Security

All email connections require TLS/SSL encryption with proper certificate validation. Secure authentication methods are enforced, and plaintext transmission is never permitted.

Use Cases

Support Ticket System

# Monitor support inbox
let support_emails = GET_EMAILS("support", "UNSEEN")

FOR EACH email IN support_emails {
    # Create ticket
    let ticket_id = CREATE_TICKET(email.from, email.subject, email.body)
    
    # Send confirmation
    let response = "Ticket #" + ticket_id + " created. We'll respond within 24 hours."
    SEND MAIL email.from, "Ticket Created: " + email.subject, response
}

Newsletter Distribution

# Send newsletter to subscribers
let subscribers = GET "subscribers.csv"
let newsletter = GET "newsletter.html"

FOR EACH subscriber IN subscribers {
    SEND MAIL subscriber.email, "Monthly Newsletter", newsletter
    WAIT 1  # Rate limiting
}

Email-to-Task Conversion

# Convert emails to tasks
let task_emails = GET_EMAILS("tasks", "UNSEEN")

FOR EACH email IN task_emails {
    CREATE TASK email.subject, email.body, email.from
    MARK_AS_READ email
}

Integration with Other Features

With Calendar

Email integrates with the calendar system for meeting invitations, event reminders, and schedule updates sent via email notifications.

With Tasks

Task integration enables task creation from emails, status updates delivered via email, and deadline reminders sent to responsible parties.

With Knowledge Base

Knowledge base integration supports email archival for compliance, searchable email history, and providing email context for bot conversations.

Limitations

Current Limitations

The current implementation does not support attachment handling, provides only basic HTML email support, lacks email templates, has limited filtering options, and does not support OAuth2 authentication, requiring app-specific passwords instead.

Rate Limiting

Provider-specific rate limits apply to all email operations. Implement delays between sends to avoid throttling, monitor for rate limit errors, and use batch operations wisely to stay within provider limits.

Email Provider Setup

Gmail Configuration

To configure Gmail, first enable 2-factor authentication on your Google account. Then generate an app-specific password for BotServer to use. Enable IMAP access in Gmail settings. Use imap.gmail.com on port 993 for IMAP and smtp.gmail.com on port 587 for SMTP.

Outlook/Office 365

For Outlook or Office 365, enable IMAP in your account settings. If 2FA is enabled, generate an app password. Use outlook.office365.com on port 993 for IMAP and smtp.office365.com on port 587 for SMTP.

Custom Email Servers

For custom email servers, configure the appropriate server addresses, port numbers, security settings including TLS or SSL requirements, and the authentication method supported by your server.

Error Handling

Connection Errors

# Handle email errors
status = SEND MAIL recipient, subject, body
IF status = "sent" THEN
    TALK "Email sent successfully"
ELSE
    TALK "Failed to send email: " + status
    # Log error for admin
END IF

Common Issues

Common email issues include authentication failures from incorrect credentials, network timeouts when servers are slow to respond, server unavailable errors during outages, quota exceeded errors when hitting send limits, and invalid address errors for malformed recipients.

Best Practices

Use app-specific passwords rather than primary account passwords to limit security exposure. Respect provider rate limits by implementing appropriate delays between operations. Implement retry logic for transient failures to ensure delivery. Validate email addresses before sending to catch format errors early. Monitor usage by tracking sent and received counts. Encrypt sensitive data in storage and transit. Maintain an audit trail by logging all email operations.

Monitoring

Metrics to Track

Key metrics include emails sent and received, failed operations and their causes, connection failures, processing time for email operations, and queue size when batching sends.

Health Checks

Regular health checks should verify IMAP connectivity, SMTP availability, account validity and credential freshness, and folder synchronization status.

Summary

Email integration in BotServer enables powerful email-based automation and communication. Through IMAP/SMTP protocols and BASIC script integration, bots can manage email workflows, automate responses, and integrate email with other bot features for comprehensive communication automation.