inboxer/README.md

inBOXER

AI-powered email classification and organization tool. Connects to your IMAP mailbox, classifies incoming emails via DeepSeek AI, and moves them into organised folders automatically.

One-Line Install

curl -sSL https://git.lohmar.co.uk/cclohmar/inboxer/raw/branch/main/install.sh | sudo bash

This will:

• Download the binary, config, and prompt file from the repository
• Create the inboxer system user
• Install everything under /opt/inboxer/
• Create and start a systemd service

After install, edit the configuration to set your credentials:

sudo nano /opt/inboxer/bin/config.yaml

Required settings:

• ai.api_key -- your DeepSeek API key
• smtp.host, smtp.port, smtp.username, smtp.password -- SMTP credentials for sending OTP login emails
• server.session_secret -- change from the default

Then start the service:

sudo systemctl start inboxer

Manual Install

Prerequisites

• Go 1.21+ (for building from source)
• A DeepSeek API key (platform.deepseek.com)
• SMTP credentials for sending OTP emails

Build from Source

git clone https://git.lohmar.co.uk/cclohmar/inboxer.git
cd inboxer
make build

The binary is written to bin/inboxer. Copy the entire bin/ directory to your target machine or deploy via install.sh.

Run Directly

cp .env.example .env
# edit .env with your credentials

make run

The web interface will be available at http://localhost:8080.

Deploy Manually to /opt/inboxer

sudo mkdir -p /opt/inboxer/{bin,data,logs}
sudo cp bin/inboxer     /opt/inboxer/bin/
sudo cp bin/config.yaml /opt/inboxer/bin/
sudo cp bin/prompt.txt  /opt/inboxer/bin/

Edit /opt/inboxer/bin/config.yaml to set credentials and adjust paths:

• database.path: /opt/inboxer/data/db.sqlite
• logging.file: /opt/inboxer/logs/inboxer.log

Create the systemd service at /etc/systemd/system/inboxer.service:

[Unit]
Description=inBOXER - AI-Powered Email Classifier
After=network-online.target

[Service]
Type=simple
User=inboxer
Group=inboxer
WorkingDirectory=/opt/inboxer
ExecStart=/opt/inboxer/bin/inboxer
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable inboxer
sudo systemctl start inboxer

Configuration

All configuration lives in a single file: bin/config.yaml.

Section	Key	Description
server	port	Web interface port (default: 8080)
server	host	Bind address (default: 0.0.0.0)
server	session_secret	Session encryption key -- change in production
database	path	SQLite database file path
smtp	host	SMTP server hostname
smtp	port	SMTP server port (typically 587 for STARTTLS)
smtp	username	SMTP login username
smtp	password	SMTP login password
ai	api_key	DeepSeek API key
ai	model	DeepSeek model (default: deepseek-chat)
ai	prompt_file	Path to classification prompt template
folders	*	IMAP folder names for classified emails

Service Management

sudo systemctl status  inboxer    # check status
sudo systemctl restart inboxer    # restart after config change
sudo systemctl stop    inboxer    # stop the service
sudo journalctl -u     inboxer -f # follow the logs

Features

• Email + OTP Authentication: Login with just your email address
• AI-Powered Classification: DeepSeek LLM sorts email into 7 categories
• 7 Classification Folders: Important, eCommerce, Notifications, Finance, Social, Other, Spam
• Mobile-First Web Interface: Responsive design for all devices
• Test Mode: Preview AI decisions without moving emails
• Empty-Inbox Guarantee: Every email is processed unconditionally

Architecture

src/
  cmd/         - Entry point (main.go)
  pkg/config/  - Configuration loader
  internal/
    auth/      - OTP authentication & SMTP sender
    imap/      - IMAP client (fetch, move, create folders)
    ai/        - DeepSeek API client & classifier
    db/        - SQLite database (GORM)
    web/       - HTTP handlers & templates
    worker/    - Background email processing
  web/
    templates/ - Go HTML templates (mobile-first)
bin/           - Pre-built binary & configuration files

See PROJECT_PLAN.md for detailed architecture and development phases.

License

See docs/LICENSE.md for license information.