====== AV-SPAM Stats ======

The **AV-SPAM Stats** page provides detailed statistics and analytics about your spam filtering performance. It is found under **Server Management > AV-SPAM Stats** (or via **Usage Information > AV-SPAM Stats**).

===== Overview Tab =====

The **Overview** tab displays key performance indicators and summary charts:

==== KPI Cards ====

Five summary cards show the current state of your mail flow:

  * **Total Messages** — Number of messages seen in the selected time window.
  * **Rejected** — Messages rejected outright by Rspamd.
  * **Spam Rate** — Percentage of messages classified as spam.
  * **Avg Score** — Average spam score across all scanned messages.
  * **Avg Scan Time** — Average time Rspamd spent scanning each message.

==== Actions Over Time ====

A line chart shows how Rspamd actions (Clean, Probable Spam, Greylisted, Rejected, etc.) have trended over the selected period.

Use the time range buttons to zoom in or out:
  * 1h — Last hour
  * 6h — Last 6 hours
  * 24h — Last 24 hours
  * 7d — Last 7 days
  * 30d — Last 30 days
  * All — Complete history

==== Action Distribution ====

A pie chart visualizes the proportion of each action type (clean, probable spam, greylisted, rejected, etc.).

==== Top 20 Symbols ====

A table showing the most frequently triggered Rspamd symbols (rules) and their hit counts. Symbols are the internal rule names that Rspamd uses to score messages, such as:

  * ``BANNED_COUNTRY`` — Triggered by GeoIP country blocking
  * ``R_SPF_FAIL`` — SPF check failure
  * ``R_DKIM_REJECT`` — DKIM signature verification failure
  * ``HFILTER_HOSTNAME_UNKNOWN`` — Unknown or suspicious sender hostname

===== Trends Tab =====

The **Trends** tab provides historical trend analysis with additional granularity. Use this to identify patterns in spam volume, score distributions, and rule effectiveness over longer periods.

===== History Tab =====

The **History** tab shows a searchable table of recently processed messages:

^ Column ^ Description ^
| Time | When the message was processed |
| Action | Rspamd's final decision (Clean, Probable Spam, Greylisted, Rejected, etc.) |
| Score | The spam score assigned to the message |
| Required | The threshold score required to trigger the action |
| From | SMTP envelope sender address |
| IP | Source IP address of the connection |
| To | Recipient address |
| Size | Message size in bytes |
| Details | Hidden details including Symbols, Message-ID, and Queue-ID (searchable) |

**Search:** You can search by any visible or hidden field. For example, searching for a specific Message-ID or Queue-ID will filter the history table even though those columns are not visible.

**Note:** The History data comes from the Rspamd controller's Redis/Valkey-backed history store. The retention period and row count are configurable in the **AV-SPAM Settings > Services** tab (default: 1000 rows, 7 days retention).

===== Details Tab =====

The **Details** tab contains two additional tables:

==== Action Thresholds ====

^ Action ^ Threshold ^ Count ^
| Clean | < 4.0 | 1234 |
| Probable Spam | 4.0 - 5.0 | 56 |
| Greylisted | 4.0 | 12 |
| Rejected | >= 15.0 | 3 |

This shows how many messages fell into each action category based on the configured thresholds.

==== Symbol Metadata ====

A sortable and paginated table of all Rspamd symbols with their hit counts. This is useful for tuning custom rules or identifying new spam patterns. The table is paginated and may span many pages depending on the number of active symbols.

===== Raw Data Tab =====

The **Raw Data** tab provides direct access to the raw JSON output from the Rspamd controller API. This is primarily intended for advanced troubleshooting and integration with external monitoring systems.

===== Data Sources =====

All statistics are read from the **Rspamd controller** API, which listens locally on ``127.0.0.1:11334``. The controller password is auto-generated during module installation and stored securely in CODB. It is not exposed in the GUI.

The controller communicates with Redis/Valkey (``127.0.0.1:6379``) for:
  * Historical message data
  * Bayes classifier training data
  * Fuzzy hash storage
  * Neural network state

===== Navigation =====

The AV-SPAM Stats page is accessible from:

  * **Server Management > AV-SPAM Stats** (menu entry under Usage Information)
  * Direct URL: ``/rspamd/rspamdstats``

It is intentionally separate from the older ``/sitestats/summaryEmail`` page, which shows general mail volume statistics without spam classification details.

===== See Also =====

  * [[userguide:email:avspam|AV-SPAM (Anti-Spam) Settings]] — Configure spam filtering thresholds and modules

----