📋 Overview

The IC Listmonk API Integration plugin provides seamless integration between WordPress and Listmonk, the open-source newsletter and mailing list manager. This plugin enables you to:

⚙️ Requirements

WordPress Requirements

• WordPress 5.6 or higher
• PHP 7.4 or higher
• cURL enabled

Required Plugins

Listmonk Requirements

• Listmonk instance with API access
• API user with proper permissions
• Lists created in Listmonk
• Email templates (for transactional emails)

🚀 Installation

Step 1: Install the Plugin

1. Upload the plugin files to the /wp-content/plugins/ic-listmonk-api-integration directory
2. Activate the plugin through the ‘Plugins’ screen in WordPress
3. Or install directly via WordPress admin (if available in repository)

Step 2: Install Cloudflare Turnstile

1. Install and activate “Simple Cloudflare Turnstile” from WordPress.org
2. Go to Settings → Cloudflare Turnstile
3. Get free Site Key and Secret Key from Cloudflare Dashboard
4. Configure the Turnstile settings

Step 3: Configure Listmonk API User

In your Listmonk administration panel:

1. Go to Users → Create User
2. Set user type to “API”
3. Assign these permissions:

   lists:manage_all
   subscribers:get
   subscribers:get_all  
   subscribers:manage
   subscribers:sql_query
   tx:send
   templates:get

4. Generate API token and save it securely

⚙️ Configuration

Plugin Settings

Navigate to Settings → IC Listmonk API to configure:

Finding List IDs

To find your Listmonk list IDs:

1. Log into your Listmonk admin
2. Go to Lists
3. Note the ID numbers in the list table
4. Use comma-separated format: 1,2,3

Test Connection

Use the “Test API Connection” button in settings to verify your configuration.

🎯 Usage

Subscribe Form Shortcode

Unsubscribe Form Shortcode

Form Placement Examples

<div class="newsletter-widget">
<h4>Join Our Newsletter</h4>
<p>Stay updated with our latest news.</p>
[listmonk_subscribe button_text="Subscribe" show_name="no"]
</div>

<div class="subscription-page">
<h2>Subscribe to Our Mailing List</h2>
<p>Get exclusive content and updates delivered to your inbox.</p>
[listmonk_subscribe 
    button_text="Join Now" 
    placeholder="Enter your best email" 
    show_name="yes"
    show_turnstile="yes"]
</div>

<div class="footer-newsletter">
<h5>Newsletter</h5>
[listmonk_subscribe 
    button_text="→" 
    placeholder="Email" 
    show_name="no"
    show_turnstile="no"]
</div>

<div class="unsubscribe-form">
<h3>Unsubscribe from Emails</h3>
<p>We're sorry to see you go! Enter your email to unsubscribe.</p>
[listmonk_unsubscribe 
    button_text="Unsubscribe Now" 
    placeholder="Your email address"]
</div>

Custom Styling Examples

/* Custom form styling */
.listmonk-custom-form input[type="email"],
.listmonk-custom-form input[type="text"] {
    padding: 12px 15px;
    margin: 8px 0;
    width: 100%;
    max-width: 400px;
    border: 2px solid #e1e1e1;
    border-radius: 6px;
    font-size: 16px;
    transition: border-color 0.3s ease;
}

.listmonk-custom-form input:focus {
    border-color: #007cba;
    outline: none;
    box-shadow: 0 0 0 3px rgba(0, 124, 186, 0.1);
}

.listmonk-custom-form button {
    background: linear-gradient(135deg, #007cba, #005a87);
    color: white;
    padding: 12px 30px;
    border: none;
    border-radius: 6px;
    cursor: pointer;
    font-size: 16px;
    font-weight: 600;
    transition: all 0.3s ease;
}

.listmonk-custom-form button:hover {
    background: linear-gradient(135deg, #005a87, #004670);
    transform: translateY(-1px);
    box-shadow: 0 4px 12px rgba(0, 124, 186, 0.3);
}

.listmonk-custom-form button:disabled {
    background: #ccc;
    cursor: not-allowed;
    transform: none;
    box-shadow: none;
}

<style>
/* Add the CSS from above */
</style>

<div class="listmonk-custom-form">
[listmonk_subscribe 
    button_text="Subscribe Now" 
    placeholder="Your email address" 
    show_name="yes"]
</div>

🔧 Troubleshooting

Common Issues

Debug Mode

Enable debug mode in plugin settings to log detailed information:

1. Go to Settings → IC Listmonk API
2. Check “Debug Mode”
3. Check WordPress debug.log file for logs

Server Requirements Check

// Check if these functions are available:
curl_init()
json_encode()
wp_remote_post()
            

🔗 API Reference

Webhook Endpoints

The plugin provides REST API endpoints for external integrations:

AJAX Endpoints

Custom Integration Examples

<form id="custom-subscribe-form">
    <input type="email" name="email" required>
    <input type="text" name="name">
    <!-- Turnstile container -->
    <div class="cf-turnstile" data-sitekey="your-site-key"></div>
    <button type="submit">Subscribe</button>
</form>

<script>
jQuery('#custom-subscribe-form').on('submit', function(e) {
    e.preventDefault();
    
    var formData = {
        action: 'listmonk_subscribe',
        email: jQuery('input[name="email"]').val(),
        name: jQuery('input[name="name"]').val(),
        'cf-turnstile-response': jQuery('[name="cf-turnstile-response"]').val()
    };
    
    jQuery.post('', formData, function(response) {
        if (response.success) {
            alert('Subscribed successfully!');
        } else {
            alert('Error: ' + response.data);
        }
    });
});
</script>
                

💬 Support

Getting Help

If you need assistance with the IC Listmonk API Integration plugin:

Contact Information

• Website: IC Listmonk API Integration
• Support: Contact Form
• License: GPL v2 or later