usend 1.0.0__tar.gz

usend-1.0.0/.gitignore

@@ -0,0 +1,34 @@
+# Secrets / local config
+deploy/.env
+deploy/.env.*
+!deploy/.env.example
+!deploy/.env.test
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Go
+backend/bin/
+backend/dist/
+backend/tmp/
+backend/**/*.test
+*.out
+coverage*.txt
+coverage*.html
+
+# Web
+web/node_modules/
+web/dist/
+web/dist-docs/
+web/dist-landing/
+web/.vite/
+node_modules/
+npm-debug.log*
+
+# Backups and local artifacts
+*.sql.gz
+backups/
+backend/dist-linux/

usend-1.0.0/LICENSE

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

usend-1.0.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: usend
+Version: 1.0.0
+Summary: The official Python SDK for usend, the email API for developers.
+Project-URL: Homepage, https://usend.et
+Project-URL: Documentation, https://usend.et/docs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email,email api,transactional email,usend,webhooks
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# usend for Python
+
+The official Python SDK for [usend](https://usend.et), the email API for developers.
+
+```bash
+pip install usend
+```
+
+```python
+import os
+from usend import Usend
+
+usend = Usend(os.environ["USEND_API_KEY"])
+
+email = usend.emails.send({
+    "from": "Acme <hello@acme.com>",
+    "to": "ann@example.com",
+    "subject": "Your login code",
+    "html": "<p>Your code is <b>482913</b></p>",
+})
+print(email["id"])
+```
+
+Methods return the API's JSON as dicts and raise `usend.UsendError` (`status_code`, `name`, `message`).
+
+- Python 3.9 or newer. No dependencies.
+- The key defaults to `USEND_API_KEY`; the base URL to `USEND_BASE_URL` or `https://api.usend.et`.
+- Resources: `emails`, `batch`, `received`, `templates`, `domains`, `api_keys`, `segments`, `contacts`,
+  `broadcasts`, `webhooks`, `suppressions`.
+
+Verify a webhook (pass the raw body):
+
+```python
+from usend import verify_webhook
+
+event = verify_webhook(raw_body, request.headers, os.environ["USEND_WEBHOOK_SECRET"])
+```
+
+Docs: https://usend.et/docs

usend-1.0.0/README.md

@@ -0,0 +1,39 @@
+# usend for Python
+
+The official Python SDK for [usend](https://usend.et), the email API for developers.
+
+```bash
+pip install usend
+```
+
+```python
+import os
+from usend import Usend
+
+usend = Usend(os.environ["USEND_API_KEY"])
+
+email = usend.emails.send({
+    "from": "Acme <hello@acme.com>",
+    "to": "ann@example.com",
+    "subject": "Your login code",
+    "html": "<p>Your code is <b>482913</b></p>",
+})
+print(email["id"])
+```
+
+Methods return the API's JSON as dicts and raise `usend.UsendError` (`status_code`, `name`, `message`).
+
+- Python 3.9 or newer. No dependencies.
+- The key defaults to `USEND_API_KEY`; the base URL to `USEND_BASE_URL` or `https://api.usend.et`.
+- Resources: `emails`, `batch`, `received`, `templates`, `domains`, `api_keys`, `segments`, `contacts`,
+  `broadcasts`, `webhooks`, `suppressions`.
+
+Verify a webhook (pass the raw body):
+
+```python
+from usend import verify_webhook
+
+event = verify_webhook(raw_body, request.headers, os.environ["USEND_WEBHOOK_SECRET"])
+```
+
+Docs: https://usend.et/docs

usend-1.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usend"
+version = "1.0.0"
+description = "The official Python SDK for usend, the email API for developers."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["usend", "email", "transactional email", "email api", "webhooks"]
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent", "Topic :: Communications :: Email"]
+
+[project.urls]
+Homepage = "https://usend.et"
+Documentation = "https://usend.et/docs"

usend-1.0.0/tests/test_client.py

@@ -0,0 +1,76 @@
+import base64, hashlib, hmac, json, os, threading, time, unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from usend import Usend, UsendError, verify_webhook
+
+
+class Handler(BaseHTTPRequestHandler):
+    seen = []
+
+    def _reply(self):
+        body = self.rfile.read(int(self.headers.get("Content-Length") or 0))
+        Handler.seen.append((self.command, self.path, dict(self.headers), body))
+        if self.path == "/emails" and json.loads(body).get("to"):
+            out, code = {"id": "e1"}, 200
+        else:
+            out, code = {"statusCode": 422, "name": "validation_error", "message": "The `to` field is required."}, 422
+        data = json.dumps(out).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    do_POST = do_GET = _reply
+
+    def log_message(self, *a):
+        pass
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.srv = HTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=cls.srv.serve_forever, daemon=True).start()
+        cls.usend = Usend("us_test", base_url=f"http://127.0.0.1:{cls.srv.server_port}/")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.srv.shutdown()
+
+    def test_send(self):
+        res = self.usend.emails.send({"from": "a@x.com", "to": "b@y.com", "subject": "Hi", "html": "x"}, idempotency_key="k1")
+        self.assertEqual(res, {"id": "e1"})
+        method, path, headers, _ = Handler.seen[-1]
+        self.assertEqual((method, path), ("POST", "/emails"))
+        self.assertEqual(headers["Authorization"], "Bearer us_test")
+        self.assertEqual(headers["Idempotency-Key"], "k1")
+
+    def test_error(self):
+        with self.assertRaises(UsendError) as cm:
+            self.usend.emails.send({})
+        self.assertEqual((cm.exception.status_code, cm.exception.name), (422, "validation_error"))
+
+    def test_missing_key(self):
+        old = os.environ.pop("USEND_API_KEY", None)
+        try:
+            with self.assertRaises(UsendError):
+                Usend()
+        finally:
+            if old:
+                os.environ["USEND_API_KEY"] = old
+
+    def test_verify_webhook(self):
+        raw = os.urandom(24)
+        secret = "whsec_" + base64.b64encode(raw).decode()
+        payload = json.dumps({"type": "email.delivered", "data": {"email_id": "e1"}})
+        ts = str(int(time.time()))
+        sig = base64.b64encode(hmac.new(raw, f"m1.{ts}.{payload}".encode(), hashlib.sha256).digest()).decode()
+        headers = {"Webhook-Id": "m1", "Webhook-Timestamp": ts, "Webhook-Signature": "v1," + sig}
+        self.assertEqual(verify_webhook(payload, headers, secret)["data"]["email_id"], "e1")
+        with self.assertRaises(UsendError):
+            verify_webhook(payload + " ", headers, secret)
+
+
+if __name__ == "__main__":
+    unittest.main()

usend-1.0.0/usend/__init__.py

@@ -0,0 +1,16 @@
+"""usend for Python: the email API for developers.
+
+    from usend import Usend
+
+    usend = Usend("us_...")  # or set USEND_API_KEY
+    email = usend.emails.send({"from": "Acme <hi@acme.com>", "to": "ann@example.com",
+                               "subject": "Hi", "html": "<p>Hi</p>"})
+    print(email["id"])
+
+Methods return the API's JSON as dicts and raise UsendError on failure.
+"""
+
+from .client import Usend, UsendError, verify_webhook
+
+__all__ = ["Usend", "UsendError", "verify_webhook"]
+__version__ = "1.0.0"

usend-1.0.0/usend/client.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Mapping, Optional
+
+DEFAULT_BASE_URL = "https://api.usend.et"
+VERSION = "1.0.0"
+
+Json = dict[str, Any]
+
+
+class UsendError(Exception):
+    """An error from the usend API, with its status code and error name."""
+
+    def __init__(self, message: str, name: str = "application_error", status_code: Optional[int] = None):
+        super().__init__(message)
+        self.message = message
+        self.name = name
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return f"UsendError(status_code={self.status_code!r}, name={self.name!r}, message={self.message!r})"
+
+
+def _q(value: str) -> str:
+    return urllib.parse.quote(str(value), safe="")
+
+
+def _qs(params: Optional[Mapping[str, Any]]) -> str:
+    if not params:
+        return ""
+    clean = {k: v for k, v in params.items() if v is not None}
+    return "?" + urllib.parse.urlencode(clean) if clean else ""
+
+
+class _Resource:
+    def __init__(self, client: "Usend"):
+        self._c = client
+
+
+class Emails(_Resource):
+    def send(self, email: Json, idempotency_key: Optional[str] = None) -> Json:
+        return self._c._request("POST", "/emails", email, _idem(idempotency_key))
+
+    def get(self, email_id: str) -> Json:
+        return self._c._request("GET", f"/emails/{_q(email_id)}")
+
+    def list(self, **params: Any) -> Json:
+        return self._c._request("GET", f"/emails{_qs(params)}")
+
+    def update(self, email_id: str, scheduled_at: str) -> Json:
+        return self._c._request("PATCH", f"/emails/{_q(email_id)}", {"scheduled_at": scheduled_at})
+
+    def cancel(self, email_id: str) -> Json:
+        return self._c._request("POST", f"/emails/{_q(email_id)}/cancel")
+
+    def events(self, email_id: str) -> Json:
+        return self._c._request("GET", f"/emails/{_q(email_id)}/events")
+
+    def attachments(self, email_id: str) -> Json:
+        return self._c._request("GET", f"/emails/{_q(email_id)}/attachments")
+
+    def attachment(self, email_id: str, attachment_id: str) -> Json:
+        return self._c._request("GET", f"/emails/{_q(email_id)}/attachments/{_q(attachment_id)}")
+
+
+class Batch(_Resource):
+    def send(self, emails: list, idempotency_key: Optional[str] = None, validation: Optional[str] = None) -> Json:
+        headers = _idem(idempotency_key)
+        if validation:
+            headers["x-batch-validation"] = validation
+        return self._c._request("POST", "/emails/batch", emails, headers)
+
+
+class Received(_Resource):
+    def list(self, **params: Any) -> Json:
+        return self._c._request("GET", f"/inbound/emails{_qs(params)}")
+
+    def get(self, email_id: str) -> Json:
+        return self._c._request("GET", f"/inbound/emails/{_q(email_id)}")
+
+
+class _Crud(_Resource):
+    path = ""
+
+    def create(self, body: Json) -> Json:
+        return self._c._request("POST", self.path, body)
+
+    def list(self, **params: Any) -> Json:
+        return self._c._request("GET", f"{self.path}{_qs(params)}")
+
+    def get(self, ident: str) -> Json:
+        return self._c._request("GET", f"{self.path}/{_q(ident)}")
+
+    def update(self, ident: str, body: Json) -> Json:
+        return self._c._request("PATCH", f"{self.path}/{_q(ident)}", body)
+
+    def remove(self, ident: str) -> Json:
+        return self._c._request("DELETE", f"{self.path}/{_q(ident)}")
+
+
+class Templates(_Crud):
+    path = "/templates"
+
+    def publish(self, id_or_alias: str) -> Json:
+        return self._c._request("POST", f"/templates/{_q(id_or_alias)}/publish")
+
+    def duplicate(self, id_or_alias: str) -> Json:
+        return self._c._request("POST", f"/templates/{_q(id_or_alias)}/duplicate")
+
+
+class Domains(_Crud):
+    path = "/domains"
+
+    def verify(self, domain_id: str) -> Json:
+        return self._c._request("POST", f"/domains/{_q(domain_id)}/verify")
+
+    def auto_configure(self, domain_id: str, api_token: str, provider: str = "cloudflare") -> Json:
+        body = {"provider": provider, "api_token": api_token}
+        return self._c._request("POST", f"/domains/{_q(domain_id)}/auto-configure", body)
+
+
+class ApiKeys(_Crud):
+    path = "/api-keys"
+
+
+class Segments(_Crud):
+    path = "/segments"
+
+
+class Contacts(_Crud):
+    path = "/contacts"
+
+    def segments(self, id_or_email: str) -> Json:
+        return self._c._request("GET", f"/contacts/{_q(id_or_email)}/segments")
+
+    def add_to_segment(self, id_or_email: str, segment_id: str) -> Json:
+        return self._c._request("POST", f"/contacts/{_q(id_or_email)}/segments/{_q(segment_id)}")
+
+    def remove_from_segment(self, id_or_email: str, segment_id: str) -> Json:
+        return self._c._request("DELETE", f"/contacts/{_q(id_or_email)}/segments/{_q(segment_id)}")
+
+
+class Broadcasts(_Crud):
+    path = "/broadcasts"
+
+    def send(self, broadcast_id: str, scheduled_at: Optional[str] = None) -> Json:
+        body = {"scheduled_at": scheduled_at} if scheduled_at else {}
+        return self._c._request("POST", f"/broadcasts/{_q(broadcast_id)}/send", body)
+
+    def test(self, broadcast_id: str, to: str) -> Json:
+        return self._c._request("POST", f"/broadcasts/{_q(broadcast_id)}/test", {"to": to})
+
+
+class Webhooks(_Crud):
+    path = "/webhooks"
+
+    def deliveries(self, webhook_id: str, **params: Any) -> Json:
+        return self._c._request("GET", f"/webhooks/{_q(webhook_id)}/deliveries{_qs(params)}")
+
+    def replay(self, webhook_id: str, delivery_id: str) -> Json:
+        return self._c._request("POST", f"/webhooks/{_q(webhook_id)}/deliveries/{_q(delivery_id)}/replay")
+
+    @staticmethod
+    def verify(payload: str, headers: Mapping[str, str], secret: str, tolerance_seconds: int = 300) -> Json:
+        return verify_webhook(payload, headers, secret, tolerance_seconds)
+
+
+class Suppressions(_Crud):
+    path = "/suppressions"
+
+
+class Usend:
+    """Client for the usend API. `base_url` defaults to USEND_BASE_URL or https://api.usend.et."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 30.0):
+        self.api_key = api_key or os.environ.get("USEND_API_KEY")
+        if not self.api_key:
+            raise UsendError('Missing API key. Pass it to Usend("us_...") or set USEND_API_KEY.', "missing_api_key")
+        self.base_url = (base_url or os.environ.get("USEND_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.emails = Emails(self)
+        self.batch = Batch(self)
+        self.received = Received(self)
+        self.templates = Templates(self)
+        self.domains = Domains(self)
+        self.api_keys = ApiKeys(self)
+        self.segments = Segments(self)
+        self.contacts = Contacts(self)
+        self.broadcasts = Broadcasts(self)
+        self.webhooks = Webhooks(self)
+        self.suppressions = Suppressions(self)
+
+    def _request(self, method: str, path: str, body: Any = None, headers: Optional[dict] = None) -> Json:
+        h = {"Authorization": f"Bearer {self.api_key}", "User-Agent": f"usend-python/{VERSION}", "Accept": "application/json"}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            h["Content-Type"] = "application/json"
+        h.update(headers or {})
+        req = urllib.request.Request(self.base_url + path, data=data, headers=h, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                raw = res.read()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as e:
+            try:
+                err = json.loads(e.read())
+            except ValueError:
+                err = {}
+            raise UsendError(err.get("message") or f"HTTP {e.code}", err.get("name") or "application_error", e.code) from None
+        except urllib.error.URLError as e:
+            raise UsendError(str(e.reason)) from None
+
+
+def _idem(key: Optional[str]) -> dict:
+    return {"Idempotency-Key": key} if key else {}
+
+
+def verify_webhook(payload: str, headers: Mapping[str, str], secret: str, tolerance_seconds: int = 300) -> Json:
+    """Verify a webhook delivery (Standard Webhooks) and return the parsed event; raises UsendError if invalid.
+
+    `payload` must be the raw request body exactly as received.
+    """
+    lower = {k.lower(): v for k, v in headers.items()}
+    msg_id, ts, sigs = lower.get("webhook-id"), lower.get("webhook-timestamp"), lower.get("webhook-signature")
+    if not (msg_id and ts and sigs):
+        raise UsendError("Missing webhook-id, webhook-timestamp or webhook-signature header", "invalid_webhook")
+    if abs(time.time() - int(ts)) > tolerance_seconds:
+        raise UsendError("Webhook timestamp is too old or too new", "invalid_webhook")
+    key = base64.b64decode(secret.removeprefix("whsec_"))
+    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.{payload}".encode(), hashlib.sha256).digest()).decode()
+    for part in sigs.split(" "):
+        version, _, sig = part.partition(",")
+        if version == "v1" and hmac.compare_digest(sig, expected):
+            return json.loads(payload)
+    raise UsendError("Invalid webhook signature", "invalid_webhook")