zerelay 0.1.0__tar.gz

zerelay-0.1.0/LICENSE

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

zerelay-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: zerelay
+Version: 0.1.0
+Summary: Official Python SDK for the Zerelay email and SMS API
+License: MIT
+Project-URL: Homepage, https://zerelay.com
+Project-URL: Documentation, https://zerelay.com/developer/docs
+Keywords: zerelay,email,sms,transactional-email,smtp,nigeria,webhooks
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Zerelay for Python
+
+Official Python SDK for the [Zerelay](https://zerelay.com) email and SMS API. No dependencies; Python 3.8+.
+
+```bash
+pip install zerelay
+```
+
+## Send an email
+
+```python
+from zerelay import Zerelay
+
+zerelay = Zerelay()  # reads ZERELAY_API_KEY, or pass the key: Zerelay("sk_...")
+
+result = zerelay.emails.send(
+    to="jane@example.com",
+    subject="Your order has shipped",
+    body="<p>It will arrive on Friday.</p>",
+)
+print(result["task_id"])
+```
+
+For cc/bcc, separate text and HTML parts, templates or categories, `emails.mail_send()` takes the SendGrid v3 `/mail/send` format:
+
+```python
+zerelay.emails.mail_send({
+    "personalizations": [{"to": [{"email": "jane@example.com"}], "cc": [{"email": "ops@example.com"}]}],
+    "from": {"email": "orders@yourdomain.com", "name": "Your Store"},
+    "subject": "Order #1001",
+    "content": [{"type": "text/html", "value": "<p>Thanks for your order</p>"}],
+})
+```
+
+## Send an SMS
+
+```python
+message = zerelay.sms.send(to="08031234567", body="Your code is 4821")
+print(message["status"], message["cost_kobo"])
+```
+
+## Test mode
+
+Create a **test key** (`sk_test_...`) under **API Keys** in the dashboard. Test keys check every request exactly like a live key does, but nothing is sent, charged or counted toward your quota. Webhooks still fire, marked `"test_mode": true`. Send to `bounce@simulator.zerelay.com` to simulate a bounce.
+
+## Verify webhooks
+
+Verify the **raw** request body:
+
+```python
+from zerelay import verify_webhook, ZerelayWebhookError
+
+# Flask
+@app.post("/webhooks/zerelay")
+def zerelay_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers, os.environ["ZERELAY_WEBHOOK_SECRET"])
+    except ZerelayWebhookError as exc:
+        return str(exc), 400
+    # event["event"] is e.g. "delivered", "bounce", "sms.delivered"; de-duplicate on event["id"]
+    return "", 200
+```
+
+In Django use `request.body`. In FastAPI use `await request.body()`.
+
+## Errors and retries
+
+Failed requests raise `ZerelayError` with `status`, `message` (the API's explanation) and `body`. The client retries automatically:
+
+- **Rate limits (429)** are always retried, after the `Retry-After` delay.
+- **Network errors and 502/503/504** are retried only when repeating the request is safe. That covers GETs, plus `emails.send()` and `sms.send()`, which send an automatic `Idempotency-Key`.
+
+Change this with `Zerelay(max_retries=0)`.
+
+Any other endpoint can be called with `zerelay.request("GET", "/path", query={...}, body={...})`. The full reference is at <https://api.zerelay.com/docs>.
+
+## License
+
+MIT

zerelay-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Zerelay for Python
+
+Official Python SDK for the [Zerelay](https://zerelay.com) email and SMS API. No dependencies; Python 3.8+.
+
+```bash
+pip install zerelay
+```
+
+## Send an email
+
+```python
+from zerelay import Zerelay
+
+zerelay = Zerelay()  # reads ZERELAY_API_KEY, or pass the key: Zerelay("sk_...")
+
+result = zerelay.emails.send(
+    to="jane@example.com",
+    subject="Your order has shipped",
+    body="<p>It will arrive on Friday.</p>",
+)
+print(result["task_id"])
+```
+
+For cc/bcc, separate text and HTML parts, templates or categories, `emails.mail_send()` takes the SendGrid v3 `/mail/send` format:
+
+```python
+zerelay.emails.mail_send({
+    "personalizations": [{"to": [{"email": "jane@example.com"}], "cc": [{"email": "ops@example.com"}]}],
+    "from": {"email": "orders@yourdomain.com", "name": "Your Store"},
+    "subject": "Order #1001",
+    "content": [{"type": "text/html", "value": "<p>Thanks for your order</p>"}],
+})
+```
+
+## Send an SMS
+
+```python
+message = zerelay.sms.send(to="08031234567", body="Your code is 4821")
+print(message["status"], message["cost_kobo"])
+```
+
+## Test mode
+
+Create a **test key** (`sk_test_...`) under **API Keys** in the dashboard. Test keys check every request exactly like a live key does, but nothing is sent, charged or counted toward your quota. Webhooks still fire, marked `"test_mode": true`. Send to `bounce@simulator.zerelay.com` to simulate a bounce.
+
+## Verify webhooks
+
+Verify the **raw** request body:
+
+```python
+from zerelay import verify_webhook, ZerelayWebhookError
+
+# Flask
+@app.post("/webhooks/zerelay")
+def zerelay_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers, os.environ["ZERELAY_WEBHOOK_SECRET"])
+    except ZerelayWebhookError as exc:
+        return str(exc), 400
+    # event["event"] is e.g. "delivered", "bounce", "sms.delivered"; de-duplicate on event["id"]
+    return "", 200
+```
+
+In Django use `request.body`. In FastAPI use `await request.body()`.
+
+## Errors and retries
+
+Failed requests raise `ZerelayError` with `status`, `message` (the API's explanation) and `body`. The client retries automatically:
+
+- **Rate limits (429)** are always retried, after the `Retry-After` delay.
+- **Network errors and 502/503/504** are retried only when repeating the request is safe. That covers GETs, plus `emails.send()` and `sms.send()`, which send an automatic `Idempotency-Key`.
+
+Change this with `Zerelay(max_retries=0)`.
+
+Any other endpoint can be called with `zerelay.request("GET", "/path", query={...}, body={...})`. The full reference is at <https://api.zerelay.com/docs>.
+
+## License
+
+MIT

zerelay-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zerelay"
+version = "0.1.0"
+description = "Official Python SDK for the Zerelay email and SMS API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+dependencies = []
+keywords = ["zerelay", "email", "sms", "transactional-email", "smtp", "nigeria", "webhooks"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Communications :: Email",
+]
+
+[project.urls]
+Homepage = "https://zerelay.com"
+Documentation = "https://zerelay.com/developer/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+zerelay = ["py.typed"]

zerelay-0.1.0/setup.cfg

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

zerelay-0.1.0/src/zerelay/__init__.py

@@ -0,0 +1,8 @@
+"""Official Python SDK for the Zerelay email and SMS API. https://zerelay.com/developer/docs"""
+from ._client import DEFAULT_BASE_URL, Zerelay
+from ._errors import ZerelayError, ZerelayWebhookError
+from ._version import VERSION
+from ._webhooks import verify_webhook
+
+__version__ = VERSION
+__all__ = ["Zerelay", "ZerelayError", "ZerelayWebhookError", "verify_webhook", "DEFAULT_BASE_URL", "VERSION"]

zerelay-0.1.0/src/zerelay/_client.py

@@ -0,0 +1,215 @@
+import json
+import os
+import random
+import time
+import uuid
+from typing import Any, Dict, List, Optional, Union
+from urllib import error as urlerror
+from urllib import parse, request
+
+from ._errors import ZerelayError
+from ._version import VERSION
+
+DEFAULT_BASE_URL = "https://api.zerelay.com"
+_RETRYABLE = {429, 502, 503, 504}
+
+
+def _detail(body: Any, fallback: str) -> str:
+    d = body.get("detail") if isinstance(body, dict) else None
+    if isinstance(d, list):
+        parts = []
+        for item in d:
+            if isinstance(item, dict) and item.get("msg"):
+                parts.append(f"{'.'.join(str(x) for x in item.get('loc', []))}: {item['msg']}")
+            else:
+                parts.append(str(item))
+        return "; ".join(parts)
+    return str(d) if d else fallback
+
+
+class Zerelay:
+    """Zerelay API client.
+
+        zr = Zerelay("sk_...")            # or set ZERELAY_API_KEY
+        zr.emails.send(to="jane@example.com", subject="Hi", body="<p>Hello</p>")
+        zr.sms.send(to="08031234567", body="Your code is 1234")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        api_key = api_key or os.environ.get("ZERELAY_API_KEY")
+        if not api_key:
+            raise ValueError("Missing Zerelay API key: pass it to Zerelay(api_key) or set ZERELAY_API_KEY")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.emails = Emails(self)
+        self.sms = Sms(self)
+
+    def key_info(self) -> Dict[str, Any]:
+        """What the configured key is: live/test, full/send-only, and the account's rate limits."""
+        return self.request("GET", "/api-keys/current")
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        idempotent: bool = False,
+    ) -> Any:
+        """Call any endpoint (see https://api.zerelay.com/docs). 429s are always retried;
+        network errors and 502-504 only for GETs and requests carrying an Idempotency-Key."""
+        url = self.base_url + path
+        if query:
+            clean = {k: ("true" if v is True else "false" if v is False else v) for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + parse.urlencode(clean)
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        all_headers = {
+            "X-API-Key": self.api_key,
+            "User-Agent": f"zerelay-python/{VERSION}",
+            "Accept": "application/json",
+        }
+        if data is not None:
+            all_headers["Content-Type"] = "application/json"
+        all_headers.update(headers or {})
+        can_retry_failures = method.upper() == "GET" or idempotent
+
+        attempt = 0
+        while True:
+            req = request.Request(url, data=data, method=method.upper(), headers=all_headers)
+            try:
+                with request.urlopen(req, timeout=self.timeout) as resp:
+                    raw = resp.read()
+                    status = resp.status
+                    test_mode = resp.headers.get("X-Zerelay-Test-Mode") == "true"
+                if not raw:
+                    return {"status": status, "test_mode": test_mode}
+                return json.loads(raw)
+            except urlerror.HTTPError as exc:
+                raw = exc.read()
+                try:
+                    parsed: Any = json.loads(raw) if raw else None
+                except ValueError:
+                    parsed = raw.decode("utf-8", "replace")
+                retry_after = exc.headers.get("Retry-After") if exc.headers else None
+                retry_after_s = float(retry_after) if retry_after and retry_after.replace(".", "", 1).isdigit() else None
+                retryable = exc.code == 429 or (can_retry_failures and exc.code in _RETRYABLE)
+                if retryable and attempt < self.max_retries:
+                    time.sleep(min(retry_after_s, 60) if retry_after_s else self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise ZerelayError(_detail(parsed, f"HTTP {exc.code}"), status=exc.code, body=parsed, retry_after=retry_after_s) from None
+            except (urlerror.URLError, TimeoutError, ConnectionError, OSError) as exc:
+                if can_retry_failures and attempt < self.max_retries:
+                    time.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise ZerelayError(f"Request to {method.upper()} {path} failed: {exc}") from None
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return min(8.0, 0.5 * 2 ** attempt) * random.uniform(0.8, 1.2)
+
+
+def _drop_none(values: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in values.items() if v is not None}
+
+
+class Emails:
+    def __init__(self, client: Zerelay) -> None:
+        self._c = client
+
+    def send(
+        self,
+        *,
+        to: str,
+        subject: str,
+        body: str,
+        sender_identity_id: Optional[int] = None,
+        attachments: Optional[List[Dict[str, str]]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Send one email. Retries are safe: an Idempotency-Key is generated unless you pass one."""
+        return self._c.request(
+            "POST", "/send-email",
+            body=_drop_none({"to": to, "subject": subject, "body": body, "sender_identity_id": sender_identity_id, "attachments": attachments}),
+            headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+            idempotent=True,
+        )
+
+    def send_bulk(
+        self,
+        *,
+        recipients: List[str],
+        subject: str,
+        body: str,
+        sender_identity_id: Optional[int] = None,
+        attachments: Optional[List[Dict[str, str]]] = None,
+    ) -> Dict[str, Any]:
+        """One message to many recipients (each gets their own copy)."""
+        return self._c.request(
+            "POST", "/send-bulk-emails",
+            body=_drop_none({"recipients": recipients, "subject": subject, "body": body, "sender_identity_id": sender_identity_id, "attachments": attachments}),
+        )
+
+    def mail_send(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Full control (cc, bcc, separate text/html, templates, categories): SendGrid v3 format."""
+        return self._c.request("POST", "/v3/mail/send", body=payload)
+
+    def get(self, task_id: str) -> Dict[str, Any]:
+        return self._c.request("GET", f"/email-status/{parse.quote(task_id, safe='')}")
+
+    def list(self, **query: Any) -> List[Dict[str, Any]]:
+        return self._c.request("GET", "/emails", query=query)
+
+
+class Sms:
+    def __init__(self, client: Zerelay) -> None:
+        self._c = client
+
+    def send(
+        self,
+        *,
+        to: Union[str, List[str]],
+        body: str,
+        sender_id: Optional[str] = None,
+        route: Optional[str] = None,
+        schedule_at: Optional[str] = None,
+        reference: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Send an SMS to one or more Nigerian numbers, paid from your SMS wallet."""
+        return self._c.request(
+            "POST", "/sms/send",
+            body=_drop_none({"to": to, "body": body, "sender_id": sender_id, "route": route, "schedule_at": schedule_at, "reference": reference}),
+            headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+            idempotent=True,
+        )
+
+    def quote(self, *, to: Union[str, List[str]], body: str, sender_id: Optional[str] = None, route: Optional[str] = None) -> Dict[str, Any]:
+        """Price a send without sending or charging."""
+        return self._c.request("POST", "/sms/quote", body=_drop_none({"to": to, "body": body, "sender_id": sender_id, "route": route}), idempotent=True)
+
+    def get(self, message_id: str, *, refresh: bool = False) -> Dict[str, Any]:
+        return self._c.request("GET", f"/sms/messages/{parse.quote(message_id, safe='')}", query={"refresh": refresh})
+
+    def list(self, **query: Any) -> List[Dict[str, Any]]:
+        return self._c.request("GET", "/sms/messages", query=query)
+
+    def cancel(self, message_id: str) -> Dict[str, Any]:
+        """Cancel a scheduled message (fully refunded)."""
+        return self._c.request("POST", f"/sms/messages/{parse.quote(message_id, safe='')}/cancel")
+
+    def wallet(self) -> Dict[str, Any]:
+        return self._c.request("GET", "/sms/wallet")

zerelay-0.1.0/src/zerelay/_errors.py

@@ -0,0 +1,16 @@
+from typing import Any, Optional
+
+
+class ZerelayError(Exception):
+    """An API error. `status` is the HTTP status (None for network errors)."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, body: Any = None, retry_after: Optional[float] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+        self.retry_after = retry_after
+
+
+class ZerelayWebhookError(Exception):
+    """A webhook failed verification (bad signature, stale timestamp, missing headers)."""

zerelay-0.1.0/src/zerelay/_version.py

@@ -0,0 +1 @@
+VERSION = "0.1.0"

zerelay-0.1.0/src/zerelay/_webhooks.py

@@ -0,0 +1,58 @@
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping, Optional, Union
+
+from ._errors import ZerelayWebhookError
+
+
+def _header(headers: Mapping[str, Any], name: str) -> Optional[str]:
+    getter = getattr(headers, "get", None)
+    if getter is not None:
+        value = getter(name)
+        if value is None:
+            value = getter(name.lower())
+        if value is not None:
+            return value[0] if isinstance(value, (list, tuple)) else str(value)
+    lower = name.lower()
+    for key, value in dict(headers).items():
+        if str(key).lower() == lower:
+            return value[0] if isinstance(value, (list, tuple)) else str(value)
+    return None
+
+
+def verify_webhook(
+    payload: Union[bytes, str],
+    headers: Mapping[str, Any],
+    secret: str,
+    tolerance_seconds: int = 300,
+    now: Optional[float] = None,
+) -> Any:
+    """Verify a Zerelay webhook and return the parsed event.
+
+    Pass the RAW request body (e.g. Flask `request.get_data()`, Django `request.body`,
+    FastAPI `await request.body()`), not re-serialised JSON. Raises ZerelayWebhookError if
+    the signature is wrong or the timestamp is older than `tolerance_seconds` (0 disables).
+    """
+    if not secret:
+        raise ZerelayWebhookError("Missing webhook signing secret")
+    raw = payload if isinstance(payload, bytes) else str(payload).encode("utf-8")
+    signature = _header(headers, "X-Zerelay-Signature") or _header(headers, "X-SMTP-Signature")
+    timestamp = _header(headers, "X-Zerelay-Timestamp") or _header(headers, "X-SMTP-Timestamp")
+    if not signature or not timestamp:
+        raise ZerelayWebhookError("Missing X-Zerelay-Signature or X-Zerelay-Timestamp header")
+    try:
+        ts = int(timestamp)
+    except ValueError:
+        raise ZerelayWebhookError("Invalid X-Zerelay-Timestamp header") from None
+    current = time.time() if now is None else now
+    if tolerance_seconds and abs(current - ts) > tolerance_seconds:
+        raise ZerelayWebhookError("Webhook timestamp is outside the allowed tolerance (possible replay)")
+    expected = "sha256=" + hmac.new(secret.encode("utf-8"), timestamp.encode("utf-8") + b"." + raw, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, signature):
+        raise ZerelayWebhookError("Invalid webhook signature")
+    try:
+        return json.loads(raw)
+    except ValueError:
+        raise ZerelayWebhookError("Webhook body is not valid JSON") from None

zerelay-0.1.0/src/zerelay.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: zerelay
+Version: 0.1.0
+Summary: Official Python SDK for the Zerelay email and SMS API
+License: MIT
+Project-URL: Homepage, https://zerelay.com
+Project-URL: Documentation, https://zerelay.com/developer/docs
+Keywords: zerelay,email,sms,transactional-email,smtp,nigeria,webhooks
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Zerelay for Python
+
+Official Python SDK for the [Zerelay](https://zerelay.com) email and SMS API. No dependencies; Python 3.8+.
+
+```bash
+pip install zerelay
+```
+
+## Send an email
+
+```python
+from zerelay import Zerelay
+
+zerelay = Zerelay()  # reads ZERELAY_API_KEY, or pass the key: Zerelay("sk_...")
+
+result = zerelay.emails.send(
+    to="jane@example.com",
+    subject="Your order has shipped",
+    body="<p>It will arrive on Friday.</p>",
+)
+print(result["task_id"])
+```
+
+For cc/bcc, separate text and HTML parts, templates or categories, `emails.mail_send()` takes the SendGrid v3 `/mail/send` format:
+
+```python
+zerelay.emails.mail_send({
+    "personalizations": [{"to": [{"email": "jane@example.com"}], "cc": [{"email": "ops@example.com"}]}],
+    "from": {"email": "orders@yourdomain.com", "name": "Your Store"},
+    "subject": "Order #1001",
+    "content": [{"type": "text/html", "value": "<p>Thanks for your order</p>"}],
+})
+```
+
+## Send an SMS
+
+```python
+message = zerelay.sms.send(to="08031234567", body="Your code is 4821")
+print(message["status"], message["cost_kobo"])
+```
+
+## Test mode
+
+Create a **test key** (`sk_test_...`) under **API Keys** in the dashboard. Test keys check every request exactly like a live key does, but nothing is sent, charged or counted toward your quota. Webhooks still fire, marked `"test_mode": true`. Send to `bounce@simulator.zerelay.com` to simulate a bounce.
+
+## Verify webhooks
+
+Verify the **raw** request body:
+
+```python
+from zerelay import verify_webhook, ZerelayWebhookError
+
+# Flask
+@app.post("/webhooks/zerelay")
+def zerelay_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers, os.environ["ZERELAY_WEBHOOK_SECRET"])
+    except ZerelayWebhookError as exc:
+        return str(exc), 400
+    # event["event"] is e.g. "delivered", "bounce", "sms.delivered"; de-duplicate on event["id"]
+    return "", 200
+```
+
+In Django use `request.body`. In FastAPI use `await request.body()`.
+
+## Errors and retries
+
+Failed requests raise `ZerelayError` with `status`, `message` (the API's explanation) and `body`. The client retries automatically:
+
+- **Rate limits (429)** are always retried, after the `Retry-After` delay.
+- **Network errors and 502/503/504** are retried only when repeating the request is safe. That covers GETs, plus `emails.send()` and `sms.send()`, which send an automatic `Idempotency-Key`.
+
+Change this with `Zerelay(max_retries=0)`.
+
+Any other endpoint can be called with `zerelay.request("GET", "/path", query={...}, body={...})`. The full reference is at <https://api.zerelay.com/docs>.
+
+## License
+
+MIT

zerelay-0.1.0/src/zerelay.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/zerelay/__init__.py
+src/zerelay/_client.py
+src/zerelay/_errors.py
+src/zerelay/_version.py
+src/zerelay/_webhooks.py
+src/zerelay/py.typed
+src/zerelay.egg-info/PKG-INFO
+src/zerelay.egg-info/SOURCES.txt
+src/zerelay.egg-info/dependency_links.txt
+src/zerelay.egg-info/top_level.txt
+tests/test_client.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+zerelay

zerelay-0.1.0/tests/test_client.py

@@ -0,0 +1,141 @@
+import hashlib
+import hmac
+import json
+import os
+import sys
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from zerelay import Zerelay, ZerelayError, ZerelayWebhookError, verify_webhook  # noqa: E402
+
+
+class Mock:
+    def __init__(self, responder):
+        self.calls = []
+        mock = self
+
+        class H(BaseHTTPRequestHandler):
+            def log_message(self, *a):
+                pass
+
+            def _handle(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                body = self.rfile.read(length) if length else b""
+                mock.calls.append({"method": self.command, "path": self.path, "headers": {k.lower(): v for k, v in self.headers.items()}, "body": json.loads(body) if body else None})
+                status, data, headers = responder(len(mock.calls))
+                self.send_response(status)
+                for k, v in (headers or {}).items():
+                    self.send_header(k, v)
+                payload = b"" if data is None else json.dumps(data).encode()
+                self.send_header("Content-Length", str(len(payload)))
+                self.end_headers()
+                self.wfile.write(payload)
+
+            do_GET = do_POST = _handle
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), H)
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        self.url = f"http://127.0.0.1:{self.server.server_address[1]}"
+
+    def close(self):
+        self.server.shutdown()
+
+
+class ClientTests(unittest.TestCase):
+    def test_send_email_headers_and_idempotency(self):
+        m = Mock(lambda n: (200, {"task_id": "t1", "status": "queued", "message": "ok", "test_mode": False}, None))
+        zr = Zerelay("sk_test_x", base_url=m.url)
+        out = zr.emails.send(to="a@example.com", subject="s", body="b")
+        self.assertEqual(out["task_id"], "t1")
+        call = m.calls[0]
+        self.assertEqual(call["path"], "/send-email")
+        self.assertEqual(call["headers"]["x-api-key"], "sk_test_x")
+        self.assertTrue(call["headers"]["user-agent"].startswith("zerelay-python/"))
+        self.assertEqual(len(call["headers"]["idempotency-key"]), 36)
+        self.assertEqual(call["body"], {"to": "a@example.com", "subject": "s", "body": "b"})
+        m.close()
+
+    def test_429_retry_after_keeps_idempotency_key(self):
+        m = Mock(lambda n: (429, {"detail": "Rate limit exceeded"}, {"Retry-After": "1"}) if n == 1 else (200, {"id": "sms_1"}, None))
+        zr = Zerelay("sk_x", base_url=m.url)
+        t0 = time.time()
+        self.assertEqual(zr.sms.send(to="08031234567", body="hi")["id"], "sms_1")
+        self.assertGreaterEqual(time.time() - t0, 0.9)
+        self.assertEqual(m.calls[0]["headers"]["idempotency-key"], m.calls[1]["headers"]["idempotency-key"])
+        m.close()
+
+    def test_503_only_retried_when_safe(self):
+        m = Mock(lambda n: (503, {"detail": "Worker unavailable"}, None))
+        zr = Zerelay("sk_x", base_url=m.url, max_retries=1)
+        with self.assertRaises(ZerelayError) as ctx:
+            zr.emails.send_bulk(recipients=["a@example.com"], subject="s", body="b")
+        self.assertEqual(ctx.exception.status, 503)
+        self.assertEqual(str(ctx.exception), "Worker unavailable")
+        self.assertEqual(len(m.calls), 1)
+        with self.assertRaises(ZerelayError):
+            zr.emails.get("t1")
+        self.assertEqual(len(m.calls), 3)
+        m.close()
+
+    def test_validation_detail(self):
+        m = Mock(lambda n: (422, {"detail": [{"loc": ["body", "to"], "msg": "value is not a valid email address"}]}, None))
+        with self.assertRaisesRegex(ZerelayError, r"body\.to: value is not a valid email address"):
+            Zerelay("sk_x", base_url=m.url).emails.send(to="x", subject="s", body="b")
+        m.close()
+
+    def test_202_no_body_and_query(self):
+        m = Mock(lambda n: (202, None, {"X-Zerelay-Test-Mode": "true"}) if n == 1 else (200, [], None))
+        zr = Zerelay("sk_x", base_url=m.url + "/")
+        self.assertEqual(zr.emails.mail_send({"personalizations": []}), {"status": 202, "test_mode": True})
+        zr.sms.get("sms_a/b", refresh=True)
+        self.assertEqual(m.calls[1]["path"], "/sms/messages/sms_a%2Fb?refresh=true")
+        m.close()
+
+    def test_network_error(self):
+        zr = Zerelay("sk_x", base_url="http://127.0.0.1:1", max_retries=0, timeout=2)
+        with self.assertRaisesRegex(ZerelayError, "failed"):
+            zr.sms.wallet()
+
+    def test_missing_key(self):
+        saved = os.environ.pop("ZERELAY_API_KEY", None)
+        with self.assertRaises(ValueError):
+            Zerelay()
+        if saved:
+            os.environ["ZERELAY_API_KEY"] = saved
+
+
+class WebhookTests(unittest.TestCase):
+    secret = "whsec_test"
+
+    def sign(self, body: bytes, ts: str) -> str:
+        return "sha256=" + hmac.new(self.secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
+
+    def test_valid_and_legacy(self):
+        body = json.dumps({"id": 1, "event": "delivered"}).encode()
+        ts = str(int(time.time()))
+        sig = self.sign(body, ts)
+        self.assertEqual(verify_webhook(body, {"X-Zerelay-Signature": sig, "X-Zerelay-Timestamp": ts}, self.secret)["event"], "delivered")
+        self.assertEqual(verify_webhook(body.decode(), {"x-smtp-signature": sig, "x-smtp-timestamp": ts}, self.secret)["id"], 1)
+
+    def test_rejections(self):
+        body = b'{"id":1}'
+        ts = str(int(time.time()))
+        sig = self.sign(body, ts)
+        with self.assertRaisesRegex(ZerelayWebhookError, "Invalid webhook signature"):
+            verify_webhook(body + b" ", {"x-zerelay-signature": sig, "x-zerelay-timestamp": ts}, self.secret)
+        with self.assertRaisesRegex(ZerelayWebhookError, "Invalid webhook signature"):
+            verify_webhook(body, {"x-zerelay-signature": sig, "x-zerelay-timestamp": ts}, "whsec_other")
+        old = str(int(time.time()) - 3600)
+        with self.assertRaisesRegex(ZerelayWebhookError, "tolerance"):
+            verify_webhook(body, {"x-zerelay-signature": self.sign(body, old), "x-zerelay-timestamp": old}, self.secret)
+        self.assertEqual(verify_webhook(body, {"x-zerelay-signature": self.sign(body, old), "x-zerelay-timestamp": old}, self.secret, tolerance_seconds=0)["id"], 1)
+        with self.assertRaisesRegex(ZerelayWebhookError, "Missing"):
+            verify_webhook(body, {}, self.secret)
+
+
+if __name__ == "__main__":
+    unittest.main()