MDL Spam Filter

Stop contact form spam before it reaches your inbox. MDL Spam Filter is a lightweight anti-spam plugin that protects Contact Form 7, WPForms, Gravity Forms, Elementor forms, and any other contact form — using keyword filtering, a honeypot, rate limiting, a language guard, and optional AI spam detection (Anthropic Claude, OpenAI GPT, or any OpenAI-compatible provider). No CAPTCHA, no visitor friction, and nothing is stored or emailed until a submission passes the filter.

MDL Spam Filter scans front-end contact form submissions on the server before any form handler runs. When a submission is detected as spam, it is blocked: no email is sent — including the admin notification of a new submission and any autoresponder — and nothing is written to your form plugin’s entries or email log. You choose whether blocked submissions are recorded in this plugin’s own private log.

Detection works two ways, used alone or together:

• Keywords — a built-in list of common spam phrases plus your own custom keywords.
• AI — optional classification by Anthropic (Claude), OpenAI, or any custom OpenAI-compatible provider using your own API key.

The filter is form-agnostic. It inspects any POST request that carries an email address — or that is recognisably from a supported form plugin even without an email field — so it works with Contact Form 7, WPForms, Gravity Forms, Elementor forms, raw HTML forms, and most others without per-plugin configuration. AJAX and REST submissions (such as Contact Form 7) receive a proper response, so the submit spinner never hangs.

When AI detection is enabled, the verdict is requested as a strict yes/no decision and, where the provider supports it, constrained to a structured JSON response — so a confident block/allow is the only possible answer. If the AI provider is unreachable (outage, timeout, bad key) the plugin can fall back to a keyword scan instead of letting the submission through, and an optional per-visitor rate limit throttles floods before any AI call is made.

When spam is caught you choose what the sender sees:

• Silently discard — the form shows its normal success message while the submission is quietly dropped, giving bots no signal.
• Show a blocked message — the form displays a clear “flagged as spam” notice.

Key features

