README

Implementation of the Listmonk API in PHP. It requires PHP >= 7.4.

A clean, object-oriented PHP client for the Listmonk API.

This package provides a structured and model-driven way to interact with a Listmonk instance, including:

Subscriber management
List management
Campaign management
Pagination handling
Strongly typed models

It wraps the Listmonk REST API into dedicated services and models for predictable and maintainable usage.

Installation

Install via Composer:

composer require ucscode/php-listmonk

Configuration

Initialize the API client with your Listmonk API URL and credentials:

use Junisan\ListmonkApi\API\ListmonkPHP;

$api = new ListmonkPHP('https://listmonk-domain.com/api', [
    'username' => 'api-username',
    'password' => 'api-token',
]);

Available Services

The client exposes three API services:

$subscriberApi = $api->getSubscribersApi();
$listApi       = $api->getListsApi();
$campaignApi   = $api->getCampaignsApi();

Each service contains methods specific to its domain.

Subscriber API

Create Subscriber

use Junisan\ListmonkApi\Models\SubscriberModel;
use Junisan\ListmonkApi\Models\SubscriberAttributesModel;

$model = (new SubscriberModel())
    ->setName('Example')
    ->setEmail('email@example.com')
    ->setStatus('enabled') // enabled, disabled, etc.
    ->setLists([]) // optional: list IDs
    ->setAttributes(new SubscriberAttributesModel()); // optional

$subscriber = $subscriberApi->createSubscriber($model);

Returns a SubscriberModel with populated id and uuid if successful.

You may optionally pass:

$subscriberApi->createSubscriber($model, true); // preconfirmed subscriptions

Get Subscriber

By Email:

$subscriber = $subscriberApi->getSubscriberByEmail('email@example.com');

By ID:

$subscriber = $subscriberApi->getSubscriberById(1);

Get All Subscribers (Paginated)

$paginator = $subscriberApi->getAllSubscriber(1, 100);

$subscribers = $paginator->getResults();
$total       = $paginator->getTotal();

Returns a PaginatorModel.

List API

Create List

use Junisan\ListmonkApi\Models\ListModel;

$list = (new ListModel())
    ->setName('Newsletter')
    ->setDescription('Main newsletter list')
    ->setIsPublic(true)
    ->setOptinSingle(true)
    ->setIsActive(true)
    ->setTags(['marketing', 'weekly']);

$createdList = $listApi->createList($list);

Returns a ListModel with id and uuid.

Get Lists

Get all lists:

$paginator = $listApi->getAllLists(1, 100);

Get list by ID:

$list = $listApi->getListById(1);

Campaign API

Create Campaign

use Junisan\ListmonkApi\Models\CampaignModel;

$campaign = (new CampaignModel())
    ->setName('January Campaign')
    ->setSubject('Welcome to our newsletter')
    ->setBody('<h1>Hello World</h1>')
    ->setType('regular')
    ->setContentType('html')
    ->setStatus('draft')
    ->setListIds([1, 2])
    ->setTags(['monthly']);

$createdCampaign = $campaignApi->createCampaign($campaign);

Get Campaigns

$paginator = $campaignApi->getAllCampaigns(1, 100);

Get single campaign:

$campaign = $campaignApi->getCampaignById(1);

Change Campaign Status

$updated = $campaignApi->changeCampaignStatus(1, 'running');

Common statuses:

draft
scheduled
running
paused
cancelled

Preview Campaign

$htmlPreview = $campaignApi->previewCampaign(1);

Returns rendered HTML preview or null.

Models Overview

CampaignModel

Represents a Listmonk campaign.

Includes:

Basic data (status, name, subject, body)
Target lists (listIds)
Tags
Scheduling (sendAt)
Advanced fields (templateId, fromEmail, etc.)
Statistics (views, clicks, bounces)

ListModel

Represents a subscriber list.

Key properties:

name
description
isPublic
optinSingle
isActive
tags

SubscriberModel

Represents a subscriber.