ParaClub AI Mailer

An automated email response system that uses OpenRouter AI API to generate context-aware replies to incoming emails. The system fetches emails via IMAP, gathers context from configured URLs, and generates AI-powered responses that are saved as email drafts.

Features

• Automatic email fetching via IMAP
• Context gathering from configured URLs
• AI-powered response generation using OpenRouter API
• Draft email creation in IMAP folders
• Configurable polling intervals
• TLS support for secure email communication
• Comprehensive logging system
• Graceful shutdown handling

Prerequisites

• Go 1.19 or later
• IMAP email account credentials
• OpenRouter API key
• Access to the websites you want to use as context sources

Installation

1. Clone the repository:

git clone gitea@git.cloonar.com:Paraclub/ai-mailer.git
cd paraclub-ai-mailer

2. Install dependencies:

go mod download

3. Build the application:

go build -o paraclub-ai-mailer ./cmd/paraclub-ai-mailer

Configuration

The application uses a YAML configuration file (config.yaml) with the following structure:

IMAP Settings

• server: IMAP server hostname (e.g., "imap.gmail.com")
• port: IMAP port (typically 993 for TLS)
• username: Your email address
• password: Email password (use ${IMAP_PASSWORD} to load from environment or file:///path/to/password.txt to read from file)
• mailbox_in: Mailbox to check for new emails (e.g., "INBOX")
• draft_box: Folder to save AI-generated drafts (e.g., "Drafts")
• use_tls: Whether to use TLS for connection (recommended: true)

AI Settings

• openrouter_api_key: Your OpenRouter API key (use ${OPENROUTER_API_KEY} to load from environment or file:///path/to/key.txt to read from file)
• model: The AI model to use (e.g., "anthropic/claude-2")
• temperature: Response randomness (0.0-1.0)
• max_tokens: Maximum response length

imap:
  server: "imap.example.com"
  port: 993
  username: "your-email@example.com"
  password: "${IMAP_PASSWORD}"  # From environment variable
  mailbox_in: "INBOX"
  draft_box: "Drafts"
  use_tls: true

ai:
  openrouter_api_key: "${OPENROUTER_API_KEY}"  # From environment variable
  model: "anthropic/claude-2"
  temperature: 0.7
  max_tokens: 2000

context:
  urls:
    - "https://example.com/faq"
    - "https://example.com/about"
    - "https://example.com/policies"

polling:
  interval: "5m"  # Duration format (e.g., 30s, 5m, 1h)

logging:
  level: "info"  # debug, info, warn, error
  file_path: "paraclub-ai-mailer.log"

Environment Variables

The following environment variables need to be set:

• IMAP_PASSWORD: Your IMAP account password
• OPENROUTER_API_KEY: Your OpenRouter API key

Usage

1. Set up your configuration file:

cp config.yaml.example config.yaml
# Edit config.yaml with your settings

2. Set required environment variables:

export IMAP_PASSWORD="your-email-password"
export OPENROUTER_API_KEY="your-openrouter-api-key"

3. Run the application:

./paraclub-ai-mailer

Or specify a custom config file path:

./paraclub-ai-mailer -config /path/to/config.yaml

How It Works

1. The application polls the IMAP server at configured intervals
2. For each unprocessed email:
   • Fetches the email content
   • Retrieves HTML content from configured URLs
   • Sends combined content to OpenRouter AI for response generation
   • Saves the AI-generated response as a draft email
   • The original email is marked as read (\Seen) before the AI is called, so it is never answered twice. Mails that fail during generation stay marked as read and are not retried.

Logging

Logs are written to both stdout and the configured log file. Log levels can be set to:

• debug: Detailed debugging information
• info: General operational information
• warn: Warning messages
• error: Error conditions

Security Considerations

• Use TLS for IMAP connections (set use_tls: true)
• Store sensitive credentials in environment variables
• Regularly rotate API keys and passwords
• Monitor log files for unusual activity

Error Handling

The application implements:

• Automatic retries for transient failures
• Graceful shutdown on system signals
• Comprehensive error logging
• Email processing state tracking to prevent duplicates

Limitations

• Processes emails sequentially
• HTML content is fetched without following links
• Requires stable internet connection
• API rate limits may apply (OpenRouter)

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

[Your chosen license]

Support

[Your support information]