Listmonk Newsletter Signup

A standalone newsletter sign-up form for WordPress, backed by a self-hosted Listmonk instance. This is NOT a "sync" plugin — it has nothing to do with WordPress user accounts or registration. It only powers a newsletter opt-in form, and checks Listmonk first so an email is never registered twice.

Installation

1. Upload the listmonk-connector folder via WordPress Admin -> Plugins -> Add New -> Upload Plugin (using the zip), or drop the folder into wp-content/plugins/.
2. Activate "Listmonk Newsletter Signup".
3. In Listmonk, go to Admin -> Users -> New and create a dedicated API user (do NOT reuse your personal admin login). Copy its username and the generated API token.
4. In WordPress, go to Settings -> Listmonk Newsletter and fill in:
   • Listmonk URL (e.g. https://lists.example.com)
   • Auth Method: "API Token" for Listmonk v4+, "Basic Auth" for older installs
   • API Username / API Token
   • List ID(s) - comma separated, found under Lists in Listmonk admin
5. Click "Test Connection" to confirm WordPress can reach the API.
6. (Optional) Tick "Enable ALTCHA" to add a self-hosted, privacy-friendly proof-of-work captcha (https://altcha.org) to the sign-up form. No third-party account or API key is needed — WordPress generates and verifies the puzzle itself. A signing key is auto-generated the first time you save settings.
7. Place the shortcode wherever you want the sign-up form: [listmonk_subscribe_form] Optional attributes: [listmonk_subscribe_form button_text="Join the list" show_name="no"]

What it does

• Renders a small email (+ optional name) opt-in form via the [listmonk_subscribe_form] shortcode.
• On submit (AJAX, no page reload):
  1. If ALTCHA is enabled, verifies the visitor solved the proof-of-work puzzle (server-side, cryptographic check — no external API call).
  2. Looks up the email in Listmonk (subscribers.email = ...).
  3. If found: tells the visitor they're already subscribed. No duplicate is created.
  4. If not found: creates a new Listmonk subscriber on the configured list(s).
• Includes a basic honeypot field for spam protection, plus optional ALTCHA.
• Exposes a public PHP function, listmonk_connector_ensure_subscribed( $email, $name ), in case you'd rather wire your own custom form markup to it instead of using the shortcode.

About the ALTCHA integration

• ALTCHA (altcha.org) is a free, open-source, GDPR-friendly captcha alternative based on proof-of-work rather than image/text puzzles.
• This plugin implements the classic SHA-256 challenge/response scheme entirely in PHP with no Composer dependency: WordPress generates a challenge (a salted hash plus an HMAC signature), the front-end widget brute-forces the answer, and WordPress verifies the signature and solution again on submit.
• The widget's JavaScript is loaded from the public jsDelivr CDN by default. If you'd rather avoid loading any third-party script, download altcha.min.js from https://github.com/altcha-org/altcha and use the lmc_altcha_widget_script_url filter to point at your own copy, e.g.: add_filter( 'lmc_altcha_widget_script_url', function() { return get_stylesheet_directory_uri() . '/js/altcha.min.js'; } );
• The signing key is stored in the lmc_settings option and never leaves your server. Use the "Rotate secret key" checkbox on the settings page if you ever need to invalidate it.

What it deliberately does NOT do

• It does not hook into WordPress user registration, login, or profile updates. WordPress accounts and Listmonk subscribers are treated as completely separate concepts.
• It does not import/export or two-way sync any existing WordPress users or Listmonk subscribers in bulk.

Notes

• The plugin never sends a WordPress login password to Listmonk. Use a Listmonk API user created specifically for this integration, and rotate its token if you ever suspect it's exposed.
• "Double opt-in" in the settings controls whether new subscribers are marked confirmed immediately or left pending Listmonk's normal opt-in email flow, depending on how your Listmonk lists are configured.