sendery 0.1.0__py3-none-any.whl

sendery/__init__.py

@@ -0,0 +1,112 @@
+"""Server-side Sendery template API client."""
+import json
+import math
+import random
+import re
+import time
+import uuid
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from urllib.parse import urlparse, quote
+from urllib.request import Request, build_opener, HTTPRedirectHandler
+from urllib.error import HTTPError, URLError
+
+
+class SenderyError(Exception):
+    def __init__(self, status, code="request_error", errors=None, retry_after=None):
+        super().__init__(f"Sendery API error: {code}")
+        self.status, self.code, self.errors, self.retry_after = status, code, errors or {}, retry_after
+
+    @property
+    def retryable(self):
+        return self.status in (0, 500, 502, 503, 504) or (self.status == 429 and self.code == "rate_limited")
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class PendingEmail:
+    def __init__(self, client, payload, key):
+        if not re.fullmatch(r"[a-zA-Z0-9_.:-]{1,128}", key):
+            raise ValueError("Invalid idempotency key.")
+        self.client, self._key, self._body, self._retries = client, key, json.dumps(payload, allow_nan=False).encode(), 0
+
+    @property
+    def idempotency_key(self):
+        return self._key
+
+    def retry(self, retries=3):
+        if type(retries) is not int or not 0 <= retries <= 5:
+            raise ValueError("Choose 0 to 5 retries.")
+        self._retries = retries
+        return self
+
+    def send(self):
+        for attempt in range(self._retries + 1):
+            try:
+                return self.client._request("POST", "/api/v1/emails", self._body, self._key)
+            except SenderyError as error:
+                if attempt == self._retries or not error.retryable:
+                    raise
+                delay = error.retry_after if error.retry_after is not None else min(8, .25 * 2 ** attempt + random.random() * .1)
+                if delay > 30:
+                    raise
+                time.sleep(delay)
+
+
+class Sendery:
+    def __init__(self, api_key, base_url="https://sendery.co"):
+        url = urlparse(base_url)
+        if not api_key or not url.hostname or url.username or url.password or url.query or url.fragment or (url.scheme != "https" and not (url.scheme == "http" and url.hostname in ("localhost", "127.0.0.1", "::1"))):
+            raise ValueError("Provide an API key and an HTTPS URL (HTTP allowed only on loopback).")
+        self._api_key, self._base_url, self._opener = api_key, base_url.rstrip("/"), build_opener(_NoRedirect)
+
+    def prepare(self, *, to, template, data, locale=None, idempotency_key=None):
+        if not isinstance(data, dict):
+            raise ValueError("data must be a dictionary.")
+        payload = {"to": to, "template": template, "data": data}
+        if locale is not None:
+            payload["locale"] = locale
+        return PendingEmail(self, payload, idempotency_key if idempotency_key is not None else str(uuid.uuid4()))
+
+    def send(self, **kwargs):
+        return self.prepare(**kwargs).send()
+
+    def get(self, message_id):
+        return self._request("GET", "/api/v1/emails/" + quote(message_id, safe=""))
+
+    def _request(self, method, path, body=None, key=None):
+        headers = {"Authorization": "Bearer " + self._api_key, "Content-Type": "application/json", "Accept": "application/json"}
+        if key is not None:
+            headers["Idempotency-Key"] = key
+        try:
+            with self._opener.open(Request(self._base_url + path, body, headers, method=method), timeout=10) as response:
+                try:
+                    result = json.load(response)
+                except (ValueError, UnicodeError):
+                    raise SenderyError(0, "invalid_response") from None
+                if not isinstance(result, dict) or not isinstance(result.get("id"), str) or not isinstance(result.get("status"), str):
+                    raise SenderyError(0, "invalid_response")
+                return result
+        except HTTPError as error:
+            try:
+                details = json.loads(error.read())
+                if not isinstance(details, dict):
+                    details = {}
+            except (ValueError, UnicodeError):
+                details = {}
+            retry_after = error.headers.get("Retry-After")
+            try:
+                delay = max(0, float(retry_after)) if retry_after is not None else None
+            except ValueError:
+                try:
+                    delay = max(0, (parsedate_to_datetime(retry_after) - datetime.now(timezone.utc)).total_seconds())
+                except (ValueError, TypeError):
+                    delay = None
+            if delay is not None and not math.isfinite(delay):
+                delay = None
+            raise SenderyError(error.code, details.get("code", "request_error"), details.get("errors"), delay) from None
+        except (URLError, TimeoutError, OSError):
+            raise SenderyError(0, "connection_error") from None

