How it works
Knowing what the client does on your behalf explains most of its behaviour, including the parts that look surprising at first.
One module, one instance
listmonk keeps its configuration in four module-level variables: the base URL, the username, the password, and a logged-in flag. set_url_base() sets the first, login() sets the rest after validating the credentials against the health endpoint, and every other function checks the flag before doing anything and raises OperationNotAllowedError if it is not set.
Two consequences follow. A process talks to one Listmonk instance at a time; to switch, call set_url_base() and login() again, and the new credentials are re-validated rather than trusted. And changing credentials is not thread-safe: do the configuration once at startup, before worker threads start, and leave it alone. Reads from worker threads are fine, since the variables never change after that.
Every call is a fresh request
The client uses httpx2’s module-level functions (httpx2.get(), httpx2.post(), and so on) rather than a long-lived Client. Each call opens its own connection, sends HTTP Basic auth built from the stored credentials, follows redirects, identifies itself with a User-Agent of the form Listmonk-Client v0.7.33 / Python 3.14.0 / Darwin, and times out after 10 seconds unless you pass timeout_config. There is no connection pooling and no session state, which is why a fake server for tests only needs to patch those four functions.
The trade-off is a little more latency per call. For a handful of calls per request in a web app it is unnoticeable; for a loop over tens of thousands of subscribers, batch where the API allows it (add_subscribers_to_lists() takes many IDs at once) and pull data in bulk with subscribers() rather than one lookup at a time.
Pagination
subscribers() asks for 500 records per page and keeps going until the server’s total is reached, so one call can be several requests. lists(), campaigns(), and templates() ask for one very large page and make a single request.
Lookups by email and UUID are SQL filters
Listmonk has a direct endpoint for fetching a subscriber by ID, and subscriber_by_id() uses it. It has no direct endpoint for email or UUID, so subscriber_by_email() and subscriber_by_uuid() send a query parameter that Listmonk runs as a SQL expression inside a read-only transaction. That is why those two need the subscribers:sql_query permission, and why the client quotes the value as a SQL literal with embedded quotes escaped before sending it.
Models
Responses are parsed into Pydantic models in listmonk.models: Subscriber, MailingList, Campaign, Template, and Media, plus the enums SubscriberStatuses and CampaignStatuses. Fields the server may omit are Optional. Timestamps are datetime objects.
The update functions do not send those response models back as-is. update_subscriber() builds a CreateSubscriberModel from the fields Listmonk’s PUT accepts, update_campaign() builds an UpdateCampaignModel (which is where a past send_at gets dropped), and update_template() builds a CreateTemplateModel. Those request models are public too, in case you want to see exactly what goes over the wire.
Response validation
Every JSON call runs the response through one helper: raise httpx2.HTTPStatusError for a 4xx or 5xx, raise ValidationError for an empty body or a body that is not JSON, otherwise hand back the parsed dict. Previews are the exception, since Listmonk returns them as raw HTML.
What the client does not cover
Listmonk’s API is larger than this client. Not wrapped, as of this version: campaign analytics, campaign archives, bounces, bulk subscriber deletion and blocklisting by query, listing and deleting media, importing subscribers from files, settings, and user management. Transactional sends by subscriber ID (rather than email) are also not exposed. For any of those, call the Listmonk API directly with httpx2 and the same Basic auth; the base URL and credentials you gave the client are available as listmonk.get_base_url() and the username and password attributes of listmonk.impl.
An async variant is planned but not yet implemented. With httpx2 underneath, the shape of it is clear; it is a matter of doing the work.
Version and user agent
listmonk.__version__ reports the installed package version, read from the package metadata, and listmonk.user_agent is the string sent with every request.