listmonk 0.1.0__tar.gz

listmonk-0.1.0/.gitignore

@@ -0,0 +1,161 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+settings.json

listmonk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Michael Kennedy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

listmonk-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.1
+Name: listmonk
+Version: 0.1.0
+Summary: Listmonk Email App API Client for Python
+Project-URL: Homepage, https://github.com/mikeckennedy/listmonk
+Project-URL: Tracker, https://github.com/mikeckennedy/listmonk/issues
+Project-URL: Source, https://github.com/mikeckennedy/listmonk
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,email,marketing,newsletters
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Description-Content-Type: text/markdown
+
+# Listmonk Email App API Client for Python
+
+Client for the for open source, self-hosted [Listmonk email platform](https://listmonk.app) based on 
+[httpx](https://www.python-httpx.org) and [pydantic](https://pydantic.dev).  
+
+`listmonk` is intended for integrating your Listmonk instance into your web app. The [Listmonk API is extensive](https://listmonk.app/docs/apis/apis/) but this only covers the subset that most developers will need for common SaaS actions such as subscribe, unsubscribe, and segmentate users (into separate lists).
+
+So while it doesn't currently cover every endpoint (for example you cannot create a list programatically nor can you edit HTML templates for campaigns over APIs) it will likely work for you. That said, PRs are weclome.
+
+🔀 Async is currently planned but not yet implemented. With the httpx-base, it should be trivial if needed.
+
+## Core Features
+
+* ➕**Add a subscriber** to your subscribed users. 
+* 🙎 Get **subscriber details** by email, ID, UUID, and more.
+* 📝 **Modify subscriber details** (including custom attribute collection).
+* 🔍 **Search** your users based on app and custom attributes.
+* 🏥 Check the **health and connectivity** of your instance.
+*  👥 Retrieve your **segmentation lists**,  list details, and subscribers.
+* 🙅 Unsubscribe and block users who don't want  to be contacted further.
+* 💥 Completely delete a subscriber from your instance.
+* 📧 Send transactional email with template data (i.e. password reset emails).
+
+## Installation
+
+Just `pip install listmonk`
+
+
+## Usage
+
+```python
+
+import listmonk
+listmonk.set_url_base('https://yourlistmonkurl.com')
+
+listmonk.login('sammyz', '1234')
+valid: bool = listmonk.verify_login()
+
+# Is it alive and working?
+up: bool = listmonk.is_healthy()
+
+# Read data about your lists
+lists: list[] = listmonk.lists()
+list: MailingList = listmonk.list(list_id=7)
+
+# Various ways to access existing subscribers
+subscribers: list[] = listmonk.subscribers(list_id=9)
+
+subscriber: Subscriber = listmonk.subscriber_by_email('testuser@some.domain')
+subscriber: Subscriber = listmonk.subscriber_by_id(2001)
+subscriber: Subscriber = listmonk.subscriber_by_uuid('f6668cf0-1c...')
+
+# Create a new subscriber
+new_subscriber = listmonk.create_subscriber(
+           'testuser@some.domain', 'Jane Doe',
+           [1, 7, 9], pre_confirm=True, attribs={...} )
+
+# Change the email, custom rating, and add to lists 4 & 6, remove from 5.
+subscriber.email = 'newemail@some.domain'
+subscriber.attribs['rating'] = 7
+updated_subscriber = listmonk.update_subscriber(new_subscriber, {4, 6}, {5})
+
+# Disable then re-enable a subscriber
+subscriber = listmonk.disable_subscriber(subscriber)
+subscriber = listmonk.enable_subscriber(subscriber)
+
+# Block (unsubscribe) them
+listmonk.block_subscriber(subscriber)
+
+# Fully delete them from your system
+listmonk.delete_subscriber(subscriber.email)
+
+# Send an individual, transacational email (e.g. password reset)
+to_email = 'testuser@some.domain'
+from_email = 'app@your.domain'
+template_id = 3  # *TX* template ID from listmonk
+template_data = {'full_name': 'Test User', 'reset_code': 'abc123'}
+
+status: bool = listmonk.send_transactional_email(
+                     to_email, template_id, from_email=from_email, 
+                     template_data=template_data, content_type='html')
+```
+
+
+
+## Want to contribute?
+
+PRs are welcome. Enjoy.

listmonk-0.1.0/README.md

@@ -0,0 +1,88 @@
+# Listmonk Email App API Client for Python
+
+Client for the for open source, self-hosted [Listmonk email platform](https://listmonk.app) based on 
+[httpx](https://www.python-httpx.org) and [pydantic](https://pydantic.dev).  
+
+`listmonk` is intended for integrating your Listmonk instance into your web app. The [Listmonk API is extensive](https://listmonk.app/docs/apis/apis/) but this only covers the subset that most developers will need for common SaaS actions such as subscribe, unsubscribe, and segmentate users (into separate lists).
+
+So while it doesn't currently cover every endpoint (for example you cannot create a list programatically nor can you edit HTML templates for campaigns over APIs) it will likely work for you. That said, PRs are weclome.
+
+🔀 Async is currently planned but not yet implemented. With the httpx-base, it should be trivial if needed.
+
+## Core Features
+
+* ➕**Add a subscriber** to your subscribed users. 
+* 🙎 Get **subscriber details** by email, ID, UUID, and more.
+* 📝 **Modify subscriber details** (including custom attribute collection).
+* 🔍 **Search** your users based on app and custom attributes.
+* 🏥 Check the **health and connectivity** of your instance.
+*  👥 Retrieve your **segmentation lists**,  list details, and subscribers.
+* 🙅 Unsubscribe and block users who don't want  to be contacted further.
+* 💥 Completely delete a subscriber from your instance.
+* 📧 Send transactional email with template data (i.e. password reset emails).
+
+## Installation
+
+Just `pip install listmonk`
+
+
+## Usage
+
+```python
+
+import listmonk
+listmonk.set_url_base('https://yourlistmonkurl.com')
+
+listmonk.login('sammyz', '1234')
+valid: bool = listmonk.verify_login()
+
+# Is it alive and working?
+up: bool = listmonk.is_healthy()
+
+# Read data about your lists
+lists: list[] = listmonk.lists()
+list: MailingList = listmonk.list(list_id=7)
+
+# Various ways to access existing subscribers
+subscribers: list[] = listmonk.subscribers(list_id=9)
+
+subscriber: Subscriber = listmonk.subscriber_by_email('testuser@some.domain')
+subscriber: Subscriber = listmonk.subscriber_by_id(2001)
+subscriber: Subscriber = listmonk.subscriber_by_uuid('f6668cf0-1c...')
+
+# Create a new subscriber
+new_subscriber = listmonk.create_subscriber(
+           'testuser@some.domain', 'Jane Doe',
+           [1, 7, 9], pre_confirm=True, attribs={...} )
+
+# Change the email, custom rating, and add to lists 4 & 6, remove from 5.
+subscriber.email = 'newemail@some.domain'
+subscriber.attribs['rating'] = 7
+updated_subscriber = listmonk.update_subscriber(new_subscriber, {4, 6}, {5})
+
+# Disable then re-enable a subscriber
+subscriber = listmonk.disable_subscriber(subscriber)
+subscriber = listmonk.enable_subscriber(subscriber)
+
+# Block (unsubscribe) them
+listmonk.block_subscriber(subscriber)
+
+# Fully delete them from your system
+listmonk.delete_subscriber(subscriber.email)
+
+# Send an individual, transacational email (e.g. password reset)
+to_email = 'testuser@some.domain'
+from_email = 'app@your.domain'
+template_id = 3  # *TX* template ID from listmonk
+template_data = {'full_name': 'Test User', 'reset_code': 'abc123'}
+
+status: bool = listmonk.send_transactional_email(
+                     to_email, template_id, from_email=from_email, 
+                     template_data=template_data, content_type='html')
+```
+
+
+
+## Want to contribute?
+
+PRs are welcome. Enjoy.

listmonk-0.1.0/listmonk/__init__.py

@@ -0,0 +1,26 @@
+from listmonk import impl
+from listmonk import models  # noqa: F401, E402
+from listmonk.impl import create_subscriber, delete_subscriber, update_subscriber  # noqa: F401, E402
+from listmonk.impl import disable_subscriber, enable_subscriber, block_subscriber  # noqa: F401, E402
+from listmonk.impl import is_healthy  # noqa: F401, E402
+from listmonk.impl import lists, list_by_id  # noqa: F401, E402
+from listmonk.impl import login, verify_login  # noqa: F401, E402
+from listmonk.impl import send_transactional_email  # noqa: F401, E402
+from listmonk.impl import set_url_base, get_base_url  # noqa: F401, E402
+from listmonk.impl import subscribers, subscriber_by_email, subscriber_by_id, subscriber_by_uuid  # noqa: F401, E402
+
+__author__ = 'Michael Kennedy <michael@talkpython.fm>'
+__version__ = impl.__version__
+user_agent = impl.user_agent
+
+__all__ = [
+    models,
+    login, verify_login,
+    set_url_base, get_base_url,
+    lists, list_by_id,
+    subscribers, subscriber_by_email, subscriber_by_id, subscriber_by_uuid,
+    create_subscriber, delete_subscriber, update_subscriber,
+    disable_subscriber, enable_subscriber, block_subscriber,
+    send_transactional_email,
+    is_healthy,
+]

listmonk-0.1.0/listmonk/impl/__init__.py

@@ -0,0 +1,416 @@
+import sys
+import urllib.parse
+from base64 import b64encode
+from typing import Optional, Tuple
+
+import httpx
+
+from listmonk import models, urls  # noqa: F401
+
+__version__ = '0.1.0'
+
+from listmonk.models import SubscriberStatuses
+
+# region global vars
+url_base: Optional[str] = None
+username: Optional[str] = None
+password: Optional[str] = None
+
+user_agent = (f'Listmonk-Client v{__version__} / '
+              f'Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro} / '
+              f'{sys.platform.capitalize()}')
+
+core_headers: dict[str, Optional[str]] = {
+    'Authorization': None,  # Set at login
+    'Content-Type': 'application/json',
+    'User-Agent': user_agent,
+}
+
+
+# endregion
+
+# region def get_base_url() -> Optional[str]
+
+def get_base_url() -> Optional[str]:
+    return url_base
+
+
+# endregion
+
+# region def set_url_base(url: str)
+
+def set_url_base(url: str):
+    if not url or not url.strip():
+        raise Exception("URL must not be empty")
+
+    global url_base
+    url_base = url.strip()
+
+
+# endregion
+
+# region def login(user_name: str, pw: str)
+
+def login(user_name: str, pw: str):
+    global core_headers, username, password
+
+    validate_login(user_name, pw)
+    username = user_name
+    password = pw
+
+    user_pass = f'{user_name}:{pw}'.encode()
+    user_pass_encoded = b64encode(user_pass).decode()
+
+    core_headers['Authorization'] = f'Basic {user_pass_encoded}'
+    if not verify_login():
+        core_headers['Authorization'] = None
+        return False
+
+    return True
+
+
+# endregion
+
+# region def lists() -> list[models.MailingList]
+
+def lists() -> list[models.MailingList]:
+    global core_headers
+    validate_state(url=True, user=True)
+
+    url = f'{url_base}{urls.lists}?page=1&per_page=1000000'
+    resp = httpx.get(url, headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    data = resp.json()
+    list_of_lists = [models.MailingList(**d) for d in data.get('data', {}).get('results', [])]
+    return list_of_lists
+
+
+# endregion
+
+# region def list_by_id(list_id: int) -> Optional[models.MailingList]
+
+def list_by_id(list_id: int) -> Optional[models.MailingList]:
+    global core_headers
+    validate_state(url=True, user=True)
+
+    url = f'{url_base}{urls.lst}'
+    url = url.format(list_id=list_id)
+
+    resp = httpx.get(url, headers=core_headers, follow_redirects=True, timeout=30)
+    resp.raise_for_status()
+
+    data = resp.json()
+    lst_data = data.get('data')
+    return models.MailingList(**lst_data)
+
+
+# endregion
+
+# region def subscribers(query_text: Optional[str] = None, list_id: Optional[int] = None) -> list[models.Subscriber]
+
+def subscribers(query_text: Optional[str] = None, list_id: Optional[int] = None) -> list[models.Subscriber]:
+    global core_headers
+    validate_state(url=True, user=True)
+
+    raw_results = []
+    page_num = 1
+    partial_results, more = _fragment_of_subscribers(page_num, list_id, query_text)
+    raw_results.extend(partial_results)
+    print(f"subscribers(): Got {len(raw_results)} so far, more? {more}")
+    while more:
+        page_num += 1
+        partial_results, more = _fragment_of_subscribers(page_num, list_id, query_text)
+        raw_results.extend(partial_results)
+        print(f"subscribers(): Got {len(raw_results)} so far on page {page_num}, more? {more}")
+
+    subscriber_list = [models.Subscriber(**d) for d in raw_results]
+
+    return subscriber_list
+
+
+# endregion
+
+# region def _fragment_of_subscribers(page_num: int, list_id: Optional[int], query_text: Optional[str])
+
+def _fragment_of_subscribers(page_num: int, list_id: Optional[int], query_text: Optional[str]) \
+        -> Tuple[list[dict], bool]:
+    """
+    Returns:
+        Tuple of partial_results, more_to_retrieve
+    """
+    per_page = 500
+
+    url = f'{url_base}{urls.subscribers}?page={page_num}&per_page={per_page}&order_by=updated_at&order=DESC'
+
+    if list_id:
+        url += f'&list_id={list_id}'
+
+    if query_text:
+        url += f"&query={urllib.parse.urlencode({'query': query_text})}"
+
+    resp = httpx.get(url, headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    # For paging:
+    # data: {"total":55712,"per_page":10,"page":1, ...}
+    raw_data = resp.json()
+    data = raw_data['data']
+
+    total = data.get('total', 0)
+    retrieved = per_page * page_num
+    more = retrieved < total
+
+    local_results = data.get('results', [])
+    return local_results, more
+
+
+# endregion
+
+# region def subscriber_by_email(email: str) -> Optional[models.Subscriber]
+
+def subscriber_by_email(email: str) -> Optional[models.Subscriber]:
+    global core_headers
+    validate_state(url=True, user=True)
+
+    url = f"{url_base}{urls.subscribers}?page=1&per_page=100&query=subscribers.email='{email}'"
+
+    resp = httpx.get(url, headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    raw_data = resp.json()
+    results: list[dict] = raw_data['data']['results']
+
+    if not results:
+        return None
+
+    return models.Subscriber(**results[0])
+
+
+# endregion
+
+# region def subscriber_by_id(subscriber_id: int) -> Optional[models.Subscriber]
+
+def subscriber_by_id(subscriber_id: int) -> Optional[models.Subscriber]:
+    global core_headers
+    validate_state(url=True, user=True)
+
+    url = f"{url_base}{urls.subscribers}?page=1&per_page=100&query=subscribers.id={subscriber_id}"
+
+    resp = httpx.get(url, headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    raw_data = resp.json()
+    results: list[dict] = raw_data['data']['results']
+
+    if not results:
+        return None
+
+    return models.Subscriber(**results[0])
+
+
+# endregion
+
+# region subscriber_by_uuid(subscriber_uuid: str) -> Optional[models.Subscriber]
+
+def subscriber_by_uuid(subscriber_uuid: str) -> Optional[models.Subscriber]:
+    global core_headers
+    validate_state(url=True, user=True)
+
+    url = f"{url_base}{urls.subscribers}?page=1&per_page=100&query=subscribers.uuid='{subscriber_uuid}'"
+
+    resp = httpx.get(url, headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    raw_data = resp.json()
+    results: list[dict] = raw_data['data']['results']
+
+    if not results:
+        return None
+
+    return models.Subscriber(**results[0])
+
+
+# endregion
+
+# region def create_subscriber(email: str, name: str, list_ids: list[int], pre_confirm: bool, attribs: dict)
+# -> models.Subscriber
+
+def create_subscriber(email: str, name: str, list_ids: list[int],
+                      pre_confirm: bool, attribs: dict) -> models.Subscriber:
+    global core_headers
+    validate_state(url=True, user=True)
+    email = (email or '').lower().strip()
+    name = (name or '').strip()
+    if not email:
+        raise ValueError("Email is required")
+    if not name:
+        raise ValueError("Name is required")
+
+    model = models.CreateSubscriberModel(email=email, name=name, status='enabled', lists=list_ids,
+                                         preconfirm_subscriptions=pre_confirm, attribs=attribs)
+
+    url = f"{url_base}{urls.subscribers}"
+    resp = httpx.post(url, json=model.model_dump(), headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    raw_data = resp.json()
+    # pprint(raw_data)
+    sub_data = raw_data['data']
+    return models.Subscriber(**sub_data)
+
+
+# endregion
+
+# region def delete_subscriber(email: Optional[str] = None, overriding_subscriber_id: Optional[int] = None) -> bool
+
+def delete_subscriber(email: Optional[str] = None, overriding_subscriber_id: Optional[int] = None) -> bool:
+    global core_headers
+    validate_state(url=True, user=True)
+    email = (email or '').lower().strip()
+    if not email and not overriding_subscriber_id:
+        raise ValueError("Email is required")
+
+    subscriber_id = overriding_subscriber_id
+    if not subscriber_id:
+        subscriber = subscriber_by_email(email)
+        if not subscriber:
+            return False
+        subscriber_id = subscriber.id
+
+    url = f"{url_base}{urls.subscriber.format(subscriber_id=subscriber_id)}"
+    resp = httpx.delete(url, headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    raw_data = resp.json()
+    return raw_data.get('data')  # {'data': True}
+
+
+# endregion
+
+# region def update_subscriber(subscriber: models.Subscriber, add_to_lists: set[int], remove_from_lists: set[int])
+
+def update_subscriber(subscriber: models.Subscriber, add_to_lists: set[int] = None, remove_from_lists: set[int] = None,
+                      status: SubscriberStatuses = SubscriberStatuses.enabled) -> models.Subscriber:
+    global core_headers
+    validate_state(url=True, user=True)
+    if subscriber is None or not subscriber.id:
+        raise ValueError("Subscriber is required")
+
+    add_to_lists = add_to_lists or set()
+    remove_from_lists = remove_from_lists or set()
+
+    existing_lists = set([int(lst.get('id')) for lst in subscriber.lists])
+    final_lists = (existing_lists - remove_from_lists)
+    final_lists.update(add_to_lists)
+
+    update_model = models.CreateSubscriberModel(
+        email=subscriber.email,
+        name=subscriber.name,
+        status=status,
+        lists=list(final_lists),
+        preconfirm_subscriptions=True,
+        attribs=subscriber.attribs
+    )
+
+    url = f"{url_base}{urls.subscriber.format(subscriber_id=subscriber.id)}"
+    resp = httpx.put(url, json=update_model.model_dump(), headers=core_headers, follow_redirects=True)
+    resp.raise_for_status()
+
+    return subscriber_by_id(subscriber.id)
+
+
+# endregion
+
+def disable_subscriber(subscriber: models.Subscriber) -> models.Subscriber:
+    return update_subscriber(subscriber, status=SubscriberStatuses.disabled)
+
+
+def enable_subscriber(subscriber: models.Subscriber) -> models.Subscriber:
+    return update_subscriber(subscriber, status=SubscriberStatuses.enabled)
+
+
+def block_subscriber(subscriber: models.Subscriber) -> models.Subscriber:
+    return update_subscriber(subscriber, status=SubscriberStatuses.blocklisted)
+
+
+# region def delete_subscriber(email: Optional[str] = None, overriding_subscriber_id: Optional[int] = None) -> bool
+
+def send_transactional_email(subscriber_email: str, template_id: int, from_email: str, template_data: dict,
+                             messenger_channel: str = 'email', content_type: str = 'markdown') -> bool:
+    global core_headers
+    validate_state(url=True, user=True)
+    subscriber_email = (subscriber_email or '').lower().strip()
+    if not subscriber_email:
+        raise ValueError("Email is required")
+
+    body_data = {
+        'subscriber_email': subscriber_email,
+        'from_email': from_email,
+        'template_id': template_id,
+        'data': template_data,
+        'messenger': messenger_channel,
+        'content_type': content_type,
+    }
+    try:
+        url = f"{url_base}{urls.send_tx}"
+        resp = httpx.post(url, json=body_data, headers=core_headers, follow_redirects=True)
+        resp.raise_for_status()
+
+        raw_data = resp.json()
+        return raw_data.get('data')  # {'data': True}
+    except Exception as e:
+        # print(e)
+        # print(resp.text)
+        raise
+
+# endregion
+
+
+# region def is_healthy() -> bool
+
+def is_healthy() -> bool:
+    # noinspection PyBroadException
+    try:
+        validate_state(url=True, user=True)
+
+        url = f'{url_base}{urls.health}'
+        resp = httpx.get(url, headers=core_headers, follow_redirects=True)
+        resp.raise_for_status()
+
+        data = resp.json()
+        return data.get('data', False)
+    except Exception:
+        return False
+
+
+# endregion
+
+# region def verify_login() -> bool
+def verify_login() -> bool:
+    return is_healthy()
+
+
+# endregion
+
+# region def validate_login(user_name, pw)
+
+def validate_login(user_name, pw):
+    if not user_name:
+        raise Exception("Username cannot be empty")
+    if not pw:
+        raise Exception("Password cannot be empty")
+
+
+# endregion
+
+# region def validate_state(url=False, user=False)
+
+def validate_state(url=False, user=False):
+    if url and not url_base:
+        raise Exception("URL Base must be set to proceed.")
+
+    if user and core_headers.get('Authorization') is None:
+        raise Exception("You must login before proceeding.")
+
+# endregion

listmonk-0.1.0/listmonk/models/__init__.py

@@ -0,0 +1,56 @@
+import datetime
+import enum
+import typing
+
+import pydantic
+from pydantic import BaseModel, field_serializer
+
+
+class SubscriberStatuses(enum.StrEnum):
+    enabled = "enabled"
+    disabled = "disabled"
+    blocklisted = "blocklisted"
+
+
+class SubscriberStatus(BaseModel):
+    unconfirmed_count: int = pydantic.Field(alias="unconfirmed")
+
+
+class MailingList(BaseModel):
+    id: int
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+    uuid: str
+    name: str
+    type: str
+    optin: str
+    tags: list[str]
+    description: str
+    subscriber_count: int
+    subscriber_statuses: SubscriberStatus
+
+
+class Subscriber(BaseModel):
+    id: int
+    email: str
+    name: str
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+    uuid: typing.Optional[str] = None
+    lists: list[dict] = []
+    attribs: dict[str, typing.Any] = {}
+    status: typing.Optional[str] = None
+
+    @field_serializer('created_at', 'updated_at')
+    def serialize_date_times(self, fld: datetime, _info):
+        formatted_string = fld.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        return formatted_string
+
+
+class CreateSubscriberModel(BaseModel):
+    email: str
+    name: str
+    status: str
+    lists: list[int] = []
+    preconfirm_subscriptions: bool
+    attribs: dict = {}

listmonk-0.1.0/listmonk/urls.py

@@ -0,0 +1,6 @@
+health = '/api/health'
+lists = '/api/lists'
+lst = '/api/lists/{list_id}'
+subscriber = '/api/subscribers/{subscriber_id}'
+subscribers = '/api/subscribers'
+send_tx = '/api/tx'

listmonk-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "listmonk"
+description = "Listmonk Email App API Client for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+keywords = [
+    "email",
+    "newsletters",
+    "marketing",
+    "api-client",
+]
+authors = [
+    { name = "Michael Kennedy", email = "michael@talkpython.fm" },
+]
+classifiers = [
+    'Development Status :: 2 - Pre-Alpha',
+    'License :: OSI Approved :: MIT License',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3.8',
+    'Programming Language :: Python :: 3.9',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+]
+dependencies = [
+    "httpx",
+    "pydantic",
+]
+version = "0.1.0"
+
+
+[project.urls]
+Homepage = "https://github.com/mikeckennedy/listmonk"
+Tracker = "https://github.com/mikeckennedy/listmonk/issues"
+Source = "https://github.com/mikeckennedy/listmonk"
+
+[build-system]
+requires = ["hatchling>=1.21.0", "hatch-vcs>=0.3.0"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.github",
+    "/tests",
+    "/example_client",
+    "settings.json",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["listmonk"]
+exclude = [
+    "/.github",
+    "/tests",
+    "/example_client",
+    "settings.json",
+]