listmonk-api 0.6.0__py3-none-any.whl

listmonk_api/__init__.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+from typing import Any
+import warnings
+
+# Suppress RequestsDependencyWarning due to chardet 6.x / requests 2.32.x mismatch
+# Centralized here to ensure it runs before any sub-package imports
+warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+
+__all__: list[str] = []
+
+CORE_MODULES: list[str] = [
+    "listmonk_api.api_client",
+    "listmonk_api.models",
+]
+
+OPTIONAL_MODULES = {
+    "listmonk_api.agent_server": "agent_server",
+    "listmonk_api.mcp_server": "mcp_server",
+}
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+# Eagerly import core modules (keeps API wrappers fast & light)
+for module_name in CORE_MODULES:
+    if module_name:
+        module = importlib.import_module(module_name)
+        _expose_members(module)
+
+# Dynamic/lazy loading of optional modules (agent_server, mcp_server)
+_loaded_optional_modules = {}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def __getattr__(name: str) -> Any:
+    # Handle availability flags dynamically without eager imports
+    if name == "_MCP_AVAILABLE":
+        mcp_key = next((k for k in OPTIONAL_MODULES if "mcp_server" in k), None)
+        if mcp_key:
+            return _import_module_safely(mcp_key) is not None
+        return False
+    if name == "_AGENT_AVAILABLE":
+        agent_key = next((k for k in OPTIONAL_MODULES if "agent_server" in k), None)
+        if agent_key:
+            return _import_module_safely(agent_key) is not None
+        return False
+
+    # Check optional modules
+    for module_name in OPTIONAL_MODULES:
+        if module_name not in _loaded_optional_modules:
+            module = _import_module_safely(module_name)
+            if module is not None:
+                _loaded_optional_modules[module_name] = module
+                _expose_members(module)
+
+        module = _loaded_optional_modules.get(module_name)
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

listmonk_api/__main__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/python
+# coding: utf-8
+from listmonk_api.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

listmonk_api/agent_server.py

