WP Listmonk Bridge

Professional WordPress plugin for seamless Listmonk newsletter integration

Overview

WP Listmonk Bridge is a comprehensive WordPress plugin that acts as a "Command Center" for your self-hosted Listmonk installation. Manage lists, subscribers, campaigns, and analytics directly from your WordPress dashboard—no need to log into Listmonk separately.

Features

🎯 Core Features

• Full Bi-Directional Sync - Automatic synchronization between WordPress users and Listmonk subscribers
• List Management - View and manage Listmonk lists from WordPress admin
• Analytics Dashboard - Visual charts powered by Chart.js showing campaign statistics
• Subscriber Management - Manage subscribers and their list assignments

🌐 Frontend Features

• Subscription Forms - Shortcodes and Gutenberg blocks for easy embedding
• Double Opt-in - GDPR-compliant email confirmation flow
• Customizable Design - Modern, responsive form styling

🛒 WooCommerce Integration

• Auto-Subscribe Customers - Add customers to lists at checkout
• Product-Specific Lists - Different products subscribe to different lists
• Customer Segmentation - Target customers based on purchase behavior

⚡ Advanced Features

• Webhook Support - Real-time sync from Listmonk events
• CSV Import/Export - Bulk subscriber management
• Transient Caching - Optimized API performance
• Comprehensive Logging - Debug mode for troubleshooting

Installation

Simple Upload Method (Recommended for End Users)

No technical knowledge required!

1. Download the plugin folder as a ZIP file
2. Go to WordPress Admin > Plugins > Add New
3. Click "Upload Plugin" button
4. Choose the ZIP file and click "Install Now"
5. Click "Activate Plugin"
6. Go to Listmonk > Settings and enter your API credentials

That's it! All dependencies are included.

Manual Installation

1. Upload the plugin files to /wp-content/plugins/wp-listmonk-bridge/
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Configure at Listmonk > Settings

For Developers

The plugin uses standard WordPress Cron for scheduling. Action Scheduler is optional and used if available.

If you want to update dependencies:

cd wp-content/plugins/wp-listmonk-bridge
composer update --no-dev

Configuration

1. API Setup

Navigate to Listmonk > Settings in WordPress admin:

