API Reference

The full listmonk client API: configuration, list/subscriber/campaign/template management, and transactional email.

Configuration & Authentication

Point the client at your Listmonk instance and authenticate.

set_url_base(): Set the base URL of your Listmonk instance for all subsequent calls.
get_base_url(): Return the configured base URL of your Listmonk instance.
login(): Log into Listmonk and cache the credentials for the life of your app.
verify_login(): Verify that the stored login credentials are still valid at the server.
is_healthy(): Check whether the server is reachable and the stored credentials are valid.

Read and manage mailing lists.

Create, query, update, and manage the status of subscribers.

subscribers(): Get the list of subscribers matching the given criteria, or all subscribers if no criteria are given.
subscriber_by_email(): Retrieve a single subscriber by their email address (e.g. “some_user@talkpython.fm”).
subscriber_by_id(): Retrieve a single subscriber by their numeric Listmonk ID (e.g. 201).
subscriber_by_uuid(): Retrieve a single subscriber by their UUID (e.g. “c37786af-e6ab-4260-9b49-740adpcm6ed”).
create_subscriber(): Create a new subscriber on the Listmonk server.
update_subscriber(): Update many aspects of a subscriber: email and name, custom attribute data, list membership, and status.
add_subscribers_to_lists(): Add a number of subscribers to a number of lists in a single bulk operation.
enable_subscriber(): Set a subscriber’s status to enabled so they will receive campaigns.
disable_subscriber(): Set a subscriber’s status to disabled, pausing their subscription so they will not receive campaigns.
block_subscriber(): Add a subscriber to the blocklist, effectively unsubscribing them so they will not receive any mail.
confirm_optin(): Confirm a subscriber’s opt-in to a list via the API.
delete_subscriber(): Completely delete a subscriber from your system (as if they were never there).

Create, preview, update, and delete email campaigns.

campaigns(): Get all campaigns on the server.
campaign_by_id(): Get the full details of a campaign with the given ID.
campaign_preview_by_id(): Get the rendered preview of a campaign with the given ID.
create_campaign(): Create a new campaign with the given parameters.
update_campaign(): Update an existing campaign with the provided campaign information.
delete_campaign(): Completely delete a campaign from your system.

Manage email templates and set the default.

templates(): Retrieve all templates defined on the Listmonk instance.
template_by_id(): Retrieve a single template by its numeric ID.
template_preview_by_id(): Render and return a preview of a template.
create_template(): Create a new template on the Listmonk instance.
update_template(): Update an existing template on the Listmonk instance.
set_default_template(): Mark the given template as the default for its type.
delete_template(): Permanently delete a template from the Listmonk instance.

Send one-off transactional messages.

send_transactional_email(): Send a transactional email through Listmonk to a single recipient.

Pydantic models returned by and passed to the API functions.

models.MailingList: A mailing list on the Listmonk instance.
models.SubscriberStatus: A breakdown of subscriber counts by subscription status for a mailing list.
models.SubscriberStatuses: The subscription status of a subscriber within a given mailing list.
models.Subscriber: A subscriber (contact) on the Listmonk instance.
models.CreateSubscriberModel: The payload used to create a new subscriber.
models.Campaign: An email campaign on the Listmonk instance.
models.CreateCampaignModel: The payload used to create a new campaign.
models.UpdateCampaignModel: The payload used to update an existing campaign.
models.CampaignPreview: A rendered preview of a campaign.
models.Template: An email template on the Listmonk instance.
models.CreateTemplateModel: The payload used to create a new template.
models.TemplatePreview: A rendered preview of a template.

Errors raised by the client.

errors.ValidationError: Raised when an argument fails client-side validation before a request is sent.
errors.OperationNotAllowedError: Raised when an operation is not permitted in the client’s current state.
errors.ListmonkFileNotFoundError: Raised when a local file referenced for upload (e.g. a transactional email attachment) cannot be found.