utobo-email 1.0.0__tar.gz

utobo_email-1.0.0/.gitignore

@@ -0,0 +1,39 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+**/.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Vite temp files
+vite.config.ts.timestamp-*.mjs
+dist/robots.txt
+node_modules/
+.gstack/
+
+# Local Claude settings (do not commit)
+.claude/settings.local.json

utobo_email-1.0.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: utobo-email
+Version: 1.0.0
+Summary: Official Python SDK for the utobo email Email Platform
+Project-URL: Homepage, https://utobo.com/email
+Project-URL: Documentation, https://utobo.com/email/docs
+Project-URL: Repository, https://github.com/myutobo/utobo-email-python
+Project-URL: Issues, https://github.com/myutobo/utobo-email-python/issues
+Author-email: Utobo <hello@mail.utobo.com>
+License-Expression: MIT
+Keywords: api,email,sdk,transactional,utobo
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# utobo-email
+
+Official Python SDK for the [utobo email](https://utobo.com/email) email platform.
+
+## Install
+
+```bash
+pip install utobo-email
+```
+
+## Quickstart
+
+```python
+from utobo_email import UtoboEmail
+
+client = UtoboEmail("av_live_...")
+
+result = client.emails.send(
+    from_="Acme <noreply@acme.com>",
+    to="user@example.com",
+    subject="Welcome!",
+    html="<p>Welcome to Acme!</p>",
+)
+print(result["id"])
+```
+
+## Check delivery status
+
+```python
+status = client.emails.get("3c9b0f4e-...")
+print(status["status"])  # "sent" | "failed"
+```
+
+## Configuration
+
+| Option | Env var | Default |
+|--------|---------|---------|
+| `api_key` | `UTOBO_EMAIL_API_KEY` | — (required) |
+| `base_url` | `UTOBO_EMAIL_BASE_URL` | `https://api.email.utobo.com/v1` |
+
+## License
+
+MIT

utobo_email-1.0.0/README.md

@@ -0,0 +1,43 @@
+# utobo-email
+
+Official Python SDK for the [utobo email](https://utobo.com/email) email platform.
+
+## Install
+
+```bash
+pip install utobo-email
+```
+
+## Quickstart
+
+```python
+from utobo_email import UtoboEmail
+
+client = UtoboEmail("av_live_...")
+
+result = client.emails.send(
+    from_="Acme <noreply@acme.com>",
+    to="user@example.com",
+    subject="Welcome!",
+    html="<p>Welcome to Acme!</p>",
+)
+print(result["id"])
+```
+
+## Check delivery status
+
+```python
+status = client.emails.get("3c9b0f4e-...")
+print(status["status"])  # "sent" | "failed"
+```
+
+## Configuration
+
+| Option | Env var | Default |
+|--------|---------|---------|
+| `api_key` | `UTOBO_EMAIL_API_KEY` | — (required) |
+| `base_url` | `UTOBO_EMAIL_BASE_URL` | `https://api.email.utobo.com/v1` |
+
+## License
+
+MIT

utobo_email-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "utobo-email"
+version = "1.0.0"
+description = "Official Python SDK for the utobo email Email Platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [{ name = "Utobo", email = "hello@mail.utobo.com" }]
+keywords = ["utobo", "email", "api", "sdk", "transactional"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+    "Topic :: Communications :: Email",
+]
+dependencies = ["httpx>=0.24.0"]
+
+[project.urls]
+Homepage = "https://utobo.com/email"
+Documentation = "https://utobo.com/email/docs"
+Repository = "https://github.com/myutobo/utobo-email-python"
+Issues = "https://github.com/myutobo/utobo-email-python/issues"

utobo_email-1.0.0/utobo_email/__init__.py

@@ -0,0 +1,5 @@
+from .client import UtoboEmail
+from .exceptions import UtoboEmailError, ApiError, NetworkError
+
+__all__ = ["UtoboEmail", "UtoboEmailError", "ApiError", "NetworkError"]
+__version__ = "1.0.0"

utobo_email-1.0.0/utobo_email/client.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .emails import Emails
+from .exceptions import ApiError, NetworkError
+
+DEFAULT_BASE_URL = "https://api.email.utobo.com/v1"
+SDK_VERSION = "1.0.0"
+
+
+class UtoboEmail:
+    """utobo email Python SDK client.
+
+    Usage:
+        from utobo_email import UtoboEmail
+
+        client = UtoboEmail("av_live_...")
+        result = client.emails.send(
+            from_="Acme <noreply@acme.com>",
+            to="user@example.com",
+            subject="Welcome!",
+            html="<p>Welcome to Acme!</p>",
+        )
+        print(result["id"])
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+    ):
+        resolved_key = api_key or os.environ.get("UTOBO_EMAIL_API_KEY") or os.environ.get("UTOBO_MAIL_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "Missing API key. "
+                'Pass it to the constructor `UtoboEmail("av_live_...")` '
+                "or set the UTOBO_EMAIL_API_KEY environment variable."
+            )
+
+        self._api_key = resolved_key
+        self._base_url = (
+            base_url
+            or os.environ.get("UTOBO_EMAIL_BASE_URL")
+            or os.environ.get("UTOBO_MAIL_BASE_URL")
+            or DEFAULT_BASE_URL
+        )
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"utobo-email-python/{SDK_VERSION}",
+            },
+            timeout=30.0,
+        )
+
+        self.emails = Emails(self)
+
+    def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        try:
+            resp = self._http.post(path, json=body)
+        except httpx.HTTPError as e:
+            raise NetworkError(str(e)) from e
+
+        if not resp.is_success:
+            self._raise_api_error(resp)
+        return resp.json()
+
+    def _get(self, path: str) -> Dict[str, Any]:
+        try:
+            resp = self._http.get(path)
+        except httpx.HTTPError as e:
+            raise NetworkError(str(e)) from e
+
+        if not resp.is_success:
+            self._raise_api_error(resp)
+        return resp.json()
+
+    def _raise_api_error(self, resp: httpx.Response) -> None:
+        try:
+            data = resp.json()
+            raise ApiError(
+                status_code=resp.status_code,
+                name=data.get("name", "api_error"),
+                message=data.get("message", resp.reason_phrase or "Request failed"),
+            )
+        except (ValueError, KeyError):
+            raise ApiError(
+                status_code=resp.status_code,
+                name="api_error",
+                message=resp.reason_phrase or "Request failed",
+            )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "UtoboEmail":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

utobo_email-1.0.0/utobo_email/emails.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from .exceptions import ApiError, NetworkError
+
+if False:  # TYPE_CHECKING
+    from .client import UtoboEmail
+
+
+class Emails:
+    def __init__(self, client: "UtoboEmail"):
+        self._client = client
+
+    def send(
+        self,
+        *,
+        from_: str,
+        to: Union[str, List[str]],
+        subject: str,
+        html: Optional[str] = None,
+        text: Optional[str] = None,
+        reply_to: Optional[Union[str, List[str]]] = None,
+        cc: Optional[Union[str, List[str]]] = None,
+        bcc: Optional[Union[str, List[str]]] = None,
+        attachments: Optional[List[Dict[str, Any]]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Send a transactional email.
+
+        Returns dict with 'id' and 'message' on success.
+        Raises ApiError or NetworkError on failure.
+
+        Each attachment dict requires 'filename' and 'content' (base64 string),
+        and an optional 'contentType'.
+        """
+        body: Dict[str, Any] = {
+            "from": from_,
+            "to": [to] if isinstance(to, str) else to,
+            "subject": subject,
+        }
+        if html is not None:
+            body["html"] = html
+        if text is not None:
+            body["text"] = text
+        if reply_to is not None:
+            body["reply_to"] = [reply_to] if isinstance(reply_to, str) else reply_to
+        if cc is not None:
+            body["cc"] = [cc] if isinstance(cc, str) else cc
+        if bcc is not None:
+            body["bcc"] = [bcc] if isinstance(bcc, str) else bcc
+        if attachments is not None:
+            body["attachments"] = attachments
+        if headers is not None:
+            body["headers"] = headers
+
+        return self._client._post("/send-email", body)
+
+    def get(self, email_id: str) -> Dict[str, Any]:
+        """Retrieve the status of a previously sent email."""
+        return self._client._get(f"/send-email/{email_id}")

utobo_email-1.0.0/utobo_email/exceptions.py

@@ -0,0 +1,16 @@
+class UtoboEmailError(Exception):
+    pass
+
+
+class ApiError(UtoboEmailError):
+    def __init__(self, status_code: int, name: str, message: str):
+        self.status_code = status_code
+        self.name = name
+        self.message = message
+        super().__init__(f"{name} ({status_code}): {message}")
+
+
+class NetworkError(UtoboEmailError):
+    def __init__(self, message: str = "Unable to reach the utobo email API"):
+        self.message = message
+        super().__init__(message)