• API URL: Your Listmonk installation URL (e.g., https://listmonk.example.com)
• Username: Listmonk admin username
• Password: Listmonk admin password

Click Test Connection to verify credentials.

2. Sync Settings

Configure automatic synchronization:

• ✅ Sync on Registration: Auto-create subscribers when users register
• ✅ Sync on Profile Update: Update subscriber info when users edit profiles
• Default List: Choose which list new subscribers join
• Subscriber Status: Set default status (enabled/blocklisted)

3. Webhook Configuration

For real-time sync from Listmonk to WordPress:

1. Copy the Webhook URL from settings
2. In Listmonk admin, go to Settings > Webhooks
3. Add the URL and configure events

4. WooCommerce (Optional)

If WooCommerce is installed:

• Enable integration
• Select customer list
• Configure checkout checkbox

Usage

Shortcodes

Subscription Form:

[listmonk_subscribe list_id="1" title="Subscribe to Newsletter" button_text="Subscribe"]

With Custom Styling:

[listmonk_subscribe list_id="1" show_name="yes" class="my-custom-class"]

Unsubscribe Form:

[listmonk_unsubscribe]

Gutenberg Block

Search for "Listmonk Subscription" in the block inserter. Customize:

• List ID
• Title & description
• Button text
• Show/hide name field

PHP Functions

// Get subscriber manager
$manager = WPLM()->subscribers;

// Sync a specific user
$manager->create_or_update_subscriber($user_id, [1, 2]); // List IDs

// Get Listmonk API instance
$api = WPLM_Listmonk_API::instance();

// Get all lists
$lists = $api->get_lists();

// Create campaign
$campaign_manager = WPLM()->campaigns;
$campaign_manager->create_campaign([
    'name' => 'My Campaign',
    'subject' => 'Newsletter',
    'lists' => [1],
    'body' => '<h1>Hello!</h1>'
]);

Architecture

File Structure

wp-listmonk-bridge/
├── wp-listmonk-bridge.php       # Main plugin file
├── includes/
│   ├── class-listmonk-api.php   # API handler (Singleton)
│   ├── class-subscriber-manager.php
│   ├── class-campaign-manager.php
│   ├── class-admin-ui.php
│   ├── class-activator.php
│   ├── class-webhook-handler.php
│   ├── class-import-export.php
│   ├── class-shortcodes.php
│   ├── class-blocks.php
│   └── class-woocommerce-integration.php
├── templates/                   # Admin page views
│   ├── dashboard.php
│   ├── settings.php
│   └── frontend/
│       └── subscription-form.php
├── assets/
│   ├── css/
│   └── js/
└── vendor/                      # Composer dependencies
    └── action-scheduler/

Class Hierarchy

• WP_Listmonk_Bridge (Main plugin class, Singleton)
  • WPLM_Listmonk_API (API handler, Singleton)
  • WPLM_Subscriber_Manager (User sync)
  • WPLM_Campaign_Manager (Campaign scheduling)
  • WPLM_Admin_UI (Admin interface)
  • WPLM_Webhook_Handler (Real-time sync)
  • WPLM_Import_Export (CSV tools)
  • WPLM_Shortcodes (Frontend forms)
  • WPLM_Blocks (Gutenberg)
  • WPLM_WooCommerce_Integration (Conditional)

API Reference

Main Plugin Instance

WPLM() // Returns main plugin instance

API Methods

$api = WPLM_Listmonk_API::instance();

// Lists
$api->get_lists();
$api->create_list($data);
$api->update_list($id, $data);
$api->delete_list($id);

// Subscribers
$api->get_subscribers($args);
$api->get_subscriber($id);
$api->create_subscriber($data);
$api->update_subscriber($id, $data);
$api->update_subscriber_lists($id, $list_ids);

// Campaigns
$api->get_campaigns($args);
$api->create_campaign($data);
$api->update_campaign_status($id, $status);

Hooks

Actions:

do_action('wplm_init'); // After plugin initialization
do_action('wplm_subscriber_created', $subscriber, $user);
do_action('wplm_subscriber_updated', $subscriber, $user);
do_action('wplm_campaign_sent', $campaign);

Filters:

apply_filters('wplm_subscriber_data', $data, $user_id);
apply_filters('wplm_campaign_data', $data);

Requirements

• PHP: 7.4 or higher
• WordPress: 5.8 or higher
• Listmonk: Any version with API enabled
• Composer: For installing dependencies

Security

• All form submissions use nonce verification
• Input sanitization with WordPress functions
• Output escaping (esc_html, esc_attr, esc_url)
• Capability checks on all admin pages
• No direct SQL queries (uses WordPress functions)
• HTTP requests via wp_remote_request()

Performance

• Transient Caching: 1-hour cache for API responses
• Batch Operations: Bulk user sync with rate limiting
• Action Scheduler: Reliable background processing for campaigns
• Conditional Loading: WooCommerce features only load when needed

Troubleshooting

Connection Issues

1. Verify API credentials in settings
2. Check Listmonk API is accessible from WordPress server
3. Enable debug logging in Advanced settings
4. Review PHP error logs for API errors

Sync Problems

• Ensure default list is configured
• Check user has valid email address
• Verify Listmonk lists exist
• Review sync logs in debug mode

Campaign Not Sending

• Check Action Scheduler queue: Tools > Scheduled Actions
• Verify campaign status in Listmonk admin
• Ensure lists have active subscribers

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Follow WordPress coding standards
4. Add PHPDoc comments
5. Test thoroughly
6. Submit pull request

License

GPL v2 or later - https://www.gnu.org/licenses/gpl-2.0.html

Support

• Issues: Create an issue on GitHub
• Documentation: See /docs folder
• Email: safwan.naqvi@gmail.com

Credits

Developed for the WordPress and Listmonk communities.

Special thanks to:

• Listmonk team for the excellent newsletter platform
• Action Scheduler for reliable task scheduling
• Chart.js for beautiful data visualizations

---

Made with ❤️ for WordPress