sendery-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: sendery
+Version: 0.1.0
+Summary: Sendery template email client
+License-Expression: MIT
+Project-URL: Documentation, https://sendery.co/en/docs/python
+Project-URL: Repository, https://github.com/sendery-co/sendery-python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Sendery for Python
+
+Send published Sendery templates from Python.
+
+[Documentation](https://sendery.co/en/docs/python) · [API reference](https://sendery.co/en/docs/send-email) · [Changelog](CHANGELOG.md)
+
+## Requirements
+
+Python 3.10+.
+
+## Install
+
+```bash
+pip install sendery
+```
+
+## Set up
+
+Publish a `welcome` template with `name` and `action_url` variables, and create a [project API key](https://sendery.co/en/docs/authentication). Store it as `SENDERY_API_KEY` on your server.
+
+```bash
+export SENDERY_API_KEY="your_project_api_key"
+```
+
+## Send an email
+
+The response contains the accepted email’s `id` and `status`. Calls are synchronous; use `asyncio.to_thread()` when sending from async code.
+
+```python
+import os
+from sendery import Sendery
+
+sendery = Sendery(os.environ["SENDERY_API_KEY"])
+receipt = sendery.send(
+    to="alex@example.com",
+    template="welcome",
+    data={"name": "Alex", "action_url": "https://example.com/start"},
+)
+
+print(receipt["id"])
+```
+
+## Retrieve an email
+
+Use the returned ID to [check delivery status](https://sendery.co/en/docs/get-email).
+
+```python
+message = sendery.get(receipt["id"])
+print(message["status"])
+```
+
+## Retry a send
+
+Use a key such as `welcome-123` for one email, and [keep the payload unchanged on retries](https://sendery.co/en/docs/idempotency). `retry(3)` allows up to three additional attempts for temporary failures; `send()` alone makes one attempt.
+
+```python
+email = sendery.prepare(
+    to="alex@example.com",
+    template="welcome",
+    data={"name": "Alex", "action_url": "https://example.com/start"},
+    idempotency_key="welcome-123",
+)
+receipt = email.retry(3).send()
+```
+
+## Handle errors
+
+Catch the SDK exception to inspect the [status and code](https://sendery.co/en/docs/errors). Retry delays are in seconds. The example uses the prepared `email` from the [retry example above](#retry-a-send).
+
+```python
+from sendery import SenderyError
+
+try:
+    receipt = email.retry(3).send()
+except SenderyError as error:
+    print(error.status, error.code, error.errors)
+    # error.retry_after is a delay in seconds, when provided.
+    raise
+```
+
+## More
+
+See [idempotency and retries](https://sendery.co/en/docs/idempotency) for retry conditions, delays, and reusing a key across attempts.
+
+## License
+
+[MIT](LICENSE).

sendery-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+sendery/__init__.py,sha256=cojnWnAlCiudgOEfZFZt5ntVkIbFRH6nHPbw7zMhHO4,5022
+sendery-0.1.0.dist-info/licenses/LICENSE,sha256=d5HiJStdXYwRXhCo_KDE-pVg2xK18jHouZ_t36Cbqwk,1077
+sendery-0.1.0.dist-info/METADATA,sha256=pEfW4Eg7J-QBnjyt11Gack1yifkGQLDhwHDShtU4DdA,2650
+sendery-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sendery-0.1.0.dist-info/top_level.txt,sha256=DO99vDP8BeBS1zmyU_Ow8r2JSCFvEimaflG9KJcv9wc,8
+sendery-0.1.0.dist-info/RECORD,,

sendery-0.1.0.dist-info/WHEEL

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

sendery-0.1.0.dist-info/licenses/LICENSE

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

sendery-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sendery