mailtruss 0.1.0__py3-none-any.whl

mailtruss/__init__.py

@@ -0,0 +1,217 @@
+"""Mailtruss API client. Standard library only.
+
+    from mailtruss import Mailtruss
+    m = Mailtruss(api_key="ms_live_...")
+    m.emails.send(from_="Ada <ada@yourdomain.com>", to="you@example.com", subject="Hi", html="<p>Hello</p>")
+
+Python keywords are suffixed with an underscore (`from_`); the suffix is removed before the request is sent.
+Retries (429 and 5xx) happen only for reads, deletes, or sends made with an idempotency key, so a send is never repeated by accident.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Optional
+
+__all__ = ["Mailtruss", "MailtrussError", "MailtrussTimeout"]
+__version__ = "0.1.0"
+
+
+class MailtrussError(Exception):
+    """Any non-2xx response. `request_id` can be searched in the dashboard's API logs."""
+
+    def __init__(self, status: int, name: str, message: str, request_id: Optional[str] = None, retry_after: Optional[float] = None):
+        super().__init__(message)
+        self.status, self.name, self.message, self.request_id, self.retry_after = status, name, message, request_id, retry_after
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        rid = f", request {self.request_id}" if self.request_id else ""
+        return f"{self.message} ({self.status} {self.name}{rid})"
+
+
+class MailtrussTimeout(Exception):
+    pass
+
+
+def _clean(body: Any) -> Any:
+    """`from_` -> `from`, and drop None values so optional arguments are simply omitted."""
+    if isinstance(body, dict):
+        return {(k[:-1] if k.endswith("_") and k[:-1] in ("from", "import", "global") else k): _clean(v) for k, v in body.items() if v is not None}
+    if isinstance(body, list):
+        return [_clean(v) for v in body]
+    return body
+
+
+class _Resource:
+    def __init__(self, c: "Mailtruss"):
+        self._c = c
+
+    def _q(self, **params: Any) -> str:
+        items = [(k, str(v)) for k, v in params.items() if v is not None and v != ""]
+        return "?" + urllib.parse.urlencode(items) if items else ""
+
+    @staticmethod
+    def _id(v: str) -> str:
+        return urllib.parse.quote(v, safe="")
+
+
+class _Emails(_Resource):
+    def send(self, *, idempotency_key: Optional[str] = None, **p: Any) -> dict:
+        return self._c.request("POST", "/api/v1/emails", p, idempotency_key=idempotency_key)
+
+    def batch(self, emails: list, *, idempotency_key: Optional[str] = None) -> dict:
+        return self._c.request("POST", "/api/v1/emails/batch", emails, idempotency_key=idempotency_key)
+
+    def get(self, id: str) -> dict:
+        return self._c.request("GET", f"/api/v1/emails/{self._id(id)}")
+
+    def list(self, limit: Optional[int] = None, after: Optional[str] = None) -> dict:
+        return self._c.request("GET", "/api/v1/emails" + self._q(limit=limit, after=after))
+
+    def reschedule(self, id: str, scheduled_at: str) -> dict:
+        return self._c.request("PATCH", f"/api/v1/emails/{self._id(id)}", {"scheduled_at": scheduled_at})
+
+    def cancel(self, id: str) -> dict:
+        return self._c.request("POST", f"/api/v1/emails/{self._id(id)}/cancel")
+
+
+class _Domains(_Resource):
+    def create(self, **p: Any) -> dict: return self._c.request("POST", "/api/v1/domains", p)
+    def list(self) -> dict: return self._c.request("GET", "/api/v1/domains")
+    def get(self, id: str) -> dict: return self._c.request("GET", f"/api/v1/domains/{self._id(id)}")
+    def verify(self, id: str) -> dict: return self._c.request("POST", f"/api/v1/domains/{self._id(id)}/verify")
+    def set_tracking(self, id: str, *, click_tracking: Optional[bool] = None, open_tracking: Optional[bool] = None) -> dict:
+        """Both are off by default. Tell your recipients before turning them on."""
+        return self._c.request("PATCH", f"/api/v1/domains/{self._id(id)}", {"click_tracking": click_tracking, "open_tracking": open_tracking})
+    def remove(self, id: str) -> dict: return self._c.request("DELETE", f"/api/v1/domains/{self._id(id)}")
+
+
+class _ApiKeys(_Resource):
+    def create(self, **p: Any) -> dict: return self._c.request("POST", "/api/v1/api-keys", p)
+    def list(self) -> dict: return self._c.request("GET", "/api/v1/api-keys")
+    def remove(self, id: str) -> dict: return self._c.request("DELETE", f"/api/v1/api-keys/{self._id(id)}")
+
+
+class _Contacts(_Resource):
+    def create(self, **p: Any) -> dict: return self._c.request("POST", "/api/v1/contacts", p)
+    def get(self, id_or_email: str) -> dict: return self._c.request("GET", f"/api/v1/contacts/{self._id(id_or_email)}")
+    def list(self, *, q: Optional[str] = None, tag: Optional[str] = None, status: Optional[str] = None, page: Optional[int] = None, limit: Optional[int] = None) -> dict:
+        return self._c.request("GET", "/api/v1/contacts" + self._q(q=q, tag=tag, status=status, page=page, limit=limit))
+    def update(self, id_or_email: str, **p: Any) -> dict: return self._c.request("PATCH", f"/api/v1/contacts/{self._id(id_or_email)}", p)
+    def remove(self, id_or_email: str) -> dict: return self._c.request("DELETE", f"/api/v1/contacts/{self._id(id_or_email)}")
+
+
+class _Segments(_Resource):
+    def create(self, **p: Any) -> dict: return self._c.request("POST", "/api/v1/segments", p)
+    def list(self) -> dict: return self._c.request("GET", "/api/v1/segments")
+    def get(self, id: str) -> dict: return self._c.request("GET", f"/api/v1/segments/{self._id(id)}")
+    def remove(self, id: str) -> dict: return self._c.request("DELETE", f"/api/v1/segments/{self._id(id)}")
+
+
+class _Topics(_Resource):
+    def create(self, **p: Any) -> dict: return self._c.request("POST", "/api/v1/topics", p)
+    def list(self) -> dict: return self._c.request("GET", "/api/v1/topics")
+
+
+class _Suppressions(_Resource):
+    def add(self, email: str) -> dict: return self._c.request("POST", "/api/v1/suppressions", {"email": email})
+    def list(self, *, q: Optional[str] = None, reason: Optional[str] = None, page: Optional[int] = None, limit: Optional[int] = None) -> dict:
+        return self._c.request("GET", "/api/v1/suppressions" + self._q(q=q, reason=reason, page=page, limit=limit))
+    def remove(self, id_or_email: str) -> dict:
+        """Complaints and unsubscribes cannot be removed (403)."""
+        return self._c.request("DELETE", f"/api/v1/suppressions/{self._id(id_or_email)}")
+
+
+class _Webhooks(_Resource):
+    def create(self, **p: Any) -> dict:
+        """The signing secret is returned once, here and from rotate_secret."""
+        return self._c.request("POST", "/api/v1/webhooks", p)
+    def list(self) -> dict: return self._c.request("GET", "/api/v1/webhooks")
+    def get(self, id: str) -> dict: return self._c.request("GET", f"/api/v1/webhooks/{self._id(id)}")
+    def update(self, id: str, **p: Any) -> dict: return self._c.request("PATCH", f"/api/v1/webhooks/{self._id(id)}", p)
+    def rotate_secret(self, id: str) -> dict: return self._c.request("POST", f"/api/v1/webhooks/{self._id(id)}/rotate-secret")
+    def remove(self, id: str) -> dict: return self._c.request("DELETE", f"/api/v1/webhooks/{self._id(id)}")
+
+
+class _Templates(_Resource):
+    def create(self, **p: Any) -> dict: return self._c.request("POST", "/api/v1/templates", p)
+    def list(self) -> dict: return self._c.request("GET", "/api/v1/templates")
+    def get(self, id: str) -> dict: return self._c.request("GET", f"/api/v1/templates/{self._id(id)}")
+    def update(self, id: str, **p: Any) -> dict:
+        """Saves a new, unpublished version."""
+        return self._c.request("PATCH", f"/api/v1/templates/{self._id(id)}", p)
+    def publish(self, id: str, version: Optional[int] = None) -> dict: return self._c.request("POST", f"/api/v1/templates/{self._id(id)}/publish", {"version": version})
+    def remove(self, id: str) -> dict: return self._c.request("DELETE", f"/api/v1/templates/{self._id(id)}")
+
+
+class _Broadcasts(_Resource):
+    def create(self, **p: Any) -> dict:
+        """Creates a draft. Nothing is sent until send()."""
+        return self._c.request("POST", "/api/v1/broadcasts", p)
+    def list(self) -> dict: return self._c.request("GET", "/api/v1/broadcasts")
+    def get(self, id: str) -> dict: return self._c.request("GET", f"/api/v1/broadcasts/{self._id(id)}")
+    def send(self, id: str, scheduled_at: Optional[str] = None) -> dict: return self._c.request("POST", f"/api/v1/broadcasts/{self._id(id)}/send", {"scheduled_at": scheduled_at})
+    def cancel(self, id: str) -> dict: return self._c.request("POST", f"/api/v1/broadcasts/{self._id(id)}/cancel")
+    def remove(self, id: str) -> dict: return self._c.request("DELETE", f"/api/v1/broadcasts/{self._id(id)}")
+
+
+class _Logs(_Resource):
+    def list(self, limit: Optional[int] = None, after: Optional[str] = None) -> dict:
+        return self._c.request("GET", "/api/v1/logs" + self._q(limit=limit, after=after))
+
+
+class Mailtruss:
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 30.0, max_retries: int = 2,
+                 opener: Optional[Callable[..., Any]] = None, sleep: Callable[[float], None] = time.sleep):
+        key = api_key or os.environ.get("MAILTRUSS_API_KEY")
+        if not key:
+            raise ValueError("An API key is required (pass api_key or set MAILTRUSS_API_KEY).")
+        self._key, self.timeout, self.max_retries, self._sleep = key, timeout, max_retries, sleep
+        self.base_url = (base_url or os.environ.get("MAILTRUSS_API_URL") or "https://mailtruss.com").rstrip("/")
+        self._open = opener or urllib.request.urlopen
+        self.emails, self.domains, self.api_keys = _Emails(self), _Domains(self), _ApiKeys(self)
+        self.contacts, self.segments, self.topics = _Contacts(self), _Segments(self), _Topics(self)
+        self.suppressions, self.webhooks, self.templates = _Suppressions(self), _Webhooks(self), _Templates(self)
+        self.broadcasts, self.logs = _Broadcasts(self), _Logs(self)
+
+    def request(self, method: str, path: str, body: Any = None, *, idempotency_key: Optional[str] = None) -> Any:
+        retryable = bool(idempotency_key) or method in ("GET", "DELETE")
+        headers = {"Authorization": f"Bearer {self._key}", "Content-Type": "application/json", "User-Agent": f"mailtruss-python/{__version__}"}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        data = None if body is None else json.dumps(_clean(body)).encode()
+        attempt = 0
+        while True:
+            req = urllib.request.Request(self.base_url + path, data=data, method=method, headers=headers)
+            try:
+                with self._open(req, timeout=self.timeout) as r:
+                    raw = r.read()
+                    return json.loads(raw) if raw else None
+            except urllib.error.HTTPError as e:
+                payload: Dict[str, Any] = {}
+                try:
+                    payload = json.loads(e.read() or b"{}")
+                except Exception:
+                    pass
+                retry_after = None
+                try:
+                    retry_after = float(e.headers.get("retry-after")) if e.headers.get("retry-after") else None
+                except (TypeError, ValueError):
+                    pass
+                if retryable and attempt < self.max_retries and (e.code == 429 or e.code >= 500):
+                    self._sleep(retry_after if retry_after is not None else 2 ** attempt)
+                    attempt += 1
+                    continue
+                raise MailtrussError(e.code, payload.get("name", "application_error"), payload.get("message", str(e.reason)), e.headers.get("x-request-id"), retry_after) from None
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                if isinstance(getattr(e, "reason", e), TimeoutError) or isinstance(e, TimeoutError):
+                    raise MailtrussTimeout(f"Request timed out after {self.timeout}s. The email may still have been sent; check the dashboard before retrying.") from None
+                if retryable and attempt < self.max_retries:
+                    self._sleep(0.5 * 2 ** attempt)
+                    attempt += 1
+                    continue
+                raise

