← Documentation

Listmonk

Listmonk is a free and open source software that lets you send e-mail campaigns and transactional messages to millions of subscribers. The Listmonk addon allows seamless integration of WordPress contact and subscription forms with its mailing lists.

The addon

All features that are available on the listmonk dashboard are also available as REST-like HTTP APIs. All API requests are validated against an API key using the Token authentication schema.

To talk with this API, the addon works with an extension of the generic REST bridge class that requires a Token credential.

A listmonk bridge will synchronize your form submissions with your mailing list subscribers. The addon comes with a couple of templates and workflow jobs to bridge forms to your mailing lists, but you’re not tied to this options: either via templates or via manual set up, you can configure your bridges to target any API endpoint.

How to use

The first step to use the addon is to activate it on the addons table on the general settings tab.

Once activated, a new tab will be visible on the settings page. If it’s your first time, it should looks like this:

The template wizard

The recommended way to set up a new bridge is to use a template as a starter point. The addon’s template wizard will set up a new Token credential, a backend connection and a form, all of them linked on a new bridge.

With this setup ready, you can edit the bridge’s form to fit your requirements or manually add new forms and bridge them with the backend / credential you’ve configured on the previous step.

The template wizard will lead you through four steps:

1. Credential

On this step, Forms Bridge will register a new Token credential based on an API token.

To generate this authorization token you have to go to Admin > Users on your listmonk dashboard. On the users page of the admin UI, click on the + New button and create a new API user. The user requires a username. You can set it to “forms-bridge”, for example, or any other name that clearly identify it. Once created, the user’s token will be displayed on the screen.

Screenshot of the pop-up with which listmonk shows you the API token of a newly created API user.

Back on WordPress, you have to fulfill the credential step form with a unique name to identify the credential, the name of your new API user, and the value of your API token.

If you already have a Token credential registered, the template wizard allows you to reuse it. If you want to get multiple listmonk bridges, the recommended way to proceed is to register a Basic credential and reuse it on your bridges.

2. Backend

The backend step will require you to set a unique name to identify the new connection and the base URL of your listmonk server.

If you already have the listmonk registered as a backend, the template wizard allows you to reuse it. If you want to get multiple bridges, the recommended way to proceed is to register the backend once and reuse it on your bridges.

3. Form

In this step you have to choose the title of the form the template are going to create. If there is a compatible form, the wizard allows you to reuse the existing form and skip the form creation.

4. Bridge

On the last step of the wizard, you have to set a unique name for the new bridge. In addition to the name, and depending on the template you are using, this step will require more or less fields to be informed. The required fields will be marked with a red asterisk

After that, click on submit and Forms Bridge will generate the credential, backend, form and bridge setting. It only remains to publish the new form on a public page and wait for a new form submission!

Manual set up

With templates, you can save a lot of time while configuring your bridges, but you can achieve the same result with a manual set up.

A listmonk bridge will require the following components:

1. Credential

To configure the listmonk REST API as a backend, you will need to generate an authorization token going to Admin > Users on your listmonk dashboard. On the users page of the admin UI, click on the + New button and create a new API user. The user requires a name. You can set it to “forms-bridge”, for example, or any other name that clearly identify it. Once created, the user’s token will be displayed on the screen and its value should looks something like this o3I8za21bJ6CSV24OY006N2pgA6uvSLmT.

With your API token on the clipboard, go to Settings > Forms Bridge > HTTP > Authentication on your WordPress admin page and register a new authentication credential.

Select Token as the authentication schema and set your API user name as the Client ID and your API token as the Client secret. In addition, you have to choose a unique name to identify this new credential.

Screenshot with an example of a Token credential with forms-bridge as client ID and a random token as the client secret

This is an example of a Token authentication credential. In your case, the client ID and client secret will be different based on the user you’ve created.

2. Backend

To configure the listmonk REST API as a backend follow this steps:

  1. Add a new backend with a unique name (Listmonk API, for example)
  2. Set the base URL of your listmonk server as the connection URL.
  3. Select JSON as the Encoding Schema
  4. Add Accept as an HTTP header with application/json as value
  5. Select the Token credential you’ve configured on the previous step.

3. Form

Get your preferred form builder and create a new form. Once created, you can choose it as the target form to be bridged on the bridges panel of the addon. If your form fields does not match the desired API module’s layout, you can use bridge’s field mappers to rename them.

4. Bridge

The addon’s bridge is an extension of the generic REST bridge. Because of this they looks so similar. Like the REST bridge, the addon’s bridge requires a unique name, a backend, a form, an endpoint and an HTTP method.

The bridge endpoint has to exists on the listmonk REST API. To get a comprehensive list of the available endpoints you can check the official documentation. For example, to get your subscription form bridged you have to set the bridge endpoint to /api/subscribers.

The bridge allows you to use 4 HTTP methods (GET, POST, PUT, DELETE). In most cases you only want to use the POST method as it is the standard method to write entries on a system through a REST API.

Troubleshooting

To troubleshooting your bridges you can use the plugin’s debug console from the General Settings page. Enable the debug mode and submit a sample form response to see what’s going on under the hood. Take a look to our tutorial about how to use the debug console.

Common issues

  1. Authentication failures
    • Check your backend URL
    • Verify endpoint and list IDs
    • Validate your API token
  2. Missing data
    • Validate field mappings
    • Validate the API endpoint schemas

Templates

The addon comes packed with the following templates:

  • Opt-in Subscriptions 🔎
    Subscription form template. The resulting bridge will convert form submissions into new list subscriptions with a double opt-in confirmation check.

  • Subscriptions 🔎
    Subscription form template. The resulting bridge will convert form submissions into new list subscriptions.

  • Opt-in Subscriptions 🔎
    Subscription form template. The resulting bridge will subscribe woocommerce customers to a given email list with a double opt in check.

  • Subscriptions 🔎
    Subscription form template. The resulting bridge will subscribe woocommerce customers to a given email list.

Workflow jobs

The addon comes packed with the following workflow jobs:

Supported form builders

Contact Form 7
WP Forms
Gravity Forms
Ninja Forms

Tutorials

  • Subscribe WooCommerce customers to listmonk

    In this tutorial we will explain how to bridge your WooCommerce orders to Listmonk. The resulting bridge will subscribe new customers from WooCommerce to our mailing lists.