Listmonk – Redirect to a Custom Thank-You Page After Subscribing

When a visitor submits an embedded Listmonk subscription form, they land on a plain Listmonk message page hosted on your Listmonk domain. Listmonk has no built-in option to redirect elsewhere, but a small piece of custom JavaScript and one query parameter are enough to send subscribers to your own confirmation page.

The Problem #

The subscription form embedded on a website (for example a static Hugo site) posts directly to Listmonk’s /subscription/form endpoint. After submitting, the visitor is taken away from your site to a bare Listmonk page saying the subscription was successful. There is no place to explain what happens next — that a confirmation e-mail is on its way, which sender address to expect, or that it’s worth checking the spam folder.

This is a known limitation, tracked in knadh/listmonk#2145 . The issue was closed as stale without a native feature, but the maintainer suggested a workaround, which is what this article builds on.

Solution: A redirect Parameter and Custom JavaScript #

Listmonk lets you inject custom JavaScript into all of its public pages (Settings → Appearance → Public → Custom JavaScript). The script runs on the page shown after the form is submitted, so it can read the URL and redirect the browser.

The plan has two parts:

1. Append a redirect query parameter to the form’s action URL.
2. Let the custom script check for that parameter and redirect to your own page.

Step 1 – Add the Parameter to the Form #

Take the form code generated by Listmonk and add ?redirect=1 to the action attribute:

<form method="post"
      action="https://list.example.com/subscription/form?redirect=1"
      class="listmonk-form">
  ...
</form>

The query string is preserved on the resulting page, so the script can see it. The value can be anything; if you have several forms with different destinations, use different values and switch on them in the script.

Step 2 – Add the Script to Listmonk #

Paste the following into Settings → Appearance → Public → Custom JavaScript and change the target URL:

(function () {
  var params = new URLSearchParams(window.location.search);
  if (!params.has('redirect')) return;

  function run() {
    // Skip the subscription form page itself (a plain GET, not a submission).
    if (document.querySelector('form')) return;

    // Listmonk renders both success and error with the same template
    // (message.html) and no distinguishing CSS class. The only difference
    // is the HTTP status: errors are 4xx/5xx, success is 200.
    var nav = performance.getEntriesByType('navigation')[0];
    if (nav && nav.responseStatus && nav.responseStatus !== 200) return;

    window.location.replace('https://www.example.com/newsletter-subscribed/');
  }

  // custom.js is loaded with async, so the DOM may not be ready yet.
  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', run);
  } else {
    run();
  }
})();

Why the Status Check? #

The maintainer’s original snippet redirects unconditionally. That means a visitor who enters an invalid e-mail or fails the captcha would also be redirected to the “you are subscribed” page, which is misleading.

I first looked for a CSS class to tell the two cases apart, but the message.html template is just an <h2> with the title and a <div> with the message — success and error are identical in markup. The only reliable difference is the HTTP status of the response, which the Navigation Timing API exposes as responseStatus (Chrome 109+, Firefox 123+, Safari 17.4+). In an older browser the value is undefined and the script simply redirects, which is an acceptable fallback.

The Confirmation Page #

The target page can be anything static. A useful one tells the subscriber:

• that a confirmation e-mail (double opt-in) is on its way and must be clicked,
• that a welcome e-mail follows after confirmation,
• which sender address to expect, so they can whitelist it,
• to check the spam folder if nothing arrives.

Including a screenshot of the confirmation e-mail helps subscribers recognise it when it lands in their inbox.

Testing #

Submit the form with a valid address and verify you end up on your own page. Then trigger an error — for example, leave the captcha unsolved — and check that you stay on the Listmonk error page. If the error case redirects anyway, inspect the response status in the browser DevTools (Network tab) to see what Listmonk actually returns for that failure.