mailtruss-0.1.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: mailtruss
+Version: 0.1.0
+Summary: Python client for the Mailtruss email API (no dependencies)
+Author-email: Mailtruss <hello@mailtruss.com>
+License-Expression: MIT
+Project-URL: Homepage, https://mailtruss.com
+Project-URL: Documentation, https://mailtruss.com/docs
+Keywords: email,transactional-email,email-api,mailtruss
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mailtruss (Python)
+
+Python client for the [Mailtruss](https://mailtruss.com) email API. `pip install mailtruss`.
+
+No dependencies. Python 3.9+.
+
+```python
+from mailtruss import Mailtruss
+m = Mailtruss(api_key="ms_live_…")          # or set MAILTRUSS_API_KEY
+m.emails.send(from_="Ada <ada@yourdomain.com>", to="you@example.com", subject="Hi", html="<p>Hello</p>", idempotency_key="order-42")
+m.contacts.create(email="ann@example.com", first_name="Ann", tags=["beta"])
+m.broadcasts.create(name="News", from_="news@yourdomain.com", subject="Hello", html="<p>…</p>")
+```
+
+Every resource of the HTTP API is covered (see `/api/v1/openapi.json`). `from_` is sent as `from`. A send is retried only when you pass an `idempotency_key`; reads and deletes retry on 429 and 5xx.
+
+Run the tests: `python3 -m unittest discover -s tests` from this folder.

mailtruss-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mailtruss/__init__.py,sha256=61QKlOuQcAD0YwhrGpigvcVddV0qWoeTK01eWSB7zZE,12178
+mailtruss/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mailtruss-0.1.0.dist-info/licenses/LICENSE,sha256=3GEnv7fYwmEQSObwRXstmMOtY7WcFMqp-HLf1pIapdU,1066
+mailtruss-0.1.0.dist-info/METADATA,sha256=A-hUDrVCMOav-NcVnqqZZLSXgQiRem7IHzq4mdWAdus,1557
+mailtruss-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mailtruss-0.1.0.dist-info/top_level.txt,sha256=6EJrUXlkXEWKAC-xAmbyrG41lmAkdQdpayrw92msDfI,10
+mailtruss-0.1.0.dist-info/RECORD,,

mailtruss-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mailtruss-0.1.0.dist-info/licenses/LICENSE

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

mailtruss-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mailtruss