email-scanner

Small script to delete emails matching certain from-addrs, or having keywords in subject line. Now with AI-powered classification to identify important emails and forward them while automatically filtering out spam and newsletters!

Why?

I have a shit-ton of personally-hosted emails, and emails on platforms without spam prevention tools, and I'm too lazy to setup a pre-recieve type of spam daemon, so I did this instead.

Features

• Legacy filtering: Delete emails based on subject keywords and sender addresses
• AI-powered classification: Uses OpenAI or Ollama to identify important emails (financial notices, plane tickets, etc.) vs spam/newsletters
• Cost-effective AI: Support for local Ollama models to avoid OpenAI API costs
• Smart forwarding: Automatically forwards important emails to a configured address via SMTP
• Auto-learning: Automatically adds spam senders to the blocklist for future filtering
• GitHub Actions: Runs automatically on a schedule to keep your inbox clean

I want to use it

Not sure why, but ok!

• Clone the repo
• Copy accounts_sample.toml, config_sample.toml, rules_sample.toml, and fwd_sample.toml to accounts.toml, config.toml, rules.toml, and fwd.toml and edit them
• Test mode: Run with --test flag to see what the AI thinks about each email without actually deleting or forwarding anything
• Configure AI classification in config.toml:
  • Option 1 (Local/Free): Enable Ollama by setting [ollama] enabled = true and configuring the base URL and model
  • Option 2 (Cloud): Add your OpenAI API key to use OpenAI models
  • Without AI configuration, only legacy filtering works
• Configure forwarding settings in fwd.toml if you want important emails forwarded
• Edit rules.toml to configure all your filtering rules:
  • [delete] section for subject lines and senders that should be deleted
  • [ignore] section for subjects/senders to skip AI and mark as read
  • [forward] section for subjects/senders to always forward (skip AI)
• Build a docker image either make dockerbuild or just docker build -t sometag .
• Run the docker image on cron or other scheduled thing of your choosing. (I'm lazy, so my crontab says docker run -dt emailthing (where emailthing is my tag of choice, and the one auto-chosen by the makefile if you use it))

Test Mode

To test your AI configuration and see what the AI thinks about each email without actually deleting or forwarding anything, use the --test flag:

python3 emailprocess.py --test

In test mode:

• No emails will be deleted
• No emails will be forwarded
• No emails will be marked as read
• All actions show [TEST MODE] prefix with what would happen
• AI classifications are displayed (IMPORTANT, SPAM, IGNORE)
• Statistics show "would be deleted/forwarded" instead of actual counts

This is useful for:

• Testing your Ollama model's classification accuracy
• Verifying AI configuration before running in production
• Debugging classification issues
• Understanding how the AI categorizes your emails

GitHub Actions Setup

If you want to run this automatically:

1. Add repository secrets for your configuration files:
   • CONFIG_TOML - Your config.toml content (with OpenAI API key or Ollama configuration)
   • ACCOUNTS_TOML - Your accounts.toml content
   • RULES_TOML - Your rules.toml content (with filtering rules)
   • FWD_TOML - Your fwd.toml content (optional)
   • SSH_DEPLOY_KEY - SSH private key for committing changes back to the repo
2. These multi-line secrets work just like SSH keys - paste the entire file content
3. The workflow runs hourly (or manually via workflow_dispatch)
4. New spam senders discovered by AI are automatically committed to rules.toml
5. Note: For Ollama in GitHub Actions, you'll need to set up a self-hosted runner with Ollama installed