supersendtx 0.8.2__tar.gz

supersendtx-0.8.2/.gitignore

@@ -0,0 +1,5 @@
+/dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+/build/

supersendtx-0.8.2/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: supersendtx
+Version: 0.8.2
+Summary: SuperSend TX transactional email API client for Python
+Project-URL: Homepage, https://supersendtx.com
+Project-URL: Documentation, https://docs.supersendtx.com/sdks/python
+Project-URL: Repository, https://github.com/Super-Send/supersendtx-sdks
+Project-URL: Issues, https://github.com/Super-Send/supersendtx-sdks/issues
+Author: SuperSend TX
+License-Expression: MIT
+Keywords: email,supersend,supersendtx,transactional
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SuperSend TX Python SDK
+
+Official Python client for the [SuperSend TX](https://supersendtx.com) transactional email API.
+
+```bash
+pip install supersendtx
+```
+
+```python
+from supersendtx import SuperSendTX
+
+tx = SuperSendTX("stx_your_key_here")
+
+result = tx.emails.send(
+    from_="you@yourdomain.com",
+    to="user@example.com",
+    subject="Hello",
+    html="<p>It works.</p>",
+)
+
+print(result["id"], result["status"])
+```
+
+Docs: https://docs.supersendtx.com/sdks/python

supersendtx-0.8.2/README.md

@@ -0,0 +1,24 @@
+# SuperSend TX Python SDK
+
+Official Python client for the [SuperSend TX](https://supersendtx.com) transactional email API.
+
+```bash
+pip install supersendtx
+```
+
+```python
+from supersendtx import SuperSendTX
+
+tx = SuperSendTX("stx_your_key_here")
+
+result = tx.emails.send(
+    from_="you@yourdomain.com",
+    to="user@example.com",
+    subject="Hello",
+    html="<p>It works.</p>",
+)
+
+print(result["id"], result["status"])
+```
+
+Docs: https://docs.supersendtx.com/sdks/python

supersendtx-0.8.2/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "supersendtx"
+version = "0.8.2"
+description = "SuperSend TX transactional email API client for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "SuperSend TX" }]
+keywords = ["email", "transactional", "supersend", "supersendtx"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://supersendtx.com"
+Documentation = "https://docs.supersendtx.com/sdks/python"
+Repository = "https://github.com/Super-Send/supersendtx-sdks"
+Issues = "https://github.com/Super-Send/supersendtx-sdks/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["supersendtx"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

supersendtx-0.8.2/supersendtx/__init__.py

@@ -0,0 +1,7 @@
+"""SuperSend TX Python SDK — transactional email API client."""
+
+from supersendtx.client import SuperSendTX
+from supersendtx.errors import SuperSendTXError
+
+__all__ = ["SuperSendTX", "SuperSendTXError"]
+DEFAULT_API_BASE_URL = "https://api.supersendtx.com"

supersendtx-0.8.2/supersendtx/client.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from supersendtx.errors import SuperSendTXError
+from supersendtx.http import HttpClient
+from supersendtx.resources import (
+    DomainsResource,
+    EmailsResource,
+    SuppressionsResource,
+    TemplatesResource,
+    WebhooksResource,
+)
+
+DEFAULT_API_BASE_URL = "https://api.supersendtx.com"
+
+
+class SuperSendTX:
+    """Thin HTTP client for the SuperSend TX REST API."""
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_API_BASE_URL) -> None:
+        self._http = HttpClient(api_key, base_url=base_url)
+        self.emails = EmailsResource(self._http)
+        self.domains = DomainsResource(self._http)
+        self.webhooks = WebhooksResource(self._http)
+        self.templates = TemplatesResource(self._http)
+        self.suppressions = SuppressionsResource(self._http)
+
+    def request(self, method: str, path: str, *, body: Any = None, headers: dict[str, str] | None = None) -> Any:
+        return self._http.request(method, path, body=body, headers=headers)

supersendtx-0.8.2/supersendtx/errors.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class SuperSendTXError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        *,
+        details: Any = None,
+        code: str | None = None,
+        upgrade_url: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.details = details
+        self.code = code
+        self.upgrade_url = upgrade_url
+
+    @classmethod
+    def from_response(cls, status: int, body: Any) -> SuperSendTXError:
+        err = body.get("error") if isinstance(body, dict) else None
+        if isinstance(err, str):
+            message = err
+            details = None
+            code = None
+            upgrade_url = None
+        elif isinstance(err, dict):
+            message = str(err.get("message") or f"Request failed with status {status}")
+            details = err.get("details")
+            code = str(err["code"]) if err.get("code") is not None else None
+            upgrade_url = str(err["upgrade_url"]) if err.get("upgrade_url") is not None else None
+        else:
+            message = f"Request failed with status {status}"
+            details = None
+            code = None
+            upgrade_url = None
+        return cls(message, status, details=details, code=code, upgrade_url=upgrade_url)

supersendtx-0.8.2/supersendtx/http.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from supersendtx.errors import SuperSendTXError
+
+
+class HttpClient:
+    def __init__(self, api_key: str, *, base_url: str = "https://api.supersendtx.com") -> None:
+        if not api_key.startswith("stx_"):
+            raise ValueError("SuperSend TX API key must start with stx_")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        payload = None
+        req_headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            **(headers or {}),
+        }
+        if body is not None:
+            payload = json.dumps(body).encode("utf-8")
+        request = urllib.request.Request(url, data=payload, headers=req_headers, method=method)
+        try:
+            with urllib.request.urlopen(request) as response:
+                raw = response.read().decode("utf-8")
+                if not raw:
+                    return {}
+                return json.loads(raw)
+        except urllib.error.HTTPError as error:
+            raw = error.read().decode("utf-8")
+            try:
+                parsed = json.loads(raw)
+            except json.JSONDecodeError:
+                parsed = {}
+            raise SuperSendTXError.from_response(error.code, parsed) from error
+
+    @staticmethod
+    def query(params: dict[str, Any]) -> str:
+        filtered = {key: value for key, value in params.items() if value is not None}
+        if not filtered:
+            return ""
+        return "?" + urllib.parse.urlencode(filtered)

supersendtx-0.8.2/supersendtx/resources.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from typing import Any
+
+from supersendtx.http import HttpClient
+
+
+class EmailsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, *, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]:
+        return self._http.request("GET", f"/emails{self._http.query({'limit': limit, 'cursor': cursor})}")
+
+    def get(self, email_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/emails/{email_id}")
+
+    def send(
+        self,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+        **params: Any,
+    ) -> dict[str, Any]:
+        if from_ is not None:
+            params["from"] = from_
+        if to is not None:
+            params["to"] = to
+        body = _serialize_send_params(params)
+        headers: dict[str, str] = {}
+        idempotency_key = params.get("idempotency_key") or params.get("idempotencyKey")
+        if idempotency_key:
+            headers["Idempotency-Key"] = str(idempotency_key)
+        return self._http.request("POST", "/emails", body=body, headers=headers)
+
+    def batch(self, emails: list[dict[str, Any]]) -> dict[str, Any]:
+        serialized = [_serialize_send_params(email) for email in emails]
+        return self._http.request("POST", "/emails/batch", body={"emails": serialized})
+
+    def cancel(self, email_id: str) -> dict[str, Any]:
+        return self._http.request("PATCH", f"/emails/{email_id}", body={"cancel": True})
+
+    def resend(self, email_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/emails/{email_id}/resend")
+
+    def test_webhook(self, **params: Any) -> dict[str, Any]:
+        return self._http.request("POST", "/emails/test", body=params)
+
+    def insights(self, *, window: str = "30d") -> dict[str, Any]:
+        return self._http.request("GET", f"/deliverability{self._http.query({'window': window})}")
+
+
+class DomainsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        inbound_enabled: bool | None = None,
+    ) -> dict[str, Any]:
+        return self._http.request(
+            "GET",
+            f"/domains{self._http.query({'limit': limit, 'cursor': cursor, 'inbound_enabled': inbound_enabled})}",
+        )
+
+    def get(self, id_or_name: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/domains/{id_or_name}")
+
+    def create(self, name: str, *, inbound_enabled: bool | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name}
+        if inbound_enabled is not None:
+            body["inbound_enabled"] = inbound_enabled
+        return self._http.request("POST", "/domains", body=body)
+
+    def verify(self, id_or_name: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/domains/{id_or_name}", body={"action": "verify"})
+
+    def apply(
+        self,
+        id_or_name: str,
+        *,
+        provider: str = "cloudflare",
+        credentials: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"action": "apply", "provider": provider}
+        if credentials:
+            body["credentials"] = credentials
+        return self._http.request("POST", f"/domains/{id_or_name}", body=body)
+
+    def update(self, id_or_name: str, **params: Any) -> dict[str, Any]:
+        return self._http.request("PATCH", f"/domains/{id_or_name}", body=params)
+
+    def delete(self, id_or_name: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/domains/{id_or_name}")
+
+
+class WebhooksResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, *, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]:
+        return self._http.request(
+            "GET",
+            f"/webhooks{self._http.query({'limit': limit, 'cursor': cursor})}",
+        )
+
+    def get(self, webhook_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/webhooks/{webhook_id}")
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        return self._http.request("POST", "/webhooks", body=params)
+
+    def update(self, webhook_id: str, **params: Any) -> dict[str, Any]:
+        return self._http.request("PATCH", f"/webhooks/{webhook_id}", body=params)
+
+    def delete(self, webhook_id: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/webhooks/{webhook_id}")
+
+
+class TemplatesResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        status: str | None = None,
+    ) -> dict[str, Any]:
+        return self._http.request(
+            "GET",
+            f"/templates{self._http.query({'limit': limit, 'cursor': cursor, 'status': status})}",
+        )
+
+    def get(self, id_or_alias: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/templates/{id_or_alias}")
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        return self._http.request("POST", "/templates", body=params)
+
+    def update(self, id_or_alias: str, **params: Any) -> dict[str, Any]:
+        return self._http.request("PATCH", f"/templates/{id_or_alias}", body=params)
+
+    def delete(self, id_or_alias: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/templates/{id_or_alias}")
+
+    def publish(self, id_or_alias: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/templates/{id_or_alias}", body={"action": "publish"})
+
+
+class SuppressionsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        email: str | None = None,
+    ) -> dict[str, Any]:
+        return self._http.request(
+            "GET",
+            f"/suppressions{self._http.query({'limit': limit, 'cursor': cursor, 'email': email})}",
+        )
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        return self._http.request("POST", "/suppressions", body=params)
+
+    def remove(self, id_or_email: str) -> dict[str, Any]:
+        if "@" in id_or_email:
+            return self._http.request("DELETE", f"/suppressions{self._http.query({'email': id_or_email})}")
+        return self._http.request("DELETE", f"/suppressions/{id_or_email}")
+
+
+def _serialize_send_params(params: dict[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "from": params["from"],
+        "to": params["to"],
+    }
+    for key in ("subject", "html", "text", "reply_to", "replyTo", "cc", "bcc", "tags", "headers", "tag", "template"):
+        if key in params and params[key] is not None:
+            mapped = "reply_to" if key == "replyTo" else key
+            body[mapped] = params[key]
+    if params.get("htmlBody") is not None:
+        body["html"] = params["htmlBody"]
+    if params.get("textBody") is not None:
+        body["text"] = params["textBody"]
+    if params.get("scheduled_at") is not None:
+        body["scheduled_at"] = params["scheduled_at"]
+    if params.get("scheduledAt") is not None:
+        body["scheduled_at"] = params["scheduledAt"]
+    if params.get("unsubscribe") is not None:
+        body["unsubscribe"] = params["unsubscribe"]
+    return body

supersendtx-0.8.2/tests/test_client.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from supersendtx import SuperSendTX
+from supersendtx.errors import SuperSendTXError
+
+
+@pytest.fixture
+def client() -> SuperSendTX:
+    return SuperSendTX("stx_test_key", base_url="https://api.example.com")
+
+
+def test_requires_stx_prefix() -> None:
+    with pytest.raises(ValueError, match="stx_"):
+        SuperSendTX("bad")
+
+
+def test_emails_send(client: SuperSendTX) -> None:
+    response = MagicMock()
+    response.read.return_value = json.dumps({"id": "msg_1", "status": "sent"}).encode()
+    response.__enter__.return_value = response
+
+    with patch("urllib.request.urlopen", return_value=response) as urlopen:
+        result = client.emails.send(
+            from_="a@example.com",
+            to="b@example.com",
+            subject="Hi",
+            html="<p>Hi</p>",
+        )
+
+    assert result == {"id": "msg_1", "status": "sent"}
+    request = urlopen.call_args.args[0]
+    assert request.full_url == "https://api.example.com/emails"
+    assert request.method == "POST"
+    assert request.get_header("Authorization") == "Bearer stx_test_key"
+
+
+def test_http_error_raises_super_send_tx_error(client: SuperSendTX) -> None:
+    import urllib.error
+
+    payload = json.dumps({"error": {"message": "Invalid API key"}}).encode()
+    http_error = urllib.error.HTTPError(
+        url="https://api.example.com/emails",
+        code=401,
+        msg="Unauthorized",
+        hdrs=None,
+        fp=MagicMock(read=MagicMock(return_value=payload)),
+    )
+
+    with patch("urllib.request.urlopen", side_effect=http_error):
+        with pytest.raises(SuperSendTXError) as exc:
+            client.emails.send(
+                from_="a@example.com",
+                to="b@example.com",
+                subject="Hi",
+                html="<p>Hi</p>",
+            )
+
+    assert exc.value.status == 401
+    assert exc.value.message == "Invalid API key"