Scan and Learn Mail Safely with rspamc

You will finish with a repeatable way to submit a message to Rspamd, inspect the result, check the controller, and make a deliberate learning request. The examples follow the installed rspamc 3.8.1 client from package rspamd 3.8.1-1ubuntu3.

Allow about fifteen minutes. You need a shell, the rspamc package, access to an Rspamd scanner or controller, and a test message saved as a file. Reading scan results is normally an unprivileged operation. Learning, fuzzy-storage changes, and other state-changing controller commands may require the controller password, depending on its configuration. This guide does not use sudo, restart a service, or edit Rspamd configuration.

1. Confirm the client before sending mail

Start with read-only checks. They do not need elevated privileges and make it clear which binary and command vocabulary you are using:

$ command -v rspamc
/usr/bin/rspamc
$ dpkg-query -W -f='${Package} ${Version}\n' rspamd
rspamd 3.8.1-1ubuntu3
$ rspamc --commands
Rspamc commands summary:
        symbols (normal  ) scan message and show symbols (default command)
           stat (control ) show rspamd statistics
         uptime (control ) show rspamd uptime
... 

The final output is longer than the excerpt. The installed client also reports that normal requests use port 11333 by default and control requests use port 11334 by default. A local package can expose more options than an older manpage, so use rspamc --help and the installed manpage when a detail matters.

2. Scan one message and show its symbols

Save a message as MESSAGE.eml, then submit it with the default scan command. A regular file is accepted; a directory is also accepted for a batch scan. The command reads standard input when no input file is supplied.

$ rspamc symbols MESSAGE.eml

symbols is the default command, so this is equivalent:

$ rspamc MESSAGE.eml

Successful output is a Rspamd report containing the message score, action and matched symbols. The exact symbols and scores depend on your configuration and the message. Check the exit status when scripting:

$ rspamc symbols MESSAGE.eml
$ status=$?
$ printf 'rspamc exit status: %s\n' "$status"
rspamc exit status: 0

Exit status 0 means the operation succeeded. It does not mean the message is safe or unwanted. Treat the score and action as the result of this Rspamd configuration, not as a universal verdict.

3. Choose an output format for scripts

Use --json when another program needs structured output. Use --human when a person needs a compact report. These are output choices, not changes to filtering policy.

$ rspamc --json symbols MESSAGE.eml
$ rspamc --human symbols MESSAGE.eml

The human report starts with the score and the greylist, add-header and reject thresholds, followed by action and status fields. If you need the response exactly as received, the manpage documents --raw. Keep machine-readable output separate from explanatory text if you are feeding it to a parser.

For a remote scanner, specify its host and port explicitly rather than assuming the local defaults:

$ rspamc --connect=SCAN_HOST:11333 --json symbols MESSAGE.eml

Replace SCAN_HOST with a host you administer. Do not place a real password or message containing private data into a public issue, terminal recording or diagnostic paste.

4. Check the controller without changing state

The controller handles statistics, uptime, learning and other control requests. Read-only checks are useful before attempting a learning operation:

$ rspamc uptime
$ rspamc stat
$ rspamc counters

Expected output is command-specific status or statistics, and it varies with traffic. A connection error usually means the controller is not listening at the selected address, a firewall blocks it, or the client is pointed at the wrong port. Adding sudo does not repair any of those conditions.

5. Learn a confirmed spam or ham message

Learning changes Rspamd state. Verify the message and its label before running this step, and make sure your operating procedure permits training. The default classifier is bayes; use --classifier only when your deployment has another configured classifier.

Do not put a real password directly in a command copied into shell history. Read it without echoing, then pass it to the client for this process:

$ read -r -s -p 'Rspamd control password: ' RSPAMD_PASSWORD
$ printf '\n'
$ rspamc --password="$RSPAMD_PASSWORD" learn_spam MESSAGE.eml
$ unset RSPAMD_PASSWORD

Use learn_ham for a confirmed non-spam message:

$ read -r -s -p 'Rspamd control password: ' RSPAMD_PASSWORD
$ printf '\n'
$ rspamc --password="$RSPAMD_PASSWORD" learn_ham MESSAGE.eml
$ unset RSPAMD_PASSWORD

The controller may use one password for both read-only and privileged operations, or separate passwords for them. The server configuration decides this. A successful client exit does not replace an audit trail: record which message was deliberately labelled according to your local process.

6. Handle fuzzy-storage commands carefully

fuzzy_add and fuzzy_del also require message input. Fuzzy operations use --flag to select a storage set and --weight for the operation. Confirm both values with the administrator who owns the fuzzy storage before changing anything.

$ rspamc --password="$RSPAMD_PASSWORD" --flag=2 --weight=10 fuzzy_add MESSAGE.eml

Deletion is harder to undo than a scan and may remove a useful fuzzy hash. The manpage's example targets another controller explicitly:

$ rspamc --password="$RSPAMD_PASSWORD" --connect=CONTROLLER_HOST:11334 --flag=2 fuzzy_del MESSAGE.eml

Replace the placeholders only after checking the target, flag and message. There is no generic client-side undo command in the manpage. If you delete the wrong hash, recover through your fuzzy-storage backup or administrator procedure.

7. Diagnose the common traps

• No input file means standard input. A command such as rspamc stat does not need a message, but scan and learning commands do. If a command appears to wait, check whether it is reading the terminal.
• --connect=HOST:PORT selects the server. It does not select a password or grant access.
• --verbose adds client detail. --timeout=SECONDS changes how long the client waits for a reply; it does not make a slow controller healthy.
• --max-requests controls parallel requests and defaults to 8. Keep batch sizes and concurrency modest on a busy host.
• Options such as --ip, --from and --rcpt emulate message metadata. Use them only for a test that requires that context, because they can make a result differ from the message's actual delivery path.