Revolutionary Spam Documentation

Revolutionary Spam is a self-hosted spam filter for WordPress comments and forms. Instead of shipping every submission off to an external service, it runs a series of lightweight checks right on your own server -- a honeypot, a time trap, keyword and IP blocklists, and pattern analysis -- then combines them into a single score.

When a submission scores at or above your threshold, it is quarantined rather than deleted. You review the quarantine at your leisure, bulk-clear the obvious junk, and restore the rare false positive with one click. Nothing is silently dropped, and nothing about your visitors ever leaves your database.

Tip: The defaults are deliberately safe out of the box. The honeypot and time trap alone stop the vast majority of automated spam, so you can leave scoring and blocklists for later once you see what's actually getting through.

Revolutionary Spam installs like any standard WordPress plugin, from the bundled .zip archive or directly from the Revolutionary Plugins hub.

Upload the plugin. Go to Plugins -> Add New -> Upload Plugin and choose revolutionary-spam.zip. Click Install Now.
Activate. A new Spam Shield menu appears in the admin sidebar and protection switches on immediately.
Review the defaults. The first activation enables the honeypot and time trap with a sensible quarantine threshold. Nothing else is required for comment protection to start working.
Verify your license. Paste your license key under Spam Shield -> Settings -> License to unlock blocklists, tunable scoring, form and login protection, and automatic updates.

Heads up: If you run a full-page cache, the honeypot and time trap use a per-render token. Exclude the comment and form endpoints from caching, or enable the built-in cache-safe mode under Settings -> Performance, so the token stays fresh.

Confirm protection is live and tune it to your site. The whole thing takes about two minutes.

Open the dashboard. Go to Spam Shield -> Dashboard. You'll see blocked counts, the current quarantine size, and which signal is catching the most spam.
Send a test comment. Post a normal comment on any article -- it should sail through. Then submit a comment containing a dozen links; it lands in quarantine with the reason attached.
Set your threshold. Under Settings -> Scoring, choose where the quarantine line sits. Lower it to be stricter on a comment-heavy blog, raise it on a busy support form.
Seed your blocklist. Add a few obvious spam keywords and any repeat-offender IPs under Settings -> Blocklists. You can always grow this from the quarantine later.
Review weekly. Glance at the quarantine once a week. Bulk-delete the junk, restore anything that slipped in, and let auto-purge clear the rest.

Revolutionary Spam layers several independent checks. Each one is invisible to real visitors, and each contributes to the final score rather than acting as a single make-or-break gate.

Defense	What it does	Default weight
Honeypot	A hidden field that bots fill in and humans never see. The single most reliable bot signal.	+60
Time trap	Measures how long the form was on screen. Submissions completed implausibly fast are flagged.	+30
Link count	Counts outbound URLs in the body. A wall of links is a classic spam tell.	+2 per link
Keyword blocklist	Matches banned words and phrases anywhere in the submission.	+40 per hit
IP blocklist	Rejects submissions from addresses or ranges you've flagged.	+50
Repeat-content trap	Flags identical bodies posted across many pages in a short window.	+35

Because each defense adds weight independently, a single weak signal won't quarantine a real comment, and a determined bot usually trips several at once and lands near the top of the quarantine.

Every submission starts at a score of 0. Each defense that fires adds its weight. When the total reaches your quarantine threshold (50 by default), the submission is held for review instead of being published. You can tune both the per-defense weights and the threshold under Settings -> Scoring.

Scoring is transparent on purpose. Open any quarantined item and you see the exact breakdown of which defenses fired and how many points each added, so you're never guessing why something was caught. Set a higher threshold to be lenient, a lower one to be strict.

Tip: If a few real comments are scoring just over the line, don't disable a defense -- nudge the threshold up by 10 first. You'll keep every signal active while giving genuine submissions a little more headroom.

Blocklists let you target the spam your site sees specifically. Add words, phrases, email patterns, and IP addresses or CIDR ranges under Settings -> Blocklists. Keyword matches are case-insensitive and can use simple wildcards.

Keywords: one entry per line. Use * as a wildcard, for example cheap-*-deal catches a whole family of spam.
IP addresses: single addresses or CIDR ranges such as 203.0.113.0/24.
Author patterns: block by email domain or display-name pattern when a bot reuses the same persona.

Every quarantined item has an Add to blocklist shortcut, so you can grow your lists straight from real spam. On the Agency plan, blocklists sync across all your sites automatically.

Careful with broad rules: A keyword like free or an over-wide CIDR range will catch real people. Prefer specific multi-word phrases and tight ranges, and check the quarantine after adding a new rule.

The quarantine under Spam Shield -> Quarantine is where every flagged comment and form entry lives until you decide its fate. Items are sorted by score with the highest, clearest spam at the top, so review is fast.

Reason shown per item, the exact defenses that fired and the point breakdown.
Sort and filter by score, source (comments, a specific form, login), or date.
Restore in one click, a false positive goes straight back to its comment thread or form entry, score and all.
Bulk actions, delete, restore, or add the author's keyword or IP to the blocklist for the selected items.
Auto-purge, quarantined items older than a configurable number of days are deleted automatically so the table never balloons.

