sendery 0.1.0__tar.gz

sendery-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,87 @@
+# 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/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sendery"
+version = "0.1.0"
+description = "Sendery template email client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Documentation = "https://sendery.co/en/docs/python"
+Repository = "https://github.com/sendery-co/sendery-python"

sendery-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sendery-0.1.0/src/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/src/sendery.egg-info/PKG-INFO

@@ -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/src/sendery.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/sendery/__init__.py
+src/sendery.egg-info/PKG-INFO
+src/sendery.egg-info/SOURCES.txt
+src/sendery.egg-info/dependency_links.txt
+src/sendery.egg-info/top_level.txt
+tests/test_client.py

sendery-0.1.0/src/sendery.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sendery-0.1.0/src/sendery.egg-info/top_level.txt

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

sendery-0.1.0/tests/test_client.py

@@ -0,0 +1,36 @@
+import json
+import unittest
+from unittest.mock import patch
+from sendery import Sendery, SenderyError
+
+
+class ClientTests(unittest.TestCase):
+    def test_retry_preserves_key_and_original_data(self):
+        client = Sendery("test")
+        data = {"name": "Original"}
+        email = client.prepare(to="alex@example.com", template="welcome", data=data)
+        data["name"] = "Changed"
+        with patch.object(client, "_request", side_effect=[SenderyError(503), {"id": "one", "status": "queued"}]) as request, patch("sendery.time.sleep"):
+            email.retry().send()
+        self.assertEqual(request.call_args_list[0], request.call_args_list[1])
+        self.assertEqual("Original", json.loads(request.call_args.args[2])["data"]["name"])
+        self.assertEqual(email.idempotency_key, request.call_args.args[3])
+
+    def test_capacity_is_not_retried(self):
+        client = Sendery("test")
+        with patch.object(client, "_request", side_effect=SenderyError(429, "email_capacity_exceeded")) as request:
+            with self.assertRaises(SenderyError):
+                client.prepare(to="a@example.com", template="welcome", data={}).retry().send()
+        self.assertEqual(1, request.call_count)
+
+    def test_explicit_key_and_get(self):
+        client = Sendery("test")
+        self.assertEqual("event-12", client.prepare(to="a@example.com", template="welcome", data={}, idempotency_key="event-12").idempotency_key)
+        with patch.object(client, "_request") as request:
+            client.get("message/12")
+        request.assert_called_once_with("GET", "/api/v1/emails/message%2F12")
+
+    def test_remote_http_and_credential_urls_rejected(self):
+        for url in ["http://example.com", "https://user:pass@example.com"]:
+            with self.assertRaises(ValueError):
+                Sendery("test", url)