Advanced Form Blocker

Documentation

Welcome to the Advanced Form Blocker documentation. This guide will help you install, configure, and effectively use the plugin to protect your WordPress forms from unwanted submissions.

Table of Contents:

  1. Installation
  2. Configuration
  3. Using the REST API
  4. Form Plugin Integration
  5. Troubleshooting / FAQ
  6. Changelog

1. Installation

There are two primary ways to install Advanced Form Blocker:

A. Via WordPress Admin (Recommended):

  1. Download: Download the latest release .zip file from the GitHub Releases page.
  2. Navigate: In your WordPress dashboard, go to Plugins > Add New.
  3. Upload: Click the Upload Plugin button at the top of the page.
  4. Choose File: Click Choose File and select the .zip file you downloaded.
  5. Install: Click Install Now.
  6. Activate: Once installed, click Activate Plugin.

B. Via FTP:

  1. Download & Unzip: Download the latest release .zip file from the GitHub Releases page and unzip it on your computer.
  2. Upload Folder: Upload the advanced-form-blocker (or the plugin’s folder name) directory to the /wp-content/plugins/ directory on your server using an FTP client.
  3. Activate: Go to Plugins in your WordPress dashboard. Find “Advanced Form Blocker” in the list and click Activate.

2. Configuration

After activating the plugin, a new menu item will appear in your WordPress admin sidebar.

2.1 Accessing the Settings Page

Navigate to Settings > Form Blocker in your WordPress admin sidebar to access all plugin options.

2.2 Blocklist Management

This section allows you to manage the list of email addresses, domains, and referring URLs that will be blocked from submitting forms.

2.2.1 Preparing your blocklist.json file

The plugin uses a JSON file to manage your blocklists. Create a file named blocklist.json with the following structure:

{
  "domains": [
    "blockeddomain.com",
    "another-spammer.org",
    "disposable-email.net"
  ],
  "emails": [
    "spammer@example.com",
    "unwanted@test.net",
    "persistent-offender@mail.com"
  ]
}
  • domains: An array of strings. Any email address from these domains will be blocked (e.g., anyuser@blockeddomain.com).
  • emails: An array of strings. These specific email addresses will be blocked.

2.2.2 Uploading New Blocklist

  1. Under the “Blocklist Management” section, click Choose File.
  2. Select your prepared blocklist.json file from your computer.
  3. Click Upload File. The plugin will process your file and update the blocklist.

2.2.3 Current Blocklist Content

This read-only section displays the content of the currently active blocklist.json file for your review. It will reflect the last successfully uploaded list.

2.3 API Key Management

The REST API allows external systems to securely access your blocklist.

  • Current API Key: An API key is automatically generated upon plugin activation. You can view the current API key here.
  • Regenerate Key: If you need to invalidate the current API key and create a new one (e.g., if the old key is compromised), click Regenerate Key. This will immediately invalidate the old key.

2.4 API Configuration & Status

This section displays the current status of your API and the URL to access it.

  • Enable API Access: Check the box “Allow external access to the blocklist via REST API” to activate the API endpoint. The API is disabled by default for security.
  • API URL: If the API is enabled and a key is set, a full, copyable API URL (including the current API key) will be displayed here. This is the URL you will use for external system integrations.
  • Save Changes: Click Save API & Message Settings after changing the “Enable API Access” status or custom messages.

2.5 Custom Block Messages

Define the messages users will see if their submission is blocked.

  • Blocked Email Message: Enter the message users will see if their specific email address is blocked.
    • Default: “This email address is not allowed for submission.”
  • Blocked Domain Message: Enter the message users will see if the domain of their email address is blocked.
    • Default: “Submissions from this email domain are not allowed.”
  • Save Changes: Click Save API & Message Settings to save your custom messages.

3. Using the REST API

The primary purpose of the REST API is to allow trusted external systems (like a backend script for your CRM or a marketing automation platform) or administrators to securely fetch the current blocklist.

