170 lines
4.3 KiB
Markdown
170 lines
4.3 KiB
Markdown
# 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:
|
|
```bash
|
|
git clone gitea@git.cloonar.com:Paraclub/ai-mailer.git
|
|
cd paraclub-ai-mailer
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
go mod download
|
|
```
|
|
|
|
3. Build the application:
|
|
```bash
|
|
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)
|
|
- `mailbox_in`: Mailbox to check for new emails (e.g., "INBOX")
|
|
- `draft_box`: Folder to save AI-generated drafts (e.g., "Drafts")
|
|
- `processed_box`: Folder to move processed emails to (they will also be marked as read)
|
|
- `use_tls`: Whether to use TLS for connection (recommended: true)
|
|
|
|
```yaml
|
|
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:
|
|
```bash
|
|
cp config.yaml.example config.yaml
|
|
# Edit config.yaml with your settings
|
|
```
|
|
|
|
2. Set required environment variables:
|
|
```bash
|
|
export IMAP_PASSWORD="your-email-password"
|
|
export OPENROUTER_API_KEY="your-openrouter-api-key"
|
|
```
|
|
|
|
3. Run the application:
|
|
```bash
|
|
./paraclub-ai-mailer
|
|
```
|
|
|
|
Or specify a custom config file path:
|
|
```bash
|
|
./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 read and moves it to the configured processed folder
|
|
|
|
## 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] |