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:
  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
   • Marks the original email as processed

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]