3.1 Endpoint URL

Once the API is enabled and a key is generated, the full API Endpoint URL will be displayed in the plugin settings under “API Configuration & Status”. It will look something like:
https://yourdomain.com/wp-json/afb/v1/list?key=YOUR_ACTUAL_API_KEY

3.2 Authentication

The API uses key-based authentication. The key parameter in the URL must match the currently active API key in the plugin settings.
Important: Treat your API key as a secret. Do not expose it in public client-side code. It should only be used in server-to-server communication or by trusted administrators.

3.3 Expected JSON Response

A successful GET request to the API endpoint will return a JSON response containing the current blocklists and configured block messages:

{
  "domains": [
    "blockeddomain.com",
    "another-spammer.org"
  ],
  "emails": [
    "spammer@example.com",
    "unwanted@test.net"
  ],
  "messages": {
    "blocked_email": "This email address is not allowed for submission.",
    "blocked_domain": "Submissions from this email domain are not allowed.",
    "blocked_referrer": "Submissions from this referring source are not allowed."
  }
}

If the API is disabled or the key is invalid/missing, an appropriate error response will be returned.

3.4 Example Usage with External Systems (Pardot/CRMs)

For Pardot (Salesforce Marketing Cloud Account Engagement), HubSpot, or other CRMs:

  1. Enable the API and copy the full API Endpoint URL from the plugin settings.
  2. Develop a Server-Side Script: A developer can create a script (e.g., a scheduled cron job, a cloud function in Python, PHP, Node.js) that:
    • Periodically calls your plugin’s API endpoint using the API key.
    • Parses the returned JSON (domains, emails, referrers, and messages).
    • Uses the CRM’s API to:
      • Update a suppression list.
      • Create or update dynamic lists for segmentation.
      • Flag contacts.
      • Potentially, if your CRM form handlers allow it, check against this list before processing an external form submission.
  3. Landing Page Scripts (Advanced): For custom landing pages, a server-side script on the page template could fetch this list and prevent form submission directly if a match is found, providing a real-time block.

4. Form Plugin Integration

Advanced Form Blocker is designed to integrate with popular WordPress form plugins.

4.1 Gravity Forms

  • Status: Currently supported.
  • Functionality: The plugin automatically hooks into Gravity Forms’ submission validation process. If an email, domain, or referrer matches an entry in your blocklist, the form submission will be prevented, and the corresponding custom block message will be displayed to the user.

4.2 Other Form Plugins (Future)

We aim to expand support for other popular form plugins such as:

  • Contact Form 7
  • WPForms
  • Ninja Forms
  • (And more, based on demand)

Check the plugin’s GitHub page for updates on new integrations.

5. Troubleshooting / FAQ

  • Q: My blocklist doesn’t seem to be working.
    • A:
      • Ensure the plugin is activated.
      • Double-check the blocklist.json file for correct JSON syntax. You can use an online JSON validator.
      • Verify you have uploaded the correct blocklist.json file in Settings > Form Blocker.
      • Check the “Current Blocklist Content” display in the settings to see if your uploaded list is loaded correctly.
      • Ensure your form plugin (e.g., Gravity Forms) is active and compatible.
      • Clear any caching on your site (WordPress caching plugins, server-side caching, CDN) after uploading a new blocklist.
  • Q: The API is returning an error.
    • A:
      • Ensure “Enable API Access” is checked in Settings > Form Blocker > API Configuration & Status.
      • Verify the API key used in your request URL matches the “Current API Key” displayed in the settings.
      • If you recently regenerated the key, make sure your external system is using the new key.
  • Q: How do I report a bug or request a feature?

6. Changelog

For a detailed list of changes in each version, please refer to the changelog.md file in the plugin directory or visit the Releases page on GitHub.

Thank you for using Advanced Form Blocker! We hope it helps you maintain cleaner and more valuable form submissions.