Real-time spam detection for WordPress comments and user registrations, powered by the Spamtroll API.
- Comment scanning — automatically checks incoming comments for spam using the Spamtroll API
- Registration scanning — blocks spam bots from creating accounts on your site
- Configurable thresholds — set separate spam and suspicious score thresholds (0–100%)
- Flexible actions — choose to block or send to moderation for spam and suspicious content
- Role-based bypass — skip scanning for trusted roles (administrators, editors, etc.)
- Fail-open architecture — API errors never block legitimate content
- Detailed logging — view scan results with status, scores, and threat categories in the admin panel
- Automatic log cleanup — daily cron job removes old log entries based on configurable retention period
- Full i18n support — translation-ready with included
.pottemplate
- WordPress 5.6 or higher
- PHP 7.4 or higher
- A Spamtroll API key (get one at spamtroll.io)
- Download the latest release ZIP from the Releases page
- In your WordPress admin panel, go to Plugins → Add New → Upload Plugin
- Upload the ZIP file and click Install Now
- Click Activate Plugin
- Download and extract the latest release
- Upload the
spamtroll-wordpressfolder to/wp-content/plugins/ - In your WordPress admin panel, go to Plugins
- Find Spamtroll Anti-Spam in the list and click Activate
cd /path/to/wordpress/wp-content/plugins
git clone https://github.com/spamtroll/spamtroll-wordpress.gitThen activate the plugin in your WordPress admin panel under Plugins.
After activation, navigate to Spamtroll → Settings in your WordPress admin sidebar.
| Setting | Description | Default |
|---|---|---|
| Enable Plugin | Turn spam scanning on/off | Disabled |
| API Key | Your Spamtroll API key | — |
| API URL | Spamtroll API endpoint | https://api.spamtroll.io/api/v1 |
| Timeout | API request timeout in seconds | 5 |
Use the Test Connection button to verify your API key is valid.
| Setting | Description | Default |
|---|---|---|
| Check Comments | Enable comment spam scanning | Enabled |
| Check Registrations | Enable registration spam scanning | Enabled |
| Spam Threshold | Score above which content is treated as spam (0.0–1.0) | 0.70 |
| Suspicious Threshold | Score above which content is treated as suspicious (0.0–1.0) | 0.40 |
| Setting | Description | Default |
|---|---|---|
| Spam Action | What to do with spam content: Block or Send to moderation | Block |
| Suspicious Action | What to do with suspicious content: Send to moderation or Allow | Send to moderation |
Select which WordPress user roles should bypass spam scanning entirely. By default, Administrator and Editor roles are bypassed.
| Setting | Description | Default |
|---|---|---|
| Log Retention | Number of days to keep log entries (1–365) | 30 |
Navigate to Spamtroll → Logs to see all scan results. You can filter by status:
- All — every scanned item
- Blocked — items identified as spam
- Suspicious — items flagged for review
- Safe — items that passed scanning
Each log entry shows the date, content type, IP address, status, spam score, action taken, and a content preview.
- When a comment is submitted or a user registers, the plugin sends the content, IP address, username, and email to the Spamtroll API
- The API returns a spam score (normalized to 0–1) along with detection symbols and threat categories
- Based on your configured thresholds, the plugin categorizes the content as blocked, suspicious, or safe
- The configured action is taken automatically (block, moderate, or allow)
- The result is logged to the database for review
If the API is unreachable or returns an error, the content is always allowed through (fail-open), ensuring legitimate users are never blocked by connectivity issues.
spamtroll-wordpress/
├── spamtroll.php # Main plugin file & bootstrap
├── uninstall.php # Clean uninstall (removes all data)
├── includes/
│ ├── class-spamtroll-admin.php # Admin settings & logs UI
│ ├── class-spamtroll-api-client.php # HTTP client for Spamtroll API
│ ├── class-spamtroll-api-exception.php # Custom exception handling
│ ├── class-spamtroll-api-response.php # Response wrapper & score normalization
│ ├── class-spamtroll-logger.php # Database logging
│ └── class-spamtroll-scanner.php # Comment & registration scanning logic
├── assets/
│ ├── css/admin.css # Admin panel styles
│ └── js/admin.js # Admin panel scripts (test connection)
└── languages/
└── spamtroll.pot # Translation template
When you delete the plugin through the WordPress admin panel, it performs a clean removal:
- Removes all plugin settings from the database
- Drops the
{prefix}spamtroll_logstable - Clears any scheduled cron jobs
Simply deactivating the plugin does not remove any data — only full deletion does.
Visit spamtroll.io to create an account and obtain your API key.
The plugin makes a single API call per comment or registration. The default timeout is 5 seconds. If the API is slow or unreachable, the content is allowed through immediately without blocking the user experience.
Yes, as long as the form uses WordPress's standard comment submission hooks (preprocess_comment and pre_comment_approved).
Yes, Spamtroll works at the comment preprocessing level and is compatible with other anti-spam solutions. However, running multiple spam plugins may result in redundant checks.
Your settings and logs are preserved. Comments and registrations will proceed without spam checking. Reactivate the plugin to resume scanning.
See CHANGELOG.md for a full list of changes.
This project is licensed under the MIT License — see the LICENSE file for details.