• Server-side blocking before the submission reaches form handlers or email.
• Works with AJAX and REST forms (Contact Form 7, WPForms, Gravity Forms, Elementor, and more) without hanging the submit spinner.
• Silent discard that mimics a successful send, or a visible blocked message.
• Keyword detection with 200+ built-in keywords organised into collapsible categories (pharma, SEO outreach, scams, gambling, and more) — each toggleable individually, per category, or all at once — plus unlimited custom keywords.
• Activate, pause, or remove individual keywords without losing them — custom keywords use the same chip interface as the built-in list.
• Regular-expression keywords: wrap a custom term in slashes (/pattern/) for advanced matching — invalid patterns are skipped safely.
• Per-keyword hit counters show how many submissions each keyword has blocked, so dead keywords are easy to prune.
• Review-queue feedback loop: one-click Allow sender / Block sender on held items, plus an inline “add keyword” box that turns a held spam’s telltale phrase into a blocking keyword.
• Optional AI detection via Anthropic, OpenAI, or a custom OpenAI-compatible provider (bring your own API key).
• AI verdicts constrained to a structured yes/no response (json_schema / json_object) where the provider supports it, so the result can’t be ambiguous free text.
• Custom AI detection rules: keep the built-in rules, write your own, or combine both — with a “Generate rules with AI” assistant and ready-made templates that draft rules from a plain-language description of your business.
• Keyword fallback when the AI provider is unavailable, so an API outage does not silently let spam through (AI-only mode; on by default).
• Optional per-visitor submission rate limit to throttle floods before any AI call is made.
• Honeypot field and minimum-submit-time check that stop obvious bots before any keyword or AI work (no cost, no false success signal).
• Optional language guard: block the languages and alphabets you choose (Cyrillic, Chinese, Arabic, and more) or allow only the ones you choose — plus an always-on trap for words mixing Latin with look-alike Cyrillic letters, a common keyword-filter evasion trick. Accented Latin languages are never affected.
• Allow list (never block) and deny list (always block) by email address, domain, or IP — with a one-click “Block sender” action on every Filter Log and Review row.
• Form targeting: scan all forms, or only selected forms identified by their id, class, or name.
• Outgoing-email safety net: when a submission is spam, every email it triggers is suppressed — including the admin “new submission” notification and any autoresponder.
• Review queue (on by default): hold keyword/AI-flagged submissions for manual review — the submission is stopped before anything is recorded or emailed. View the fields, then Accept to email it to the site admin (kept out of the filter log) or Block to drop it (recorded in the filter log). Optionally get an email notification when a submission is held.
• Optional email alert to an admin when the plugin hits a provider error — invalid or expired API key, exhausted credit or quota, or a provider outage — throttled to one email per distinct error every 10 minutes.
• Private, opt-in log of blocked submissions in a dedicated database table.
• Automatic retention cleanup: filter-log and review-queue entries older than a configurable number of days (default 90, 0 = keep forever) are pruned daily, so a spam flood cannot grow the database forever.
• Optional weekly email digest: blocked totals, detection-method breakdown, top blocked senders, and the review-queue backlog — skipped automatically when there is nothing to report.
• A dedicated Notifications settings section: one central notification email address for every alert (review holds, provider errors, weekly digest), an on/off toggle and optional override address per notification, a tag-style picker for adding multiple recipients to any field (plain comma-separated input still works), and a send-test button that resolves the recipient exactly like the real notification; everything falls back to the site admin email.
• “Spam blocked” counter in the WordPress dashboard At a Glance widget.
• Analytics dashboard with a 7/30/90-day period picker: daily blocked-submission chart, trend deltas against the previous period, busiest-day and awaiting-review tiles, detection-method breakdown, and top blocked senders and targeted pages — every bar, method, sender, and page clicks through to the pre-filtered Filter Log.
• System-health card on the dashboard: protection state, detection engine and API-key source, AI-provider status (from the circuit breaker — no live call), review-queue backlog, scheduled maintenance (with your retention period), and weekly-digest status, each with a fix-it link when something needs attention. The cron rows diagnose real scheduling problems: an overdue event (WP-Cron not firing on a quiet site) or a stale queue entry gets an amber warning with the fix.
• Dismissable setup checklist on the dashboard that tracks protection, detection, notifications, and the first test email — each step deep-links to the right screen.
• Dashboard aggregates are cached for five minutes so the overview never runs heavy queries on every load.
• Enterprise-grade admin polish: every screen opens with a one-line purpose statement and a primary action, a persistent banner warns on every screen when protection is off, the Filter Log, Review, and Activity lists all sort by date, table headers stay visible while scrolling long lists, and the whole UI follows your chosen WordPress admin color scheme.
• Accessible by design: keyboard-visible focus on every custom control (toggles, keyword chips, recipient pickers, chart bars), screen-reader table behind the dashboard chart, WCAG AA contrast on badges and status colors, and reduced-motion support.
• Contextual help on every screen: the WordPress Help flyout carries the screen’s purpose and the FAQ entries relevant to that page.
• One-click dashboard report export (CSV): totals, daily counts, method breakdown, and top senders/pages for the selected period.
• Filter Log excerpts expand in place, so long submissions can be read without leaving the list.
• Searchable, filterable log with date range and method filters, sortable dates, bulk delete, and CSV export.
• Settings import/export as JSON for moving configuration between sites (API keys are never exported).
• Keywords-only import/export for sharing keyword lists between sites without touching other settings.
• Activity audit log: who changed settings and keywords, imports/exports, log purges, AI connection tests, and AI provider outages — with automatic 90-day retention.
• Stores submitter IP as a one-way hash for privacy.
• WooCommerce-style navigation: a dedicated top-level MDL Spam Filter menu with Dashboard, Settings, Keywords, Review, Filter Log, Activity Log, Help, and Import/Export pages. The Settings page is organised into sections (Protection, Detection engine, AI engine, Advanced protection, Form targeting, Email & logging, Notifications) and the Help page into Getting started / FAQ / About — each with its own section links.

External Services

This plugin connects to third-party AI services only when AI detection is enabled, or when an admin uses the optional “Generate rules with AI” assistant on the settings page. Keyword-only mode with the assistant unused contacts no external service.

Anthropic (Claude API) Used to classify submission text as spam or genuine when the AI provider is set to Anthropic, and to draft custom detection rules when an admin uses the “Generate rules with AI” assistant. What is sent: the text content of the contact form submission and your API key, sent to the endpoint at the time a submission is scanned; and, only when an admin clicks “Generate rules with AI”, the business description that admin types into the assistant. Endpoint: https://api.anthropic.com/v1/messages Terms of Service: https://www.anthropic.com/legal/commercial-terms Privacy Policy: https://www.anthropic.com/legal/privacy

OpenAI (Chat Completions API) Used to classify submission text as spam or genuine when the AI provider is set to OpenAI, and to draft custom detection rules when an admin uses the “Generate rules with AI” assistant. What is sent: the text content of the contact form submission and your API key, sent to the endpoint at the time a submission is scanned; and, only when an admin clicks “Generate rules with AI”, the business description that admin types into the assistant. Endpoint: https://api.openai.com/v1/chat/completions Terms of Use: https://openai.com/policies/terms-of-use Privacy Policy: https://openai.com/policies/privacy-policy

Custom provider (optional) If you set the AI provider to “Custom”, submission text and your API key are sent to the OpenAI-compatible endpoint URL you enter in the settings — and, only when an admin clicks “Generate rules with AI”, the business description that admin types into the assistant. The endpoint must be an https:// URL that is not a private or loopback address (an http:// endpoint can be enabled with the mdlsf_allow_insecure_custom_endpoint filter for a trusted local model). No request is made unless you configure this. Because the endpoint is supplied by you, review the terms and privacy policy of whichever provider you point it at (for example OpenRouter, Groq, Together AI, or a self-hosted model).