Quarantine access respects WordPress capabilities. By default only administrators can review it; grant the revspam_manage_quarantine capability to give an editor or a custom moderation role access.

The dashboard turns raw blocks into something you can read at a glance. See how much spam was stopped today, this week, and this month, and which defense did the heavy lifting, so you can tune the weights that matter for your site.

Blocked totals over time, with a trend so you can spot a sudden spam wave.
Breakdown by signal, what share of blocks came from the honeypot, time trap, or blocklists.
False-positive rate, how often you've restored an item, the number to keep low.
Top offenders, the IPs and keywords your blocklist is catching most.

All of this is stored in your own database. There is no hosted analytics dashboard and no data sent anywhere -- the numbers are yours and they stay on your server.

Out of the box, Revolutionary Spam screens the entry points bots target most:

Comments, every native WordPress comment is scored before it's published.
The login form, brute-force and credential-stuffing scripts trip the time trap and IP blocklist.
Revolutionary Forms, any form built with our form plugin is scored automatically with no extra setup.
Custom forms, developers can route any submission through the same engine with the revspam_score filter.

Each surface can be toggled independently under Settings -> Protection, so you can run strict scoring on comments while leaving a trusted internal form untouched.

To add the honeypot and time-trap fields to a custom HTML form, drop the shortcode anywhere inside your <form>. It renders the hidden trap fields and the timing token.

// Drop inside any form to add the honeypot + time trap
[revolutionary_spam_field]

// Name the trap field yourself if you have a convention
[revolutionary_spam_field name="website_url_confirm"]

On submission, score the request server-side with the revspam_check() helper. It returns the numeric score and whether it crossed your threshold:

if ( function_exists( 'revspam_check' ) ) {
    $result = revspam_check( [
        'content' => $_POST['message'],
        'email'   => $_POST['email'],
        'ip'      => $_SERVER['REMOTE_ADDR'],
        'source'  => 'newsletter',
    ] );
    if ( $result['is_spam'] ) {
        wp_die( 'Your submission was flagged. Please try again.' );
    }
}

Flagged submissions passed through revspam_check() are written to the same quarantine as comments, so a real person you accidentally block is one click from being restored.

Developers can adjust scoring and react to quarantine events with standard WordPress filters and actions. Use the revspam_score filter to add your own signal to the score before the threshold is checked:

add_filter( 'revspam_score', function( $score, $submission ) {
    if ( stripos( $submission['content'], 'guaranteed returns' ) !== false ) {
        $score += 45;
    }
    return $score;
}, 10, 2 );

Use the revspam_quarantined action to run custom logic -- logging, alerting, or syncing -- whenever a submission is held for review. Other commonly used hooks include revspam_is_whitelisted, revspam_threshold, revspam_blocklist_keywords, and revspam_restored.

Most issues trace back to caching or an over-broad blocklist. Work through these first:

Spam still getting through: lower the quarantine threshold, confirm the honeypot is enabled, and add the offending keywords or IPs from the items that slipped past.
Real comments quarantined: open the item to see which defense fired. If it's the time trap, your page cache may be serving a stale token -- enable cache-safe mode. If it's a keyword, tighten the rule.
Honeypot never triggers: a page cache is likely stripping or freezing the hidden field. Exclude the comment and form endpoints from caching.
Login protection blocks me: add your own IP to the allowlist under Settings -> Protection -> Login before tightening the rules.
Quarantine table is huge: turn on auto-purge so items older than your chosen window are cleared automatically.

Tip: Enable Settings -> Logging to record the score and reasons for every checked submission, including the ones that passed. The log makes it obvious whether a defense is firing too often or not at all.

Correct. Every check runs on your own server and no comment text, email, or IP is sent anywhere for scoring. The plugin works the same whether or not your server can reach the internet, which is why it passes strict compliance reviews.

Yes. They coexist without conflict. If Akismet is active, its verdict is included as one more signal in the score. Most people deactivate Akismet once they see Revolutionary Spam catching everything on its own.

No. The full set of checks adds well under a millisecond per submission because it's all local pattern matching and lookups, no network round-trip to wait on. Visitors never notice it's there.

It's quarantined, not deleted. You'll find it in the quarantine list, clearly marked with its score and the reasons it was flagged, and one click restores it to the comment thread. Nothing is ever lost.

No. The free version protects comments with the honeypot, time trap, quarantine, and basic stats. The paid suite unlocks keyword and IP blocklists, tunable scoring, and form and login protection, plus the other 15 Revolutionary plugins.

DOCUMENTATION

The defenses

Scoring & thresholds

Blocklists

Quarantine

Stats & reports

Shortcode & hooks

Introduction

Installation

Your first run

The defenses

Scoring & thresholds

Keyword & IP blocklists

Quarantine

Stats & reports

What's protected

Shortcode & checks

Hooks & filters

Troubleshooting

FAQ

Frequently asked questions

Was this helpful?