Spam

The spam plugin counts behaviour over time windows and punishes members who exceed your limits. It is bucket-based: each rule tracks its own window, and a member trips the rule by exceeding count within interval seconds.

plugins:
  spam:
    levels:
      0:                          # rules for everyone at level 0+
        max_messages:
          count: 12
          interval: 10
        max_mentions:
          count: 8
          interval: 10
        punishment: TEMPMUTE
        punishment_duration: 600
        clean: true
        clean_count: 50
        clean_duration: 120
      50: {}                      # mods exempt

Setup checklist

1. Open Setup > Filters and add one rule for level 0. Begin with a generous count and a short interval.
2. Set punishment: NONE for the first test. Turn on cleanup only in a private channel where deleting the test messages is safe.
3. Add an empty block at your staff level, such as 50: {}, if moderators should be exempt.
4. Subscribe a mod log channel to Spam violation so every trip is visible even without punishment.
5. Save, run Diagnostics, and use the message simulator to see which counters one test message increments.
6. As a level 0 test member, cross the threshold. Confirm the violation log and optional cleanup.
7. Add the intended punishment and duration. Test again before expanding the rule to busy channels.

count is the allowed bucket size and interval is seconds. A rule trips when the member exceeds the count inside that window. Keep those units in mind when copying examples.

Tuning individual rules

Every rule block takes more than count and interval. Give one its own punishment, punishment_duration, or channel_whitelist and that rule overrides the sub-config default - so you can mute for mention floods while merely cleaning up on link spam.

Two values worth knowing:

• punishment: NONE detects and cleans without punishing anyone, which is the safe way to trial a new limit.
• count: 0 (or interval: 0) switches a rule off without deleting it.

Scoping

Like censor, rules live in sub-configs keyed by level (levels) or role (roles); an empty higher-level block exempts staff. Each sub-config can also carry a channel_whitelist of places it ignores (a listed channel's threads and forum posts are ignored with it).

The rules

Each of these takes { count, interval }:

• max_messages - raw message rate.
• max_mentions - user/role mentions. Only mentions that actually ping count: a reply with reply-pinging turned off adds nothing, while a reply that pings the original author counts as one mention.
• max_duplicates - repeated identical messages.
• max_links, max_attachments, max_emojis, max_newlines, max_upper_case - exactly what they say.

Punishment and cleanup

• punishment - what happens on a trip (for example TEMPMUTE, MUTE, KICK, TEMPBAN, BAN), with punishment_duration for the timed ones. Punishments create real infractions, so they show in the mod log and expire automatically.
• Every trip also logs the Spam violation mod log event (which rule tripped and why), whether or not a punishment is configured - enable it in your mod log channel's event picker to see spam hits as they happen.
• clean - delete the offending backlog: up to clean_count recent messages from the member within clean_duration seconds.

Testing

The Setup → Filters message simulator includes spam: it lists every rule that would count a given message and the per-message cost, so you can sanity- check thresholds before a raid does it for you. Each rule shows the config key it comes from (for example plugins.spam.levels.50.max_mentions), so tuning it is a straight lookup in your config.

Troubleshooting

• A moderator cannot trigger the test: a higher-level empty block exempts them.
• Detection logs but nobody is punished: NONE is detection-only, and a per-rule punishment overrides the surrounding level or role default.
• A timed mute or ban fails: set the corresponding duration and check the infractions plugin, mute role, Discord permission, and role hierarchy.
• Cleanup misses old messages: it only considers up to clean_count messages inside clean_duration seconds.
• A channel appears exempt: inspect both the sub-config and per-rule channel_whitelist values.