vaartix 0.1.0__tar.gz

vaartix-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.env
+.env.*

vaartix-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0
+
+- First release: `emails.send`, `get`, `list`, `cancel`, `batch.send`, webhook endpoints, and
+  `verify_webhook` for signed webhooks (Standard Webhooks).
+- Idempotency keys, scheduled sending and test mode.
+- No dependencies; Python 3.10 or newer; fully typed.

vaartix-0.1.0/LICENSE

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

vaartix-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: vaartix
+Version: 0.1.0
+Summary: Official Python SDK for the Vaartix email API
+Project-URL: Homepage, https://vaartix.com
+Project-URL: Documentation, https://vaartix.com/docs/
+Project-URL: Source, https://github.com/vaartix-mail/vaartix-python
+Project-URL: Issues, https://github.com/vaartix-mail/vaartix-python/issues
+Project-URL: Changelog, https://github.com/vaartix-mail/vaartix-python/blob/main/CHANGELOG.md
+Author-email: NAP Designs <support@vaartix.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,email,india,sdk,ses,transactional-email,vaartix
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# vaartix
+
+Official Python SDK for [Vaartix](https://vaartix.com), the email API for Indian developers.
+
+> Vaartix is in private beta. [Request early access](https://vaartix.com/#early-access).
+
+```sh
+pip install vaartix
+```
+
+Python 3.10 or newer. No dependencies.
+
+## Send an email
+
+```python
+from vaartix import Vaartix
+
+vaartix = Vaartix()  # reads the VAARTIX_API_KEY environment variable
+
+email = vaartix.emails.send(
+    {
+        "from": "Acme <onboarding@acme.in>",
+        "to": ["priya@example.com"],
+        "subject": "Hello from Vaartix",
+        "html": "<strong>It works!</strong>",
+    }
+)
+print(email["id"])  # em_...
+```
+
+Emails are plain dicts because `from` is a Python keyword. Keys can be `snake_case`
+(`reply_to`, `scheduled_at`) or the API's camelCase (`replyTo`, `scheduledAt`). Responses are the
+API's JSON as dicts, exactly as in the [API reference](https://vaartix.com/docs/).
+
+```python
+# Retry safely: the same key within 24 hours returns the first email instead of sending twice.
+vaartix.emails.send(email, idempotency_key=f"welcome-{user.id}")
+
+# Send later (up to 30 days ahead), and cancel if plans change.
+scheduled = vaartix.emails.send({**email, "scheduled_at": "2026-11-01T09:00:00+05:30"})
+vaartix.emails.cancel(scheduled["id"])
+
+# Up to 100 emails in one request.
+vaartix.batch.send([email_1, email_2])
+
+# Look up an email and its delivery events, or list recent bounces.
+vaartix.emails.get("em_...")
+vaartix.emails.list(status="bounced", days=7)
+
+# Try it without a domain: test addresses simulate delivery, bounces and complaints.
+vaartix.emails.send(
+    {
+        "from": "onboarding@test.vaartix.com",
+        "to": "delivered@test.vaartix.com",
+        "subject": "Hello",
+        "text": "It works!",
+    }
+)
+```
+
+## Errors
+
+API and network errors raise `VaartixError`:
+
+```python
+from vaartix import VaartixError
+
+try:
+    vaartix.emails.send(email)
+except VaartixError as err:
+    print(err.type, err.status_code, err.message)  # e.g. rate_limited 429 Too many requests...
+```
+
+`err.type` is a stable code; the full list is in [Errors](https://vaartix.com/docs/concepts/errors/).
+Network failures have `type == "network_error"` and `status_code is None`.
+
+## Webhooks
+
+Check that a webhook request really came from Vaartix before trusting it. Pass the **raw** body.
+
+```python
+import os
+
+from flask import Flask, request
+from vaartix import verify_webhook, WebhookVerificationError
+
+app = Flask(__name__)
+
+
+@app.post("/webhooks/vaartix")
+def vaartix_webhook():
+    try:
+        event = verify_webhook(
+            request.get_data(),  # raw bytes, not request.json
+            request.headers,
+            os.environ["VAARTIX_WEBHOOK_SECRET"],
+        )
+    except WebhookVerificationError:
+        return "", 400
+    if event["type"] == "email.bounced":
+        ...  # stop emailing event["data"]["recipient"]
+    return "", 200
+```
+
+In Django use `request.body` and `request.headers`. Signatures follow the
+[Standard Webhooks](https://www.standardwebhooks.com) spec.
+
+Manage endpoints with `vaartix.webhooks.create(url=..., events=[...])`, `list()`, `get()`,
+`update()`, `remove()`, `rotate_secret()`, `deliveries()` and `retry_delivery()`.
+
+## Docs
+
+Full API reference and guides: [vaartix.com/docs](https://vaartix.com/docs/).
+
+## Contributing and security
+
+Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Please report
+security problems privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

vaartix-0.1.0/README.md

@@ -0,0 +1,122 @@
+# vaartix
+
+Official Python SDK for [Vaartix](https://vaartix.com), the email API for Indian developers.
+
+> Vaartix is in private beta. [Request early access](https://vaartix.com/#early-access).
+
+```sh
+pip install vaartix
+```
+
+Python 3.10 or newer. No dependencies.
+
+## Send an email
+
+```python
+from vaartix import Vaartix
+
+vaartix = Vaartix()  # reads the VAARTIX_API_KEY environment variable
+
+email = vaartix.emails.send(
+    {
+        "from": "Acme <onboarding@acme.in>",
+        "to": ["priya@example.com"],
+        "subject": "Hello from Vaartix",
+        "html": "<strong>It works!</strong>",
+    }
+)
+print(email["id"])  # em_...
+```
+
+Emails are plain dicts because `from` is a Python keyword. Keys can be `snake_case`
+(`reply_to`, `scheduled_at`) or the API's camelCase (`replyTo`, `scheduledAt`). Responses are the
+API's JSON as dicts, exactly as in the [API reference](https://vaartix.com/docs/).
+
+```python
+# Retry safely: the same key within 24 hours returns the first email instead of sending twice.
+vaartix.emails.send(email, idempotency_key=f"welcome-{user.id}")
+
+# Send later (up to 30 days ahead), and cancel if plans change.
+scheduled = vaartix.emails.send({**email, "scheduled_at": "2026-11-01T09:00:00+05:30"})
+vaartix.emails.cancel(scheduled["id"])
+
+# Up to 100 emails in one request.
+vaartix.batch.send([email_1, email_2])
+
+# Look up an email and its delivery events, or list recent bounces.
+vaartix.emails.get("em_...")
+vaartix.emails.list(status="bounced", days=7)
+
+# Try it without a domain: test addresses simulate delivery, bounces and complaints.
+vaartix.emails.send(
+    {
+        "from": "onboarding@test.vaartix.com",
+        "to": "delivered@test.vaartix.com",
+        "subject": "Hello",
+        "text": "It works!",
+    }
+)
+```
+
+## Errors
+
+API and network errors raise `VaartixError`:
+
+```python
+from vaartix import VaartixError
+
+try:
+    vaartix.emails.send(email)
+except VaartixError as err:
+    print(err.type, err.status_code, err.message)  # e.g. rate_limited 429 Too many requests...
+```
+
+`err.type` is a stable code; the full list is in [Errors](https://vaartix.com/docs/concepts/errors/).
+Network failures have `type == "network_error"` and `status_code is None`.
+
+## Webhooks
+
+Check that a webhook request really came from Vaartix before trusting it. Pass the **raw** body.
+
+```python
+import os
+
+from flask import Flask, request
+from vaartix import verify_webhook, WebhookVerificationError
+
+app = Flask(__name__)
+
+
+@app.post("/webhooks/vaartix")
+def vaartix_webhook():
+    try:
+        event = verify_webhook(
+            request.get_data(),  # raw bytes, not request.json
+            request.headers,
+            os.environ["VAARTIX_WEBHOOK_SECRET"],
+        )
+    except WebhookVerificationError:
+        return "", 400
+    if event["type"] == "email.bounced":
+        ...  # stop emailing event["data"]["recipient"]
+    return "", 200
+```
+
+In Django use `request.body` and `request.headers`. Signatures follow the
+[Standard Webhooks](https://www.standardwebhooks.com) spec.
+
+Manage endpoints with `vaartix.webhooks.create(url=..., events=[...])`, `list()`, `get()`,
+`update()`, `remove()`, `rotate_secret()`, `deliveries()` and `retry_delivery()`.
+
+## Docs
+
+Full API reference and guides: [vaartix.com/docs](https://vaartix.com/docs/).
+
+## Contributing and security
+
+Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Please report
+security problems privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

vaartix-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vaartix"
+dynamic = ["version"]
+description = "Official Python SDK for the Vaartix email API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "NAP Designs", email = "support@vaartix.com" }]
+keywords = ["email", "transactional-email", "api", "india", "vaartix", "ses", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Communications :: Email",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://vaartix.com"
+Documentation = "https://vaartix.com/docs/"
+Source = "https://github.com/vaartix-mail/vaartix-python"
+Issues = "https://github.com/vaartix-mail/vaartix-python/issues"
+Changelog = "https://github.com/vaartix-mail/vaartix-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/vaartix/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["UP006", "UP007", "UP035", "UP045"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src"]

vaartix-0.1.0/src/vaartix/__init__.py

@@ -0,0 +1,14 @@
+"""Official Python SDK for Vaartix, the email API for Indian developers."""
+
+from ._client import Vaartix
+from ._errors import VaartixError, WebhookVerificationError
+from ._verify import verify_webhook
+from ._version import __version__
+
+__all__ = [
+    "Vaartix",
+    "VaartixError",
+    "WebhookVerificationError",
+    "__version__",
+    "verify_webhook",
+]

vaartix-0.1.0/src/vaartix/_client.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple
+
+from ._errors import VaartixError
+from ._types import (
+    SendEmailParams,
+    SendEmailResponse,
+    Webhook,
+    WebhookEventType,
+    WebhookWithSecret,
+)
+from ._verify import verify_webhook
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.vaartix.com"
+
+# (method, url, headers, body, timeout) -> (status code, response body)
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Tuple[int, bytes]]
+
+# snake_case keys Python developers expect, mapped to the API's names.
+_KEY_NAMES = {
+    "reply_to": "replyTo",
+    "scheduled_at": "scheduledAt",
+    "content_type": "contentType",
+    "content_id": "contentId",
+}
+
+
+def _api_keys(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {_KEY_NAMES.get(k, k): _api_keys(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_api_keys(v) for v in value]
+    return value
+
+
+def _urllib_transport(
+    method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float
+) -> Tuple[int, bytes]:
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, response.read()
+    except urllib.error.HTTPError as err:
+        return err.code, err.read()
+
+
+def _trim_trailing_slashes(url: str) -> str:
+    end = len(url)
+    while end > 0 and url[end - 1] == "/":
+        end -= 1
+    return url[:end]
+
+
+class Vaartix:
+    """Client for the Vaartix email API.
+
+    >>> vaartix = Vaartix()  # reads VAARTIX_API_KEY
+    >>> vaartix.emails.send({"from": "Acme <hi@acme.in>", "to": "priya@example.com",
+    ...                      "subject": "Hello", "html": "<p>Hi</p>"})
+    {'id': 'em_...'}
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        key = api_key or os.environ.get("VAARTIX_API_KEY")
+        if not key:
+            raise ValueError(
+                'Missing API key. Pass it as Vaartix("vx_...") or set the VAARTIX_API_KEY '
+                "environment variable."
+            )
+        self._key = key
+        self._base_url = _trim_trailing_slashes(base_url or DEFAULT_BASE_URL)
+        self._timeout = timeout
+        self._transport = transport or _urllib_transport
+        self.emails = Emails(self)
+        self.batch = Batch(self)
+        self.webhooks = Webhooks(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        url = self._base_url + path
+        if query:
+            params = {k: v for k, v in query.items() if v is not None}
+            if params:
+                url += "?" + urllib.parse.urlencode(params)
+        headers = {
+            "Authorization": f"Bearer {self._key}",
+            "User-Agent": f"vaartix-python/{__version__}",
+            "Accept": "application/json",
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        try:
+            status, raw = self._transport(method, url, headers, data, self._timeout)
+        except (TimeoutError, urllib.error.URLError, OSError) as err:
+            reason = getattr(err, "reason", err)
+            raise VaartixError("network_error", str(reason)) from err
+
+        payload: Any = None
+        if raw:
+            try:
+                payload = json.loads(raw)
+            except ValueError:
+                payload = None
+        if status >= 400:
+            error = payload.get("error") if isinstance(payload, dict) else None
+            error = error if isinstance(error, dict) else {}
+            raise VaartixError(
+                str(error.get("type") or "api_error"),
+                str(error.get("message") or f"Request failed with status {status}"),
+                status,
+            )
+        return payload
+
+
+class Emails:
+    def __init__(self, client: Vaartix) -> None:
+        self._client = client
+
+    def send(
+        self, params: SendEmailParams, *, idempotency_key: Optional[str] = None
+    ) -> SendEmailResponse:
+        """Send an email. Returns ``{"id": "em_..."}`` once it is queued.
+
+        With ``idempotency_key``, retrying within 24 hours returns the first email instead of
+        sending again.
+        """
+        result: SendEmailResponse = self._client._request(
+            "POST", "/emails", _api_keys(params), idempotency_key=idempotency_key
+        )
+        return result
+
+    def get(self, email_id: str) -> Dict[str, Any]:
+        """An email with its status and event timeline. Needs a full-access key."""
+        result: Dict[str, Any] = self._client._request(
+            "GET", f"/emails/{urllib.parse.quote(email_id, safe='')}"
+        )
+        return result
+
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        before: Optional[str] = None,
+        status: Optional[str] = None,
+        search: Optional[str] = None,
+        days: Optional[int] = None,
+        api_key_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Recent emails, newest first: ``{"data": [...], "hasMore": bool}``.
+
+        Page with ``before=<last email ID>``. Needs a full-access key.
+        """
+        result: Dict[str, Any] = self._client._request(
+            "GET",
+            "/emails",
+            query={
+                "limit": limit,
+                "before": before,
+                "status": status,
+                "search": search,
+                "days": days,
+                "apiKeyId": api_key_id,
+            },
+        )
+        return result
+
+    def cancel(self, email_id: str) -> Dict[str, Any]:
+        """Cancel a scheduled email before it is sent. Needs a full-access key."""
+        result: Dict[str, Any] = self._client._request(
+            "POST", f"/emails/{urllib.parse.quote(email_id, safe='')}/cancel"
+        )
+        return result
+
+
+class Batch:
+    def __init__(self, client: Vaartix) -> None:
+        self._client = client
+
+    def send(self, emails: Sequence[SendEmailParams]) -> Dict[str, List[SendEmailResponse]]:
+        """Send up to 100 emails in one request (no attachments or scheduling). All or nothing."""
+        result: Dict[str, List[SendEmailResponse]] = self._client._request(
+            "POST", "/emails/batch", [_api_keys(e) for e in emails]
+        )
+        return result
+
+
+class Webhooks:
+    """Webhook endpoints. Managing them needs a full-access key."""
+
+    def __init__(self, client: Vaartix) -> None:
+        self._client = client
+
+    def _path(self, webhook_id: str, suffix: str = "") -> str:
+        return f"/webhooks/{urllib.parse.quote(webhook_id, safe='')}{suffix}"
+
+    def create(self, *, url: str, events: Sequence[WebhookEventType]) -> WebhookWithSecret:
+        """Create an endpoint. The response includes the signing secret, shown only this once."""
+        result: WebhookWithSecret = self._client._request(
+            "POST", "/webhooks", {"url": url, "events": list(events)}
+        )
+        return result
+
+    def list(self) -> Dict[str, List[Webhook]]:
+        result: Dict[str, List[Webhook]] = self._client._request("GET", "/webhooks")
+        return result
+
+    def get(self, webhook_id: str) -> Webhook:
+        result: Webhook = self._client._request("GET", self._path(webhook_id))
+        return result
+
+    def update(
+        self,
+        webhook_id: str,
+        *,
+        url: Optional[str] = None,
+        events: Optional[Sequence[WebhookEventType]] = None,
+        status: Optional[str] = None,
+    ) -> Webhook:
+        """Change the URL or events, or turn the endpoint off (``status="disabled"``) and on."""
+        body: Dict[str, Any] = {}
+        if url is not None:
+            body["url"] = url
+        if events is not None:
+            body["events"] = list(events)
+        if status is not None:
+            body["status"] = status
+        result: Webhook = self._client._request("PATCH", self._path(webhook_id), body)
+        return result
+
+    def remove(self, webhook_id: str) -> None:
+        self._client._request("DELETE", self._path(webhook_id))
+
+    def rotate_secret(self, webhook_id: str) -> WebhookWithSecret:
+        """Replace the signing secret. The old one stops working immediately."""
+        result: WebhookWithSecret = self._client._request(
+            "POST", self._path(webhook_id, "/rotate-secret")
+        )
+        return result
+
+    def deliveries(self, webhook_id: str, *, limit: Optional[int] = None) -> Dict[str, Any]:
+        """Recent deliveries to an endpoint, newest first, with your server's responses."""
+        result: Dict[str, Any] = self._client._request(
+            "GET", self._path(webhook_id, "/deliveries"), query={"limit": limit}
+        )
+        return result
+
+    def retry_delivery(self, webhook_id: str, delivery_id: str) -> Dict[str, Any]:
+        """Send a delivery again, with the same ``webhook-id``."""
+        path = self._path(
+            webhook_id, f"/deliveries/{urllib.parse.quote(delivery_id, safe='')}/retry"
+        )
+        result: Dict[str, Any] = self._client._request("POST", path)
+        return result
+
+    @staticmethod
+    def verify(
+        payload: Any, headers: Mapping[str, Any], secret: str, tolerance_seconds: int = 300
+    ) -> Dict[str, Any]:
+        """Same as the standalone ``verify_webhook``."""
+        return verify_webhook(payload, headers, secret, tolerance_seconds)

vaartix-0.1.0/src/vaartix/_errors.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class VaartixError(Exception):
+    """Raised when the API returns an error or cannot be reached.
+
+    ``type`` is a stable code such as ``validation_error`` or ``rate_limited`` (see
+    https://vaartix.com/docs/concepts/errors/). ``status_code`` is ``None`` for network errors.
+    """
+
+    def __init__(self, type: str, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.type = type
+        self.message = message
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return (
+            f"VaartixError(type={self.type!r}, message={self.message!r}, "
+            f"status_code={self.status_code!r})"
+        )
+
+
+class WebhookVerificationError(Exception):
+    """Raised by ``verify_webhook`` when a request's signature or timestamp is not valid."""

vaartix-0.1.0/src/vaartix/_types.py

@@ -0,0 +1,83 @@
+"""Shapes of the data the API accepts and returns. Responses are the API's JSON, unchanged."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+Addresses = Union[str, List[str]]
+
+
+class Tag(TypedDict):
+    name: str
+    value: str
+
+
+class _AttachmentRequired(TypedDict):
+    filename: str
+    content: str
+    """Base64-encoded file content."""
+
+
+class Attachment(_AttachmentRequired, total=False):
+    content_type: str
+    content_id: str
+    """For inline images: reference it in your HTML as ``cid:<content_id>``."""
+
+
+# "from" is a Python keyword, so emails are passed as plain dicts:
+#   {"from": "...", "to": "...", "subject": "...", "html": "..."}
+# Keys can be snake_case (reply_to, scheduled_at) or the API's camelCase (replyTo, scheduledAt).
+SendEmailParams = Dict[str, Any]
+
+EmailStatus = Literal[
+    "queued",
+    "scheduled",
+    "sending",
+    "sent",
+    "delivered",
+    "delivery_delayed",
+    "bounced",
+    "complained",
+    "suppressed",
+    "failed",
+    "canceled",
+]
+
+WebhookEventType = Literal[
+    "email.sent",
+    "email.delivered",
+    "email.delivery_delayed",
+    "email.bounced",
+    "email.complained",
+    "email.rejected",
+    "email.rendering_failure",
+    "email.suppressed",
+]
+
+
+class SendEmailResponse(TypedDict):
+    id: str
+
+
+class EmailSummary(TypedDict):
+    id: str
+    status: EmailStatus
+    subject: str
+    to: List[str]
+    createdAt: str
+    sentAt: Optional[str]
+    scheduledAt: Optional[str]
+    error: Optional[str]
+
+
+class Webhook(TypedDict):
+    id: str
+    url: str
+    events: List[WebhookEventType]
+    status: Literal["enabled", "disabled"]
+    createdAt: str
+
+
+class WebhookWithSecret(Webhook):
+    secret: str
+    """The signing secret (``whsec_...``). Only returned when created or rotated."""

vaartix-0.1.0/src/vaartix/_verify.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Mapping, Optional, Union
+
+from ._errors import WebhookVerificationError
+
+_PREFIX = "whsec_"
+
+
+def _header(headers: Mapping[str, Any], name: str) -> Optional[str]:
+    # Works with dicts, Django's request.headers, Flask/Werkzeug and Starlette headers.
+    getter = getattr(headers, "get", None)
+    value = getter(name) if getter else None
+    if value is None:
+        for key in headers:
+            if str(key).lower() == name:
+                value = headers[key]
+                break
+    if isinstance(value, (list, tuple)):
+        value = value[0] if value else None
+    return None if value is None else str(value)
+
+
+def verify_webhook(
+    payload: Union[str, bytes],
+    headers: Mapping[str, Any],
+    secret: str,
+    tolerance_seconds: int = 300,
+    *,
+    now: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Check that a webhook request came from Vaartix and return its parsed JSON body.
+
+    ``payload`` must be the raw request body, exactly as received (for example
+    ``request.get_data()`` in Flask or ``request.body`` in Django), not parsed JSON.
+    Raises ``WebhookVerificationError`` if the signature or timestamp is wrong.
+
+    Follows the Standard Webhooks spec, so any Standard Webhooks library works too.
+    """
+    msg_id = _header(headers, "webhook-id")
+    timestamp = _header(headers, "webhook-timestamp")
+    signatures = _header(headers, "webhook-signature")
+    if not msg_id or not timestamp or not signatures:
+        raise WebhookVerificationError(
+            "Missing webhook-id, webhook-timestamp or webhook-signature header."
+        )
+
+    try:
+        sent_at = int(timestamp)
+    except ValueError:
+        raise WebhookVerificationError("The webhook timestamp is not a number.") from None
+    current = time.time() if now is None else now
+    if abs(current - sent_at) > tolerance_seconds:
+        raise WebhookVerificationError("The webhook timestamp is too old or in the future.")
+
+    if not secret.startswith(_PREFIX):
+        raise WebhookVerificationError(f"The secret should start with {_PREFIX}.")
+    try:
+        key = base64.b64decode(secret[len(_PREFIX) :], validate=True)
+    except (binascii.Error, ValueError):
+        raise WebhookVerificationError("The secret is not valid base64.") from None
+
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    signed = f"{msg_id}.{timestamp}.{body}".encode()
+    expected = hmac.new(key, signed, hashlib.sha256).digest()
+
+    # The header can hold several space-separated signatures, e.g. while a secret is rotated.
+    for entry in signatures.split(" "):
+        version, _, signature = entry.partition(",")
+        if version != "v1" or not signature:
+            continue
+        try:
+            given = base64.b64decode(signature)
+        except (binascii.Error, ValueError):
+            continue
+        if hmac.compare_digest(given, expected):
+            parsed: Dict[str, Any] = json.loads(body)
+            return parsed
+    raise WebhookVerificationError("The webhook signature does not match.")

vaartix-0.1.0/src/vaartix/_version.py

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

vaartix-0.1.0/tests/test_client.py

@@ -0,0 +1,164 @@
+import json
+import urllib.error
+
+import pytest
+
+from vaartix import Vaartix, VaartixError, __version__
+
+
+class FakeTransport:
+    def __init__(self, status=200, body=None):
+        self.status = status
+        self.body = body if body is not None else {"id": "em_1"}
+        self.calls = []
+
+    def __call__(self, method, url, headers, data, timeout):
+        self.calls.append(
+            {
+                "method": method,
+                "url": url,
+                "headers": headers,
+                "json": json.loads(data) if data else None,
+                "timeout": timeout,
+            }
+        )
+        raw = self.body if isinstance(self.body, bytes) else json.dumps(self.body).encode()
+        return self.status, raw
+
+
+def client(transport, **kwargs):
+    return Vaartix("vx_test", transport=transport, **kwargs)
+
+
+def test_sends_with_auth_json_and_idempotency_key():
+    t = FakeTransport()
+    result = client(t, base_url="https://api.example.test/").emails.send(
+        {"from": "a@acme.in", "to": "b@example.com", "subject": "Hi", "html": "<p>Hi</p>"},
+        idempotency_key="order-42",
+    )
+    assert result == {"id": "em_1"}
+    call = t.calls[0]
+    assert call["method"] == "POST"
+    assert call["url"] == "https://api.example.test/emails"
+    assert call["headers"]["Authorization"] == "Bearer vx_test"
+    assert call["headers"]["Idempotency-Key"] == "order-42"
+    assert call["headers"]["User-Agent"] == f"vaartix-python/{__version__}"
+    assert call["json"]["subject"] == "Hi"
+
+
+def test_snake_case_keys_become_api_names():
+    t = FakeTransport()
+    client(t).emails.send(
+        {
+            "from": "a@acme.in",
+            "to": ["b@example.com"],
+            "subject": "Invoice",
+            "text": "Attached",
+            "reply_to": "billing@acme.in",
+            "scheduled_at": "2026-11-01T09:00:00+05:30",
+            "attachments": [
+                {"filename": "a.pdf", "content": "QQ==", "content_type": "application/pdf"}
+            ],
+        }
+    )
+    sent = t.calls[0]["json"]
+    assert sent["replyTo"] == "billing@acme.in"
+    assert sent["scheduledAt"] == "2026-11-01T09:00:00+05:30"
+    assert sent["attachments"][0]["contentType"] == "application/pdf"
+    assert "reply_to" not in sent
+
+
+def test_api_errors_raise_vaartix_error():
+    t = FakeTransport(422, {"error": {"type": "validation_error", "message": "from is required"}})
+    with pytest.raises(VaartixError) as info:
+        client(t).emails.send({"to": "b@example.com", "subject": "Hi"})
+    assert info.value.type == "validation_error"
+    assert info.value.message == "from is required"
+    assert info.value.status_code == 422
+
+
+def test_non_json_errors_still_raise():
+    t = FakeTransport(502, b"<html>Bad gateway</html>")
+    with pytest.raises(VaartixError) as info:
+        client(t).emails.get("em_1")
+    assert info.value.type == "api_error"
+    assert info.value.status_code == 502
+
+
+def test_network_errors_raise_with_no_status():
+    def broken(*args):
+        raise urllib.error.URLError("connection refused")
+
+    with pytest.raises(VaartixError) as info:
+        client(broken).emails.get("em_1")
+    assert info.value.type == "network_error"
+    assert info.value.status_code is None
+
+
+def test_list_builds_query_and_skips_empty_filters():
+    t = FakeTransport(body={"data": [], "hasMore": False})
+    client(t).emails.list(limit=5, status="bounced", api_key_id="key_1")
+    assert (
+        t.calls[0]["url"] == "https://api.vaartix.com/emails?limit=5&status=bounced&apiKeyId=key_1"
+    )
+
+
+def test_ids_are_escaped_in_paths():
+    t = FakeTransport(body={"id": "em_1", "status": "canceled"})
+    client(t).emails.cancel("em_1/../x")
+    assert t.calls[0]["url"] == "https://api.vaartix.com/emails/em_1%2F..%2Fx/cancel"
+
+
+def test_batch_sends_a_list():
+    t = FakeTransport(body={"data": [{"id": "em_1"}, {"id": "em_2"}]})
+    result = client(t).batch.send(
+        [
+            {"from": "a@acme.in", "to": "b@example.com", "subject": "1", "text": "x"},
+            {
+                "from": "a@acme.in",
+                "to": "c@example.com",
+                "subject": "2",
+                "text": "y",
+                "reply_to": "r@acme.in",
+            },
+        ]
+    )
+    assert [e["id"] for e in result["data"]] == ["em_1", "em_2"]
+    assert t.calls[0]["url"].endswith("/emails/batch")
+    assert t.calls[0]["json"][1]["replyTo"] == "r@acme.in"
+
+
+def test_webhook_management():
+    t = FakeTransport(body={"id": "wh_1", "status": "disabled"})
+    hooks = client(t).webhooks
+    hooks.create(url="https://acme.in/hooks", events=["email.bounced"])
+    hooks.update("wh_1", status="disabled")
+    hooks.deliveries("wh_1", limit=10)
+    hooks.retry_delivery("wh_1", "whd_1")
+    assert [(c["method"], c["url"].replace("https://api.vaartix.com", "")) for c in t.calls] == [
+        ("POST", "/webhooks"),
+        ("PATCH", "/webhooks/wh_1"),
+        ("GET", "/webhooks/wh_1/deliveries?limit=10"),
+        ("POST", "/webhooks/wh_1/deliveries/whd_1/retry"),
+    ]
+    assert t.calls[0]["json"] == {"url": "https://acme.in/hooks", "events": ["email.bounced"]}
+    assert t.calls[1]["json"] == {"status": "disabled"}
+
+
+def test_api_key_from_environment(monkeypatch):
+    monkeypatch.setenv("VAARTIX_API_KEY", "vx_env")
+    t = FakeTransport()
+    Vaartix(transport=t).emails.get("em_1")
+    assert t.calls[0]["headers"]["Authorization"] == "Bearer vx_env"
+
+
+def test_missing_api_key(monkeypatch):
+    monkeypatch.delenv("VAARTIX_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="VAARTIX_API_KEY"):
+        Vaartix()
+
+
+def test_many_trailing_slashes_in_base_url():
+    t = FakeTransport()
+    client(t, base_url="https://api.example.test" + "/" * 50_000).emails.get("em_1")
+    assert t.calls[0]["url"] == "https://api.example.test/emails/em_1"

vaartix-0.1.0/tests/test_verify.py

@@ -0,0 +1,79 @@
+import base64
+import hashlib
+import hmac
+import json
+
+import pytest
+
+from vaartix import Vaartix, WebhookVerificationError, verify_webhook
+
+# Test-only secrets, built from a separate prefix so secret scanners don't flag them.
+PREFIX = "whsec_"
+
+# The worked example from the Standard Webhooks specification.
+SPEC_SECRET = f"{PREFIX}MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
+SPEC_HEADERS = {
+    "webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
+    "webhook-timestamp": "1614265330",
+    "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
+}
+SPEC_BODY = '{"test": 2432232314}'
+SPEC_NOW = 1614265330
+
+
+def sign(secret, msg_id, timestamp, body):
+    key = base64.b64decode(secret[len(PREFIX) :])
+    digest = hmac.new(key, f"{msg_id}.{timestamp}.{body}".encode(), hashlib.sha256).digest()
+    return "v1," + base64.b64encode(digest).decode()
+
+
+def test_matches_the_standard_webhooks_example():
+    assert verify_webhook(SPEC_BODY, SPEC_HEADERS, SPEC_SECRET, now=SPEC_NOW) == {
+        "test": 2432232314
+    }
+
+
+def test_accepts_bytes_and_any_header_case():
+    headers = {k.title(): v for k, v in SPEC_HEADERS.items()}
+    assert (
+        verify_webhook(SPEC_BODY.encode(), headers, SPEC_SECRET, now=SPEC_NOW)["test"] == 2432232314
+    )
+
+
+def test_accepts_one_valid_signature_among_several():
+    headers = dict(SPEC_HEADERS)
+    headers["webhook-signature"] = "v1,AAAA " + SPEC_HEADERS["webhook-signature"]
+    verify_webhook(SPEC_BODY, headers, SPEC_SECRET, now=SPEC_NOW)
+
+
+def test_rejects_a_changed_body():
+    with pytest.raises(WebhookVerificationError, match="does not match"):
+        verify_webhook('{"test": 1}', SPEC_HEADERS, SPEC_SECRET, now=SPEC_NOW)
+
+
+def test_rejects_old_timestamps():
+    with pytest.raises(WebhookVerificationError, match="too old"):
+        verify_webhook(SPEC_BODY, SPEC_HEADERS, SPEC_SECRET, now=SPEC_NOW + 301)
+
+
+def test_rejects_missing_headers_and_bad_secrets():
+    with pytest.raises(WebhookVerificationError, match="Missing"):
+        verify_webhook(SPEC_BODY, {}, SPEC_SECRET, now=SPEC_NOW)
+    with pytest.raises(WebhookVerificationError, match="start with"):
+        verify_webhook(SPEC_BODY, SPEC_HEADERS, "not-a-secret", now=SPEC_NOW)
+
+
+def test_round_trip_with_a_vaartix_style_payload():
+    secret = f"{PREFIX}" + base64.b64encode(b"x" * 24).decode()
+    body = json.dumps({"type": "email.bounced", "data": {"recipient": "priya@example.com"}})
+    headers = {
+        "webhook-id": "whd_1",
+        "webhook-timestamp": "1793181600",
+        "webhook-signature": sign(secret, "whd_1", "1793181600", body),
+    }
+    result = verify_webhook(body, headers, secret, now=1793181600)
+    assert result["data"]["recipient"] == "priya@example.com"
+    # The client exposes the same check.
+    client = Vaartix("vx_test", transport=lambda *a: (200, b"{}"))
+    with pytest.raises(WebhookVerificationError):
+        client.webhooks.verify(body, headers, secret)  # real clock: timestamp is far off