axene-mailer 0.1.0__tar.gz

axene_mailer-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# node
+node_modules/
+dist/
+*.tsbuildinfo
+# dotnet
+bin/
+obj/
+*.nupkg
+*.snupkg
+# python
+__pycache__/
+*.egg-info/
+.venv/
+# misc
+.DS_Store
+.idea/
+.vscode/
+# gradle
+.gradle/
+build/

axene_mailer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axene Solutions
+
+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.

axene_mailer-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: axene-mailer
+Version: 0.1.0
+Summary: Official Python client for Axene Mailer: send receipts, confirmations, and campaigns from your own domain. Priced in KES, billed via M-Pesa.
+Project-URL: Homepage, https://axene.io/docs/mailer/getting-started/welcome
+Project-URL: Repository, https://github.com/Axene-Solutions/axene-sdks
+Project-URL: Issues, https://github.com/Axene-Solutions/axene-sdks/issues
+Author: Axene Solutions
+License-Expression: MIT
+License-File: LICENSE
+Keywords: africa,axene,email,kes,mailer,mpesa,transactional
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# axene-mailer (Python)
+
+Official Python client for [Axene Mailer](https://axene.io). Send receipts,
+confirmations, and campaigns from your own domain, priced in KES, billed via M-Pesa.
+
+Pure standard library: no runtime dependencies. Python 3.8+.
+
+## Install
+
+```bash
+pip install axene-mailer
+```
+
+## Usage
+
+```python
+from axene_mailer import Axene
+
+axene = Axene(api_key="axm_k_your_api_key")
+
+res = axene.emails.send({
+    "from": {"email": "hello@yourdomain.com", "name": "Your Shop"},
+    "to": "customer@example.com",
+    "subject": "Your receipt",
+    "html": "<p>Thanks for your order.</p>",
+    "text": "Thanks for your order.",
+})
+print("queued", res["id"])
+```
+
+`from`, `to`, `cc`, `bcc` accept a string, a `{"email", "name"}` dict, or a list of either.
+
+### More
+
+```python
+axene.emails.send_batch([{...}, {...}])      # bare array under the hood
+axene.emails.get(res["id"])                   # status
+axene.emails.validate({...})                  # dry-run: would this send?
+axene.domains.list()                          # your sending domains
+
+# Scheduling (Starter plan and up)
+from datetime import datetime, timedelta, timezone
+axene.emails.send({..., "send_at": datetime.now(timezone.utc) + timedelta(hours=1)})
+```
+
+### Errors and retries
+
+Non-2xx responses raise `AxeneError` (`.status`, `.code`, `.args[0]` message).
+The client retries 429 and 5xx with exponential backoff (configurable via
+`max_retries`).
+
+Get an API key at [mail.axene.io](https://mail.axene.io). Docs: <https://axene.io/docs/mailer/getting-started/welcome>.
+
+MIT (c) Axene Solutions

axene_mailer-0.1.0/README.md

@@ -0,0 +1,54 @@
+# axene-mailer (Python)
+
+Official Python client for [Axene Mailer](https://axene.io). Send receipts,
+confirmations, and campaigns from your own domain, priced in KES, billed via M-Pesa.
+
+Pure standard library: no runtime dependencies. Python 3.8+.
+
+## Install
+
+```bash
+pip install axene-mailer
+```
+
+## Usage
+
+```python
+from axene_mailer import Axene
+
+axene = Axene(api_key="axm_k_your_api_key")
+
+res = axene.emails.send({
+    "from": {"email": "hello@yourdomain.com", "name": "Your Shop"},
+    "to": "customer@example.com",
+    "subject": "Your receipt",
+    "html": "<p>Thanks for your order.</p>",
+    "text": "Thanks for your order.",
+})
+print("queued", res["id"])
+```
+
+`from`, `to`, `cc`, `bcc` accept a string, a `{"email", "name"}` dict, or a list of either.
+
+### More
+
+```python
+axene.emails.send_batch([{...}, {...}])      # bare array under the hood
+axene.emails.get(res["id"])                   # status
+axene.emails.validate({...})                  # dry-run: would this send?
+axene.domains.list()                          # your sending domains
+
+# Scheduling (Starter plan and up)
+from datetime import datetime, timedelta, timezone
+axene.emails.send({..., "send_at": datetime.now(timezone.utc) + timedelta(hours=1)})
+```
+
+### Errors and retries
+
+Non-2xx responses raise `AxeneError` (`.status`, `.code`, `.args[0]` message).
+The client retries 429 and 5xx with exponential backoff (configurable via
+`max_retries`).
+
+Get an API key at [mail.axene.io](https://mail.axene.io). Docs: <https://axene.io/docs/mailer/getting-started/welcome>.
+
+MIT (c) Axene Solutions

axene_mailer-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "axene-mailer"
+version = "0.1.0"
+description = "Official Python client for Axene Mailer: send receipts, confirmations, and campaigns from your own domain. Priced in KES, billed via M-Pesa."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [{ name = "Axene Solutions" }]
+keywords = ["email", "mailer", "axene", "africa", "kes", "mpesa", "transactional"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Email",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://axene.io/docs/mailer/getting-started/welcome"
+Repository = "https://github.com/Axene-Solutions/axene-sdks"
+Issues = "https://github.com/Axene-Solutions/axene-sdks/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/axene_mailer"]

axene_mailer-0.1.0/src/axene_mailer/__init__.py

@@ -0,0 +1,36 @@
+"""Axene Mailer SDK for Python.
+
+Professional email for Africa: send receipts, confirmations, and campaigns from
+your own domain. Priced in KES, billed via M-Pesa.
+
+    from axene_mailer import Axene
+
+    axene = Axene(api_key="axm_k_your_api_key")
+    axene.emails.send({
+        "from": "hello@yourdomain.com",
+        "to": "customer@example.com",
+        "subject": "Your receipt",
+        "html": "<p>Thanks for your order.</p>",
+    })
+"""
+
+from .client import Axene
+from .errors import AxeneError
+from .resources.contacts import Contacts
+from .resources.domains import Domains
+from .resources.emails import Emails
+from .resources.suppressions import Suppressions
+from .resources.templates import Templates
+from .resources.webhooks import Webhooks
+
+__all__ = [
+    "Axene",
+    "AxeneError",
+    "Emails",
+    "Domains",
+    "Contacts",
+    "Suppressions",
+    "Templates",
+    "Webhooks",
+]
+__version__ = "0.1.0"

axene_mailer-0.1.0/src/axene_mailer/_http.py

@@ -0,0 +1,127 @@
+"""HTTP transport: the single place that talks to the network. Owns
+authentication, JSON encoding, timeouts, retries with backoff, and turning
+non-2xx responses into :class:`AxeneError`. Uses only the standard library so
+the package has no runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+from .errors import AxeneError
+
+_DEFAULT_BASE = "https://mail.axene.io"
+_USER_AGENT = "axene-mailer-python/0.1.0"
+
+
+class HttpTransport:
+    """Performs authenticated JSON requests, retrying ``429`` and ``5xx``."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = (base_url or _DEFAULT_BASE).rstrip("/")
+        self._max_retries = max(1, max_retries)
+        self._timeout = timeout
+
+    def request(self, method: str, path: str, body: Any = None) -> Any:
+        """Send a request and return the parsed JSON response."""
+        url = f"{self._base_url}{path}"
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        last_error: Optional[Exception] = None
+
+        for attempt in range(1, self._max_retries + 1):
+            req = urllib.request.Request(url, data=data, method=method)
+            req.add_header("Authorization", f"Bearer {self._api_key}")
+            req.add_header("Content-Type", "application/json")
+            req.add_header("User-Agent", _USER_AGENT)
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                    raw = resp.read().decode("utf-8")
+                    return json.loads(raw) if raw else None
+            except urllib.error.HTTPError as e:  # the server responded with a non-2xx
+                status = e.code
+                if self._is_retryable(status) and attempt < self._max_retries:
+                    time.sleep(self._backoff(e, attempt))
+                    continue
+                raise self._to_error(status, e.read().decode("utf-8", "replace"))
+            except urllib.error.URLError as e:  # transport / DNS / timeout
+                last_error = e
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff(None, attempt))
+                    continue
+
+        raise AxeneError(0, f"Axene request failed: {last_error}")
+
+    def upload(self, path: str, file_bytes: bytes, filename: str) -> Any:
+        """Upload a single file as ``multipart/form-data`` under the field name
+        ``file``.
+
+        The multipart body is built by hand (boundary included) so the package
+        stays dependency-free. Not retried, since uploads are not idempotent.
+        """
+        url = f"{self._base_url}{path}"
+        boundary = "axene" + os.urandom(16).hex()
+        crlf = b"\r\n"
+        head = (
+            f'--{boundary}\r\n'
+            f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n'
+            f"Content-Type: application/octet-stream\r\n\r\n"
+        ).encode("utf-8")
+        tail = f"\r\n--{boundary}--\r\n".encode("utf-8")
+        data = head + file_bytes + tail
+
+        req = urllib.request.Request(url, data=data, method="POST")
+        req.add_header("Authorization", f"Bearer {self._api_key}")
+        req.add_header("Content-Type", f"multipart/form-data; boundary={boundary}")
+        req.add_header("User-Agent", _USER_AGENT)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as e:
+            raise self._to_error(e.code, e.read().decode("utf-8", "replace"))
+        except urllib.error.URLError as e:
+            raise AxeneError(0, f"Axene upload failed: {e}")
+
+    @staticmethod
+    def _is_retryable(status: int) -> bool:
+        return status == 429 or status >= 500
+
+    @staticmethod
+    def _backoff(err: Optional[urllib.error.HTTPError], attempt: int) -> float:
+        if err is not None:
+            retry_after = err.headers.get("Retry-After") if err.headers else None
+            if retry_after and retry_after.isdigit():
+                return float(retry_after)
+        return 0.25 * (2 ** (attempt - 1))
+
+    @staticmethod
+    def _to_error(status: int, raw: str) -> AxeneError:
+        """Map the API's ``{"detail": {"code", "message"}}`` (or string) body."""
+        message = f"Axene request failed ({status})"
+        code: Optional[str] = None
+        payload: Any = None
+        try:
+            payload = json.loads(raw)
+            detail = payload.get("detail") if isinstance(payload, dict) else None
+            if isinstance(detail, dict):
+                message = detail.get("message", message)
+                code = detail.get("code")
+            elif isinstance(detail, str):
+                message = detail
+        except (ValueError, AttributeError):
+            pass  # non-JSON body: keep the generic message
+        return AxeneError(status, message, code, payload)

axene_mailer-0.1.0/src/axene_mailer/_serialize.py

@@ -0,0 +1,73 @@
+"""Internal helpers that translate ergonomic inputs into the exact JSON the
+API expects. Not part of the public API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+Address = Union[str, Dict[str, Any]]
+
+
+def _to_address(a: Address) -> Dict[str, Any]:
+    """A bare string becomes ``{"email": ...}``."""
+    return {"email": a} if isinstance(a, str) else a
+
+
+def _to_address_list(a: Optional[Union[Address, List[Address]]]) -> Optional[List[Dict[str, Any]]]:
+    if a is None:
+        return None
+    items = a if isinstance(a, list) else [a]
+    return [_to_address(x) for x in items]
+
+
+def _iso(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    return value.isoformat() if isinstance(value, datetime) else value
+
+
+def prune(o: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop keys whose value is ``None`` so they are omitted from the JSON body."""
+    return {k: v for k, v in o.items() if v is not None}
+
+
+def query(params: Dict[str, Any]) -> str:
+    """Build a URL query string, skipping ``None`` values.
+
+    Returns ``""`` when nothing is set, or ``"?a=1&b=2"`` otherwise. ``datetime``
+    values are serialized to ISO 8601.
+    """
+    from urllib.parse import urlencode
+
+    pairs = []
+    for k, v in params.items():
+        if v is None:
+            continue
+        pairs.append((k, _iso(v) if isinstance(v, datetime) else str(v)))
+    encoded = urlencode(pairs)
+    return f"?{encoded}" if encoded else ""
+
+
+def serialize_send(p: Dict[str, Any]) -> Dict[str, Any]:
+    """Build the JSON body for a send.
+
+    The API names the sender field ``from_`` on the wire; callers pass a clean
+    ``"from"`` key, so the mapping happens here. Keys with ``None`` values are
+    omitted.
+    """
+    body = {
+        "from_": _to_address(p["from"]),
+        "to": _to_address_list(p["to"]),
+        "subject": p["subject"],
+        "html": p.get("html"),
+        "text": p.get("text"),
+        "cc": _to_address_list(p.get("cc")),
+        "bcc": _to_address_list(p.get("bcc")),
+        "reply_to": _to_address(p["reply_to"]) if p.get("reply_to") else None,
+        "headers": p.get("headers"),
+        "tags": p.get("tags"),
+        "send_at": _iso(p.get("send_at")),
+        "attachments": p.get("attachments"),
+    }
+    return {k: v for k, v in body.items() if v is not None}

axene_mailer-0.1.0/src/axene_mailer/client.py

@@ -0,0 +1,51 @@
+"""The Axene client: composes the HTTP transport with the resource groups."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._http import HttpTransport
+from .resources.contacts import Contacts
+from .resources.domains import Domains
+from .resources.emails import Emails
+from .resources.suppressions import Suppressions
+from .resources.templates import Templates
+from .resources.webhooks import Webhooks
+
+
+class Axene:
+    """Axene Mailer API client.
+
+    Example::
+
+        from axene_mailer import Axene
+
+        axene = Axene(api_key="axm_k_your_api_key")
+        axene.emails.send({
+            "from": "hello@yourdomain.com",
+            "to": "customer@example.com",
+            "subject": "Your receipt",
+            "html": "<p>Thanks for your order.</p>",
+        })
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+    ) -> None:
+        http = HttpTransport(api_key, base_url=base_url, max_retries=max_retries, timeout=timeout)
+        #: Send and inspect emails.
+        self.emails = Emails(http)
+        #: Register, verify, and transfer sending domains.
+        self.domains = Domains(http)
+        #: Manage subscriber lists, contacts, CSV imports, and bulk sends.
+        self.contacts = Contacts(http)
+        #: Manage the do-not-send suppression list.
+        self.suppressions = Suppressions(http)
+        #: Manage reusable email templates.
+        self.templates = Templates(http)
+        #: Manage webhook subscriptions and inspect deliveries.
+        self.webhooks = Webhooks(http)

axene_mailer-0.1.0/src/axene_mailer/errors.py

@@ -0,0 +1,23 @@
+"""Error types raised by the SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class AxeneError(Exception):
+    """Raised for any non-2xx API response, or a transport failure that
+    survives all retries.
+
+    Inspect :attr:`status` and :attr:`code` to branch on specific failures
+    (for example a ``422`` with code ``"invalid"``).
+    """
+
+    def __init__(self, status: int, message: str, code: Optional[str] = None, detail: Any = None) -> None:
+        super().__init__(message)
+        #: HTTP status code. ``0`` indicates a transport/network failure.
+        self.status = status
+        #: Machine-readable error code from the API body, when present.
+        self.code = code
+        #: The raw parsed response body, for debugging.
+        self.detail = detail

axene_mailer-0.1.0/src/axene_mailer/resources/__init__.py

@@ -0,0 +1 @@
+"""API resource groups."""

axene_mailer-0.1.0/src/axene_mailer/resources/contacts.py

@@ -0,0 +1,104 @@
+"""The ``contacts`` resource: manage subscriber lists, their contacts, CSV
+imports, and templated bulk sends."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._http import HttpTransport
+from .._serialize import prune, query
+
+
+class Contacts:
+    """Accessed as ``axene.contacts``."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    def list_lists(self) -> List[Dict[str, Any]]:
+        """List all subscriber lists in the active workspace."""
+        return self._http.request("GET", "/v1/contacts/")
+
+    def create_list(
+        self,
+        name: str,
+        description: Optional[str] = None,
+        icon_seed: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a subscriber list."""
+        body = prune({"name": name, "description": description, "icon_seed": icon_seed})
+        return self._http.request("POST", "/v1/contacts/", body)
+
+    def get_list(self, list_id: str, page: int = 0, limit: int = 50) -> Dict[str, Any]:
+        """Get a list with a page of its contacts (zero-based ``page``)."""
+        return self._http.request("GET", f"/v1/contacts/{list_id}{query({'page': page, 'limit': limit})}")
+
+    def update_list(
+        self,
+        list_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        icon_seed: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Update a list's name, description, or icon (partial)."""
+        body = prune({"name": name, "description": description, "icon_seed": icon_seed})
+        return self._http.request("PATCH", f"/v1/contacts/{list_id}", body)
+
+    def delete_list(self, list_id: str) -> None:
+        """Delete a list and all of its contacts."""
+        return self._http.request("DELETE", f"/v1/contacts/{list_id}")
+
+    def add_contact(
+        self,
+        list_id: str,
+        email: str,
+        name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Add a single contact to a list."""
+        body = prune({"email": email, "name": name, "metadata": metadata})
+        return self._http.request("POST", f"/v1/contacts/{list_id}/contacts", body)
+
+    def remove_contact(self, list_id: str, contact_id: str) -> None:
+        """Remove a contact from a list."""
+        return self._http.request("DELETE", f"/v1/contacts/{list_id}/contacts/{contact_id}")
+
+    def upload_csv(
+        self,
+        list_id: str,
+        file_bytes: bytes,
+        filename: str = "contacts.csv",
+    ) -> Dict[str, Any]:
+        """Import contacts from a CSV file (header row required).
+
+        The email column is auto-detected; other columns become contact
+        metadata. Sent as ``multipart/form-data`` under the field ``file``.
+        """
+        return self._http.upload(f"/v1/contacts/{list_id}/upload", file_bytes, filename)
+
+    def bulk_send(
+        self,
+        list_id: str,
+        sender_address_id: str,
+        subject: str,
+        html: Optional[str] = None,
+        text: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Send a templated email to every contact in a list.
+
+        ``contact_list_id`` is injected automatically from ``list_id``.
+        Subject/html/text may use ``{{email}}``, ``{{name}}``, and
+        ``{{metadata_key}}`` placeholders.
+        """
+        body = prune(
+            {
+                "contact_list_id": list_id,
+                "sender_address_id": sender_address_id,
+                "subject": subject,
+                "html": html,
+                "text": text,
+                "tags": tags,
+            }
+        )
+        return self._http.request("POST", f"/v1/contacts/{list_id}/send", body)

axene_mailer-0.1.0/src/axene_mailer/resources/domains.py

@@ -0,0 +1,77 @@
+"""The ``domains`` resource: register, verify, inspect, and transfer sending
+domains."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._http import HttpTransport
+from .._serialize import query
+
+
+class Domains:
+    """Accessed as ``axene.domains``."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    def list(self) -> List[Dict[str, Any]]:
+        """List your sending domains and their verification status."""
+        return self._http.request("GET", "/v1/domains/")
+
+    def create(self, name: str) -> Dict[str, Any]:
+        """Register a new sending domain. Returns the DNS records to publish."""
+        return self._http.request("POST", "/v1/domains/", {"name": name})
+
+    def get(self, domain_id: str) -> Dict[str, Any]:
+        """Fetch a domain with its DKIM selector and DNS records."""
+        return self._http.request("GET", f"/v1/domains/{domain_id}")
+
+    def delete(self, domain_id: str) -> None:
+        """Delete a domain."""
+        return self._http.request("DELETE", f"/v1/domains/{domain_id}")
+
+    def verify(self, domain_id: str) -> Dict[str, Any]:
+        """Re-check DNS and verify the domain."""
+        return self._http.request("POST", f"/v1/domains/{domain_id}/verify")
+
+    def health(self, domain_id: str) -> Dict[str, Any]:
+        """Run live DNS health checks (DKIM, SPF, DMARC, return-path, MX)."""
+        return self._http.request("GET", f"/v1/domains/{domain_id}/health")
+
+    def diagnose(self, domain_id: str) -> Dict[str, Any]:
+        """Diagnose configuration issues and get a health score."""
+        return self._http.request("GET", f"/v1/domains/{domain_id}/diagnose")
+
+    def mx_status(self, domain_id: str) -> Dict[str, Any]:
+        """Current MX status for inbound/forwarding (shape varies by provider)."""
+        return self._http.request("GET", f"/v1/domains/{domain_id}/mx-status")
+
+    def published_records(self, domain_id: str) -> Dict[str, Any]:
+        """The values currently published in DNS for each of the domain's records."""
+        return self._http.request("GET", f"/v1/domains/{domain_id}/published-records")
+
+    def rotate_dkim(self, domain_id: str) -> Dict[str, Any]:
+        """Rotate the domain's DKIM key, returning the new record to publish."""
+        return self._http.request("POST", f"/v1/domains/{domain_id}/rotate-dkim")
+
+    def transfer(
+        self,
+        domain_id: str,
+        target_email: str,
+        note: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Initiate a transfer of this domain to another Axene account."""
+        return self._http.request(
+            "POST",
+            f"/v1/domains/{domain_id}/transfer",
+            {"target_email": target_email, "note": note},
+        )
+
+    def check_availability(self, name: str) -> Dict[str, Any]:
+        """Check whether a domain name is available to add (checks public DNS)."""
+        return self._http.request("GET", f"/v1/domains/check-availability{query({'name': name})}")
+
+    def check(self, name: str) -> Dict[str, Any]:
+        """Check whether a domain name already exists in your account."""
+        return self._http.request("GET", f"/v1/domains/check/{name}")

axene_mailer-0.1.0/src/axene_mailer/resources/emails.py

@@ -0,0 +1,106 @@
+"""The ``emails`` resource: send, look up, search, schedule, and inspect
+messages."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from .._http import HttpTransport
+from .._serialize import _iso, query, serialize_send
+
+
+class Emails:
+    """Accessed as ``axene.emails``."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    def send(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Send a single email.
+
+        ``message`` keys: ``from`` (required), ``to`` (required), ``subject``
+        (required), and optionally ``html``, ``text``, ``cc``, ``bcc``,
+        ``reply_to``, ``headers``, ``tags``, ``send_at`` (``datetime`` or ISO
+        string), ``attachments``. ``from``/``to``/``cc``/``bcc`` accept a
+        string, a ``{"email", "name"}`` dict, or a list.
+        """
+        return self._http.request("POST", "/v1/emails/", serialize_send(message))
+
+    def send_batch(self, messages: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Send up to your plan's batch limit. The API accepts a bare array."""
+        return self._http.request("POST", "/v1/emails/batch", [serialize_send(m) for m in messages])
+
+    def validate(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Dry-run a send: check whether ``message`` would be accepted (sender
+        registered, domain verified, plan limits, account not restricted)
+        without actually sending it. Returns ``valid``, ``can_send``,
+        ``issues``, ``plan`` and ``usage``.
+        """
+        return self._http.request("POST", "/v1/emails/validate", serialize_send(message))
+
+    def list(
+        self,
+        status: Optional[str] = None,
+        page: int = 0,
+        limit: int = 20,
+    ) -> List[Dict[str, Any]]:
+        """List recent emails, newest first (zero-based ``page``)."""
+        params = {"status": status, "page": page, "limit": limit}
+        return self._http.request("GET", f"/v1/emails/{query(params)}")
+
+    def get(self, email_id: str) -> Dict[str, Any]:
+        """Fetch a single email with its bodies and events."""
+        return self._http.request("GET", f"/v1/emails/{email_id}")
+
+    def events(self, email_id: str) -> List[Dict[str, Any]]:
+        """List delivery / open / click / bounce events for an email."""
+        return self._http.request("GET", f"/v1/emails/{email_id}/events")
+
+    def retry(self, email_id: str) -> Dict[str, Any]:
+        """Re-send a bounced, rejected, or failed email as a new message."""
+        return self._http.request("POST", f"/v1/emails/{email_id}/retry")
+
+    def search(
+        self,
+        q: Optional[str] = None,
+        status: Optional[str] = None,
+        tag: Optional[str] = None,
+        page: int = 0,
+        limit: int = 20,
+    ) -> List[Dict[str, Any]]:
+        """Search emails.
+
+        ``q`` supports inline tokens (``to:``, ``from:``, ``status:``,
+        ``domain:``, ``tag:``); leftover words are matched as free text.
+        """
+        params = {"q": q, "status": status, "tag": tag, "page": page, "limit": limit}
+        return self._http.request("GET", f"/v1/emails/search{query(params)}")
+
+    def list_scheduled(self) -> List[Dict[str, Any]]:
+        """List emails scheduled for future delivery, soonest first."""
+        return self._http.request("GET", "/v1/emails/scheduled")
+
+    def cancel_scheduled(self, email_id: str) -> Dict[str, Any]:
+        """Cancel a scheduled email."""
+        return self._http.request("DELETE", f"/v1/emails/scheduled/{email_id}")
+
+    def send_scheduled_now(self, email_id: str) -> Dict[str, Any]:
+        """Send a scheduled email immediately instead of waiting."""
+        return self._http.request("POST", f"/v1/emails/scheduled/{email_id}/send-now")
+
+    def updates(self, since: Union[str, datetime]) -> List[Dict[str, Any]]:
+        """Poll for emails whose status changed at or after ``since`` (a
+        ``datetime`` or ISO 8601 string). Capped at 50 rows.
+        """
+        return self._http.request("GET", f"/v1/emails/updates{query({'since': _iso(since)})}")
+
+    def get_saved_searches(self) -> List[Dict[str, Any]]:
+        """Get the caller's saved searches."""
+        result = self._http.request("GET", "/v1/emails/saved-searches")
+        return result.get("searches", []) if isinstance(result, dict) else result
+
+    def set_saved_searches(self, searches: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Replace the caller's saved searches (max 50)."""
+        result = self._http.request("PUT", "/v1/emails/saved-searches", {"searches": searches})
+        return result.get("searches", []) if isinstance(result, dict) else result

axene_mailer-0.1.0/src/axene_mailer/resources/suppressions.py

@@ -0,0 +1,55 @@
+"""The ``suppressions`` resource: manage the do-not-send list."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .._http import HttpTransport
+from .._serialize import query
+
+
+class Suppressions:
+    """Accessed as ``axene.suppressions``."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    def list(
+        self,
+        page: int = 0,
+        limit: int = 50,
+        search: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List suppressed addresses.
+
+        Returns a paginated envelope ``{items, total, page, limit}`` (zero-based
+        ``page``).
+        """
+        params = {"page": page, "limit": limit, "search": search}
+        return self._http.request("GET", f"/v1/suppressions{query(params)}")
+
+    def add(self, email: str, reason: str = "manual") -> Dict[str, Any]:
+        """Suppress a single address.
+
+        The address maps to the wire field ``email_address``.
+        """
+        return self._http.request(
+            "POST",
+            "/v1/suppressions",
+            {"email_address": email, "reason": reason},
+        )
+
+    def bulk_upload(
+        self,
+        file_bytes: bytes,
+        filename: str = "suppressions.txt",
+    ) -> Dict[str, Any]:
+        """Bulk-import suppressions from a file (one email per line).
+
+        Sent as ``multipart/form-data`` under the field ``file``.
+        """
+        return self._http.upload("/v1/suppressions/bulk", file_bytes, filename)
+
+    def remove(self, suppression_id: str) -> None:
+        """Remove an address from the suppression list."""
+        return self._http.request("DELETE", f"/v1/suppressions/{suppression_id}")

axene_mailer-0.1.0/src/axene_mailer/resources/templates.py

@@ -0,0 +1,79 @@
+"""The ``templates`` resource: reusable email templates. Starter plan and up."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._http import HttpTransport
+from .._serialize import prune
+
+
+class Templates:
+    """Accessed as ``axene.templates``."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    def list(self) -> List[Dict[str, Any]]:
+        """List all templates, most recently updated first."""
+        return self._http.request("GET", "/v1/templates/")
+
+    def create(
+        self,
+        name: str,
+        subject: Optional[str] = None,
+        html: Optional[str] = None,
+        text: Optional[str] = None,
+        blocks_json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Create a template.
+
+        ``html`` maps to ``html_body`` and ``text`` to ``text_body`` on the
+        wire. ``variables`` are derived server-side from ``{{name}}``
+        placeholders, so you do not pass them.
+        """
+        body = prune(
+            {
+                "name": name,
+                "subject": subject,
+                "html_body": html,
+                "text_body": text,
+                "blocks_json": blocks_json,
+            }
+        )
+        return self._http.request("POST", "/v1/templates/", body)
+
+    def get(self, template_id: str) -> Dict[str, Any]:
+        """Fetch a single template."""
+        return self._http.request("GET", f"/v1/templates/{template_id}")
+
+    def update(
+        self,
+        template_id: str,
+        name: Optional[str] = None,
+        subject: Optional[str] = None,
+        html: Optional[str] = None,
+        text: Optional[str] = None,
+        blocks_json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Update a template (partial). ``html``/``text`` map to
+        ``html_body``/``text_body``.
+        """
+        body = prune(
+            {
+                "name": name,
+                "subject": subject,
+                "html_body": html,
+                "text_body": text,
+                "blocks_json": blocks_json,
+            }
+        )
+        return self._http.request("PATCH", f"/v1/templates/{template_id}", body)
+
+    def delete(self, template_id: str) -> None:
+        """Delete a template."""
+        return self._http.request("DELETE", f"/v1/templates/{template_id}")
+
+    def duplicate(self, template_id: str) -> Dict[str, Any]:
+        """Duplicate a template (the copy's ``blocks_json`` is not carried over)."""
+        return self._http.request("POST", f"/v1/templates/{template_id}/duplicate")

axene_mailer-0.1.0/src/axene_mailer/resources/webhooks.py

@@ -0,0 +1,61 @@
+"""The ``webhooks`` resource: manage event subscriptions and inspect
+deliveries."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._http import HttpTransport
+from .._serialize import prune, query
+
+
+class Webhooks:
+    """Accessed as ``axene.webhooks``."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    def list(self) -> List[Dict[str, Any]]:
+        """List your active webhooks."""
+        return self._http.request("GET", "/v1/webhooks/")
+
+    def create(self, url: str, events: List[str]) -> Dict[str, Any]:
+        """Create a webhook. The signing ``secret`` is generated and returned."""
+        return self._http.request("POST", "/v1/webhooks/", {"url": url, "events": events})
+
+    def update(
+        self,
+        webhook_id: str,
+        url: Optional[str] = None,
+        events: Optional[List[str]] = None,
+        is_active: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Update a webhook's url, events, or active state (partial).
+
+        ``is_active`` maps to the wire field ``is_active``.
+        """
+        body = prune({"url": url, "events": events, "is_active": is_active})
+        return self._http.request("PATCH", f"/v1/webhooks/{webhook_id}", body)
+
+    def delete(self, webhook_id: str) -> None:
+        """Delete a webhook."""
+        return self._http.request("DELETE", f"/v1/webhooks/{webhook_id}")
+
+    def test(self, webhook_id: str) -> Dict[str, Any]:
+        """Queue a sample ``email.delivered`` delivery to test the endpoint."""
+        return self._http.request("POST", f"/v1/webhooks/{webhook_id}/test")
+
+    def list_deliveries(
+        self,
+        webhook_id: str,
+        page: int = 0,
+        limit: int = 20,
+        status: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List delivery attempts for a webhook (paginated envelope)."""
+        params = {"page": page, "limit": limit, "status": status}
+        return self._http.request("GET", f"/v1/webhooks/{webhook_id}/deliveries{query(params)}")
+
+    def get_delivery(self, webhook_id: str, delivery_id: str) -> Dict[str, Any]:
+        """Fetch one delivery with its full payload and the endpoint's response."""
+        return self._http.request("GET", f"/v1/webhooks/{webhook_id}/deliveries/{delivery_id}")

axene_mailer-0.1.0/tests/test_client.py

@@ -0,0 +1,174 @@
+"""Integration-style tests against a local HTTP server (stdlib only)."""
+
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from axene_mailer import Axene, AxeneError
+
+
+class _Handler(BaseHTTPRequestHandler):
+    def _handle(self):
+        srv = self.server
+        length = int(self.headers.get("Content-Length", 0))
+        raw = self.rfile.read(length) if length else b""
+        try:
+            body = raw.decode()
+        except UnicodeDecodeError:
+            body = ""
+        srv.requests.append({
+            "method": self.command,
+            "path": self.path,
+            "auth": self.headers.get("Authorization"),
+            "content_type": self.headers.get("Content-Type"),
+            "body": body,
+            "raw": raw,
+        })
+        i = min(srv.call, len(srv.statuses) - 1)
+        srv.call += 1
+        status = srv.statuses[i]
+        payload = (srv.response if 200 <= status < 300
+                   else '{"detail":{"code":"invalid","message":"bad from"}}').encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    do_GET = _handle
+    do_POST = _handle
+    do_PUT = _handle
+    do_PATCH = _handle
+    do_DELETE = _handle
+
+    def log_message(self, *args):  # silence the test server
+        pass
+
+
+class ClientTest(unittest.TestCase):
+    def setUp(self):
+        self.server = HTTPServer(("127.0.0.1", 0), _Handler)
+        self.server.requests = []
+        self.server.statuses = [202]
+        self.server.response = '{"id":"em_1","status":"queued"}'
+        self.server.call = 0
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        self.base = f"http://127.0.0.1:{self.server.server_address[1]}"
+
+    def tearDown(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+    def client(self):
+        return Axene(api_key="axm_k_test", base_url=self.base, max_retries=3)
+
+    def test_send_maps_from_and_sets_bearer(self):
+        res = self.client().emails.send({
+            "from": {"email": "hello@shop.co", "name": "Shop"},
+            "to": "a@example.com",
+            "subject": "Hi",
+            "html": "<p>x</p>",
+        })
+        self.assertEqual(res["id"], "em_1")
+        req = self.server.requests[0]
+        self.assertEqual(req["path"], "/v1/emails/")
+        self.assertEqual(req["auth"], "Bearer axm_k_test")
+        body = json.loads(req["body"])
+        self.assertEqual(body["from_"], {"email": "hello@shop.co", "name": "Shop"})
+        self.assertNotIn("from", body)
+        self.assertEqual(body["to"], [{"email": "a@example.com"}])
+        self.assertNotIn("text", body)  # nulls pruned
+
+    def test_non_2xx_raises(self):
+        self.server.statuses = [422]
+        with self.assertRaises(AxeneError) as cm:
+            self.client().emails.send({"from": "f@x.co", "to": "a@x.co", "subject": "s"})
+        self.assertEqual(cm.exception.status, 422)
+        self.assertEqual(cm.exception.code, "invalid")
+
+    def test_retries_5xx_then_succeeds(self):
+        self.server.statuses = [503, 503, 202]
+        res = self.client().emails.send({"from": "f@x.co", "to": "a@x.co", "subject": "s"})
+        self.assertEqual(res["id"], "em_1")
+        self.assertEqual(len(self.server.requests), 3)
+
+    def test_send_batch_posts_bare_array(self):
+        self.server.response = '{"total":1,"sent":1,"failed":0,"results":[{"id":"a","status":"queued"}]}'
+        res = self.client().emails.send_batch([{"from": "f@x.co", "to": "a@x.co", "subject": "s"}])
+        self.assertEqual(res["total"], 1)
+        body = json.loads(self.server.requests[0]["body"])
+        self.assertIsInstance(body, list)  # bare array, not {"emails": [...]}
+        self.assertEqual(body[0]["from_"], {"email": "f@x.co"})
+
+    def test_validate_posts_full_message(self):
+        self.server.response = '{"valid":true,"can_send":true,"issues":[],"plan":"free","usage":{}}'
+        res = self.client().emails.validate({"from": "f@x.co", "to": "a@x.co", "subject": "s"})
+        self.assertTrue(res["can_send"])
+        self.assertEqual(self.server.requests[0]["path"], "/v1/emails/validate")
+        body = json.loads(self.server.requests[0]["body"])
+        self.assertEqual(body["from_"], {"email": "f@x.co"})  # full send body
+
+    def test_list_domains(self):
+        self.server.response = '[{"id":"d1","name":"shop.co","status":"verified"}]'
+        self.server.statuses = [200]
+        domains = self.client().domains.list()
+        self.assertEqual(domains[0]["name"], "shop.co")
+
+    def test_contacts_upload_csv_multipart(self):
+        self.server.response = '{"imported":2,"skipped":0,"errors":[]}'
+        self.server.statuses = [200]
+        res = self.client().contacts.upload_csv("lst_1", b"email\na@x.co\n", "people.csv")
+        self.assertEqual(res["imported"], 2)
+        req = self.server.requests[0]
+        self.assertEqual(req["path"], "/v1/contacts/lst_1/upload")
+        self.assertIn("multipart/form-data", req["content_type"])
+        self.assertIn("boundary=", req["content_type"])
+        # exactly one part named "file"
+        self.assertEqual(req["raw"].count(b"Content-Disposition"), 1)
+        self.assertIn(b'name="file"', req["raw"])
+        self.assertIn(b'filename="people.csv"', req["raw"])
+        self.assertIn(b"email\na@x.co\n", req["raw"])
+
+    def test_suppressions_list_envelope(self):
+        self.server.response = (
+            '{"items":[{"id":"s1","email_address":"a@x.co","reason":"manual",'
+            '"created_at":null}],"total":1,"page":0,"limit":50}'
+        )
+        self.server.statuses = [200]
+        page = self.client().suppressions.list()
+        self.assertEqual(page["total"], 1)
+        self.assertEqual(page["items"][0]["email_address"], "a@x.co")
+
+    def test_suppressions_add_maps_email_address(self):
+        self.server.response = '{"id":"s1","email_address":"a@x.co","reason":"manual"}'
+        self.server.statuses = [201]
+        self.client().suppressions.add("a@x.co")
+        body = json.loads(self.server.requests[0]["body"])
+        self.assertEqual(body["email_address"], "a@x.co")
+        self.assertNotIn("email", body)
+        self.assertEqual(body["reason"], "manual")
+
+    def test_templates_create_maps_html_body(self):
+        self.server.response = '{"id":"tpl_1","name":"Welcome","html_body":"<p>hi</p>"}'
+        self.server.statuses = [201]
+        self.client().templates.create(name="Welcome", html="<p>hi</p>", text="hi")
+        body = json.loads(self.server.requests[0]["body"])
+        self.assertEqual(body["html_body"], "<p>hi</p>")
+        self.assertEqual(body["text_body"], "hi")
+        self.assertNotIn("html", body)
+        self.assertNotIn("text", body)
+
+    def test_webhooks_update_maps_is_active(self):
+        self.server.response = '{"id":"wh_1","url":"https://x.co/h","events":[],"is_active":false}'
+        self.server.statuses = [200]
+        self.client().webhooks.update("wh_1", is_active=False)
+        req = self.server.requests[0]
+        self.assertEqual(req["method"], "PATCH")
+        body = json.loads(req["body"])
+        self.assertEqual(body["is_active"], False)
+        self.assertNotIn("isActive", body)
+
+
+if __name__ == "__main__":
+    unittest.main()