@@ -0,0 +1,85 @@
+#!/usr/bin/python
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.6.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
+
+
+def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv(
+        "DEFAULT_AGENT_NAME", meta.get("name", "Listmonk Api")
+    )
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get(
+            "description",
+            "AI agent for Listmonk Api management.",
+        ),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    print(f"{DEFAULT_AGENT_NAME} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    # Start server using the auto-discovery pattern (from mcp_config.json)
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

listmonk_api/api_client.py

@@ -0,0 +1,300 @@
+from typing import Optional, List, Dict, Union
+import requests
+
+from listmonk_api.models import (
+    SubscriberCreateRequest,
+    ListCreateRequest,
+    ListEditRequest,
+    ImportSubscribersRequest,
+    CampaignCreateRequest,
+    CampaignStatusRequest,
+    MediaUploadRequest,
+    TransactionalMessageRequest,
+)
+
+
+class ListmonkAPI:
+    """API client for Listmonk."""
+
+    def __init__(self, url: str, token: str):
+        self.base_url = url
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            }
+        )
+
+    def get(self, endpoint: str, **kwargs):
+        url = self.base_url.rstrip("/") + "/" + endpoint.lstrip("/")
+        response = self._session.get(url, **kwargs)
+        response.raise_for_status()
+        return response
+
+    def post(self, endpoint: str, **kwargs):
+        url = self.base_url.rstrip("/") + "/" + endpoint.lstrip("/")
+        response = self._session.post(url, **kwargs)
+        response.raise_for_status()
+        return response
+
+    def put(self, endpoint: str, **kwargs):
+        url = self.base_url.rstrip("/") + "/" + endpoint.lstrip("/")
+        response = self._session.put(url, **kwargs)
+        response.raise_for_status()
+        return response
+
+    def delete(self, endpoint: str, **kwargs):
+        url = self.base_url.rstrip("/") + "/" + endpoint.lstrip("/")
+        response = self._session.delete(url, **kwargs)
+        response.raise_for_status()
+        return response
+
+    # ------------------------------------------------------------------------------------------------------------------
+    # Subscribers API
+    # ------------------------------------------------------------------------------------------------------------------
+    def get_subscribers(
+        self,
+        query: Optional[Dict] = None,
+        list_id: Optional[Union[int, List[int]]] = None,
+        max_pages: int = 0,
+        per_page: int = 100,
+    ):
+        # Fetch the first page to get X-Total-Pages
+        response = self.get(f"/subscribers?per_page={per_page}")
+        # BUG FIX 1: Safely get X-Total-Pages, defaulting to 1 if not present
+        total_pages = int(response.headers.get("X-Total-Pages", 1))
+
+        results = []
+        subscriber_filter = f"?per_page={per_page}"
+
+        if list_id:
+            if isinstance(list_id, list):
+                for single_list_id in list_id:
+                    subscriber_filter += f"&list_id={single_list_id}"
+            else:
+                subscriber_filter += f"&list_id={list_id}"
+
+        if max_pages == 0 or max_pages > total_pages:
+            max_pages = total_pages
+
+        data = None
+        if query:
+            data = query
+
+        for page in range(1, max_pages + 1):
+            # Listmonk usually uses 1-indexed pages for its endpoints like `?page=1`
+            response_page = self.get(
+                f"/subscribers{subscriber_filter}&page={page}", json=data
+            )
+            response_json = response_page.json()
+            if isinstance(response_json, dict) and "data" in response_json:
+                results.extend(response_json["data"].get("results", []))
+            elif isinstance(response_json, list):
+                results.extend(response_json)
+            else:
+                results.append(response_json)
+
+        return results
+
+    def get_subscriber(self, subscriber_id: int):
+        return self.get(f"/subscribers/{subscriber_id}").json()
+
+    def get_subscribers_from_list(self, list_id: int):
+        return self.get(f"/subscribers/lists/{list_id}").json()
+
+    def create_subscriber(self, data: SubscriberCreateRequest):
+        return self.post("/subscribers", json=data.model_dump(exclude_none=True)).json()
+
+    # ------------------------------------------------------------------------------------------------------------------
+    # Lists API
+    # ------------------------------------------------------------------------------------------------------------------
+    def get_lists(
+        self,
+        query: Optional[Dict] = None,
+        order_by: Optional[str] = None,
+        order: Optional[str] = None,
+        max_pages: int = 0,
+        per_page: int = 100,
+    ):
+        response = self.get(f"/lists?per_page={per_page}")
+        total_pages = int(response.headers.get("X-Total-Pages", 1))
+
+        results = []
+        list_filter = f"?per_page={per_page}"
+
+        if order_by and order_by in ["name", "status", "created_at", "updated_at"]:
+            list_filter += f"&order_by={order_by}"
+        if order and order.upper() in ["ASC", "DESC"]:
+            list_filter += f"&order={order}"
+
+        if max_pages == 0 or max_pages > total_pages:
+            max_pages = total_pages
+
+        data = None
+        if query:
+            data = query
+
+        for page in range(1, max_pages + 1):
+            response_page = self.get(f"/lists{list_filter}&page={page}", json=data)
+            response_json = response_page.json()
+            if isinstance(response_json, dict) and "data" in response_json:
+                results.extend(response_json["data"].get("results", []))
+            elif isinstance(response_json, list):
+                results.extend(response_json)
+            else:
+                results.append(response_json)
+
+        return results
+
+    def get_list(self, list_id: int):
+        return self.get(f"/lists/{list_id}").json()
+
+    def create_list(self, data: ListCreateRequest):
+        return self.post("/lists", json=data.model_dump(exclude_none=True)).json()
+
+    def edit_list(self, list_id: int, data: ListEditRequest):
+        return self.put(
+            f"/lists/{list_id}", json=data.model_dump(exclude_none=True)
+        ).json()
+
+    # ------------------------------------------------------------------------------------------------------------------
+    # Import API
+    # ------------------------------------------------------------------------------------------------------------------
+    def get_subscriber_import_status(self):
+        return self.get("/import/subscribers").json()
+
+    def get_subscriber_import_logs(self):
+        return self.get("/import/subscribers/logs").json()
+
+    def import_subscribers(self, data: ImportSubscribersRequest):
+        # NOTE: Using self.post instead of self.get for importing as it was incorrect in the old wrapper.
+        # Actually listmonk expects a POST for import
+        return self.post(
+            "/import/subscribers", json=data.model_dump(exclude_none=True)
+        ).json()
+
+    def delete_subscriber_import(self):
+        return self.delete("/import/subscribers/logs").json()
+
+    # ------------------------------------------------------------------------------------------------------------------
+    # Campaigns API
+    # ------------------------------------------------------------------------------------------------------------------
+    def get_campaigns(
+        self,
+        query: Optional[Dict] = None,
+        order_by: Optional[str] = None,
+        order: Optional[str] = None,
+        max_pages: int = 0,
+        per_page: int = 100,
+    ):
+        response = self.get(f"/campaigns?per_page={per_page}")
+        total_pages = int(response.headers.get("X-Total-Pages", 1))
+
+        results = []
+        campaign_filter = f"?per_page={per_page}"
+
+        if order_by and order_by in ["name", "status", "created_at", "updated_at"]:
+            campaign_filter += f"&order_by={order_by}"
+        if order and order.upper() in ["ASC", "DESC"]:
+            campaign_filter += f"&order={order}"
+
+        if max_pages == 0 or max_pages > total_pages:
+            max_pages = total_pages
+
+        data = None
+        if query:
+            data = query
+
+        for page in range(1, max_pages + 1):
+            response_page = self.get(
+                f"/campaigns{campaign_filter}&page={page}", json=data
+            )
+            response_json = response_page.json()
+            if isinstance(response_json, dict) and "data" in response_json:
+                results.extend(response_json["data"].get("results", []))
+            elif isinstance(response_json, list):
+                results.extend(response_json)
+            else:
+                results.append(response_json)
+
+        return results
+
+    def get_campaign(self, campaign_id: int):
+        return self.get(f"/campaigns/{campaign_id}").json()
+
+    def get_campaign_preview(self, campaign_id: int):
+        return self.get(f"/campaigns/{campaign_id}/preview").json()
+
+    def get_campaign_stats(self, campaign_id: int):
+        return self.get(f"/campaigns/{campaign_id}/running/stats").json()
+
+    def create_campaign(self, data: CampaignCreateRequest):
+        # BUG FIX 2 & 3: Included attachments in data model and mapped send_type to type via pydantic alias (by_alias=True)
+        return self.post(
+            "/campaigns", json=data.model_dump(by_alias=True, exclude_none=True)
+        ).json()
+
+    def set_campaign_status(self, campaign_id: int, data: CampaignStatusRequest):
+        return self.put(
+            f"/campaigns/{campaign_id}/status", json=data.model_dump(exclude_none=True)
+        ).json()
+
+    def delete_campaign(self, campaign_id: int):
+        return self.delete(f"/campaigns/{campaign_id}").json()
+
+    # ------------------------------------------------------------------------------------------------------------------
+    # Media API
+    # ------------------------------------------------------------------------------------------------------------------
+    def get_media(self, media_id: int):
+        return self.get("/media").json()
+
+    def upload_media(self, data: MediaUploadRequest):
+        return self.post("/media", json=data.model_dump(exclude_none=True)).json()
+
+    def delete_media(self, media_id: int):
+        return self.delete(f"/media/{media_id}").json()
+
+    # ------------------------------------------------------------------------------------------------------------------
+    # Templates API
+    # ------------------------------------------------------------------------------------------------------------------
+    def get_templates(self, max_pages: int = 0, per_page: int = 100):
+        response = self.get(f"/templates?per_page={per_page}")
+        total_pages = int(response.headers.get("X-Total-Pages", 1))
+
+        results = []
+        template_filter = f"?per_page={per_page}"
+
+        if max_pages == 0 or max_pages > total_pages:
+            max_pages = total_pages
+
+        for page in range(1, max_pages + 1):
+            response_page = self.get(f"/templates{template_filter}&page={page}")
+            response_json = response_page.json()
+            if isinstance(response_json, dict) and "data" in response_json:
+                results.extend(response_json["data"].get("results", []))
+            elif isinstance(response_json, list):
+                results.extend(response_json)
+            else:
+                results.append(response_json)
+
+        return results
+
+    def get_template(self, template_id: int):
+        return self.get(f"/templates/{template_id}").json()
+
+    def get_template_preview(self, template_id: int):
+        return self.get(f"/templates/{template_id}/preview").json()
+
+    def set_default_template(self, template_id: int):
+        return self.put(f"/templates/{template_id}/default").json()
+
+    def delete_template(self, template_id: int):
+        return self.delete(f"/templates/{template_id}").json()
+
+    # ------------------------------------------------------------------------------------------------------------------
+    # Transactional API
+    # ------------------------------------------------------------------------------------------------------------------
+    def transactional_message(self, data: TransactionalMessageRequest):
+        # BUG FIX 4: Included attachments in data model and excluded None
+        return self.post("/tx", json=data.model_dump(exclude_none=True)).json()

listmonk_api/auth.py

@@ -0,0 +1,36 @@
+#!/usr/bin/python
+# coding: utf-8
+
+import os
+import urllib3
+
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+from agent_utilities.core.exceptions import AuthError, UnauthorizedError
+
+from listmonk_api.api_client import ListmonkAPI
+
+_client = None
+
+
+def get_client():
+    """Get or create a singleton API client instance."""
+    global _client
+    if _client is None:
+        base_url = os.getenv("LISTMONK_URL", "http://localhost:8080")
+        token = os.getenv("LISTMONK_TOKEN", "")
+
+        try:
+            _client = ListmonkAPI(
+                url=base_url,
+                token=token,
+            )
+
+        except (AuthError, UnauthorizedError) as e:
+            raise RuntimeError(
+                f"AUTHENTICATION ERROR: The credentials provided are not valid for '{base_url}'. "
+                f"Please check your LISTMONK_TOKEN and LISTMONK_URL environment variables. "
+                f"Error details: {str(e)}"
+            ) from e
+
+    return _client