# rspamd-mail-trainer

Small defensive admin tool for Linux mail servers. It finds messages in Maildir
or mbox mailboxes by sender, recipient, subject, date or selected text and then
passes the matching messages to `rspamc learn_spam` or `rspamc learn_ham`.

Designed for setups such as Rocky Linux + Postfix/Dovecot + Rspamd.

## Features

- Searches Maildir and mbox mailboxes.
- Tries to discover common mailbox roots automatically, including `doveconf -n`.
- Filters by `From`, `To`, `Subject`, header/body text and date range.
- Trains spam and ham via `rspamc`.
- Asks for confirmation before training.
- Refuses broad runs without any filter.
- Deduplicates matches by SHA-256.
- Extracts single mbox messages to temporary `.eml` files before training.
- Provides `search`, `check`, `train spam` and `train ham` subcommands.

## Install

From the repository root:

```bash
sudo python3 -m pip install .
```

Then:

```bash
rspamd-mail-trainer --help
```

For a local editable install during development:

```bash
python3 -m pip install -e .
```

## Quick start

Discover mailbox roots for the Unix user `johannes`:

```bash
sudo rspamd-mail-trainer roots --user johannes
```

Search suspicious messages from a sender:

```bash
sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test
```

Train matches as spam:

```bash
sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test
```

Train matches as ham:

```bash
sudo rspamd-mail-trainer train ham --user johannes --subject "Invoice"
```

Run Rspamd analysis without training:

```bash
sudo rspamd-mail-trainer check --user johannes --from no-reply@example.test
```

## Useful options

Treat filter arguments as literal text instead of regex:

```bash
sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test --literal
```

Search subject:

```bash
sudo rspamd-mail-trainer search --user johannes --subject "Monthly report"
```

Search selected headers and text body:

```bash
sudo rspamd-mail-trainer search --user johannes --any "unsubscribe"
```

Restrict by date:

```bash
sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test --after 2026-06-01 --before 2026-06-13
```

Dry-run training:

```bash
sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test --dry-run
```

Skip confirmation for a known-safe batch:

```bash
sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test --yes
```

## Push to Gitea

Create a new empty repository in Gitea, then run from this directory:

```bash
git init
git add .
git commit -m "Initial import of rspamd mail trainer"
git branch -M main
git remote add origin ssh://git@gitea.example.local/johannes/rspamd-mail-trainer.git
git push -u origin main
```

Replace the remote URL with your Gitea repository URL.

A Gitea Actions workflow is included at `.gitea/workflows/ci.yml`.

## Development

Run tests without external dependencies:

```bash
python3 -m unittest discover -s tests
```

Build a Python package:

```bash
python3 -m pip install build
python3 -m build
```

## Safety notes

This tool reads local mailboxes and can train your Rspamd classifier. Start with
`search`, `check` or `--dry-run`. Avoid broad patterns unless you inspected the
matches. Train good messages as ham from time to time, not only spam.

## License

MIT