Skaia Mail Agent

A Rust-based email monitoring and classification service that integrates with Matrix for notifications. Uses AI-powered email classification and scheduled digest delivery.

Overview

Skaia Mail Agent continuously monitors an IMAP inbox, classifies emails using an OpenAI-compatible API (Ollama, OpenAI, etc.), and sends notifications through Matrix. It supports immediate alerts for urgent emails and scheduled digests for less important messages.

Features

• AI-Powered Classification: Uses OpenAI-compatible APIs (Ollama, OpenAI, etc.) to classify emails as Urgent, Important, Low, or Noise
• Matrix Integration: Sends notifications to a specified Matrix room
• Immediate Alerts: Urgent emails are sent immediately to Matrix
• Scheduled Digests: Non-urgent emails are bundled into digests sent at scheduled times
• IMAP Monitoring: Polls email accounts via IMAP at configurable intervals
• SQLite Storage: Tracks seen emails and queues digest messages

Prerequisites

• Rust 1.75+ (edition 2024)
• SQLite
• Access to an OpenAI-compatible API (Ollama, OpenAI, etc.)
• Matrix account and room
• IMAP email account

Installation

From Source

git clone https://git.cozygalvinism.dev/cozyGalvinism/skaia-mail-agent.git
cd skaia-mail-agent
cargo build --release

Docker

docker build -t skaia-mail-agent .
docker run -v /path/to/data:/data skaia-mail-agent

Configuration

Configuration is loaded from config.toml (optional) and environment variables. Environment variables take precedence.

Required Environment Variables

# IMAP Configuration
IMAP_USER=your-email@example.com
IMAP_PASSWORD=your-app-password

# Matrix Configuration
MATRIX_HOMESERVER=https://matrix.example.com
MATRIX_USER=@yourbot:example.com
MATRIX_PASSWORD=your-matrix-password
MATRIX_ROOM_ID=!roomid:example.com

Optional Configuration

# IMAP Settings (defaults shown)
IMAP_HOST=imap.secureserver.net
IMAP_PORT=993
IMAP_POLL_SCHEDULE="0 */5 * * * * *"  # Every 5 minutes

# OpenAI/Ollama Settings (defaults shown)
OPENAI_URL=http://ollama:11434
OPENAI_MODEL=qwen3.5:27b
OPENAI_TOKEN=your-token  # Optional, for authenticated endpoints

# Digest Schedule (defaults shown)
DIGEST_SCHEDULE=["0 0 8 * * * *", "0 0 18 * * * *"]  # 8 AM and 6 PM

# Database Path (default shown)
DB_PATH=/data/email_agent.db

Note: OLLAMA_URL and OLLAMA_MODEL are accepted as aliases for backwards compatibility.

Example config.toml

imap_host = "imap.gmail.com"
imap_port = 993
imap_user = "your-email@gmail.com"
imap_password = "your-app-password"
imap_poll_schedule = "0 */10 * * * * *"  # Every 10 minutes

openai_url = "http://localhost:11434"
openai_model = "llama3:8b"
openai_token = ""  # Optional, for authenticated endpoints

matrix_homeserver = "https://matrix.org"
matrix_user = "@yourbot:matrix.org"
matrix_password = "your-matrix-password"
matrix_room_id = "!abcdefg:matrix.org"

digest_schedule = [
    "0 0 9 * * * *",  # 9 AM
    "0 0 17 * * * *"  # 5 PM
]

db_path = "/data/email_agent.db"

Note: ollama_url and ollama_model are accepted as aliases for backwards compatibility.

Usage

Initialize Database

skaia-mail-agent init-db --db-path /path/to/email_agent.db

Run the Agent

skaia-mail-agent run

The agent will:

1. Connect to Matrix and send a startup message
2. Begin polling emails according to the schedule
3. Classify new emails using the configured AI model
4. Send urgent emails immediately
5. Queue other emails for digest delivery
6. Send digests at scheduled times

Create Matrix User

skaia-mail-agent create-matrix-user \
  --homeserver https://matrix.org \
  --registration-token YOUR_TOKEN \
  your-bot-user your-bot-password

Accept Room Invite

skaia-mail-agent accept-room-invite

Test Matrix Connection

skaia-mail-agent test-matrix

Docker Usage

# Create data directory
mkdir -p ./data

# Run with environment variables
docker run -d \
  -v $(pwd)/data:/data \
  -e IMAP_USER=your-email@example.com \
  -e IMAP_PASSWORD=your-password \
  -e MATRIX_HOMESERVER=https://matrix.org \
  -e MATRIX_USER=@yourbot:matrix.org \
  -e MATRIX_PASSWORD=your-matrix-password \
  -e MATRIX_ROOM_ID=!roomid:matrix.org \
  skaia-mail-agent

Email Classification

The agent classifies emails into four categories:

• Urgent: Requires immediate attention (security alerts, direct messages from real people asking for something time-sensitive, critical system alerts)
• Important: Should be read soon but not immediately (invoices, account notices, messages from real people that aren't time-sensitive)
• Low: Useful but not pressing (shipping notifications, renewal reminders, newsletters you actually want)
• Noise: Marketing, promotional, automated bulk email that adds no value

Noise emails are ignored completely, urgent emails are sent immediately, and important/low emails are included in digests.

Development

Building

cargo build
cargo build --release

Running Tests

cargo test

Project Structure

• src/main.rs - Main application entry point and CLI
• src/config.rs - Configuration management
• src/db.rs - Database operations and schema
• src/imap_client.rs - IMAP email fetching
• src/classifier.rs - AI-powered email classification
• src/matrix.rs - Matrix bot integration

CI/CD

The project uses Forgejo Actions for CI. On version tags (v*), a Docker image is automatically built and pushed to git.cozygalvinism.dev.