notifyvia-email 0.1.0__tar.gz

notifyvia_email-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.3
+Name: notifyvia-email
+Version: 0.1.0
+Summary: The frontend Python library for notifyvia.email
+Requires-Dist: requests>=2.34.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# notifyvia-email
+
+The frontend Python library for [notifyvia.email](https://notifyvia.email/docs).
+
+## Installation
+
+```bash
+pip install notifyvia-email
+```
+
+or with uv:
+
+```bash
+uv add notifyvia-email
+```
+
+Requires Python 3.13+.
+
+## Quick start
+
+```python
+from notifyvia_email.v2 import NotifyViaEmail, SendResult
+
+client = NotifyViaEmail(api_key="your-api-key")
+
+resp = client.send(
+    to="you@example.com",
+    subject="A message from your website",
+    text="Do you have any strawberry cheesecake?",
+)
+
+if resp.ok:
+    print("Email queued for delivery")
+else:
+    print(resp.result, resp.errors)
+```
+
+## API versions
+
+Each API version has its own client with the same interface:
+
+```python
+from notifyvia_email.v1 import NotifyViaEmail  # POST /api/v1/send
+from notifyvia_email.v2 import NotifyViaEmail  # POST /api/v2/send
+```
+
+v2 adds the `reply_to` parameter. Everything else is shared.
+
+## Sending HTML
+
+Provide `html`, `text`, or both. At least one is required, otherwise `send()` raises `ValueError`.
+
+```python
+resp = client.send(
+    to="you@example.com",
+    subject="Welcome!",
+    html="<h1>Welcome</h1><p>Thanks for signing up.</p>",
+    text="Welcome! Thanks for signing up.",
+    reply_to="support@example.com",  # v2 only
+)
+```
+
+## Spam checking and rate limiting
+
+A typical contact form setup. The rate limiter needs the sender's IPv4 address.
+
+```python
+resp = client.send(
+    to="owner@example.com",
+    subject="New contact form submission",
+    text=form_message,
+    enable_spam_checker=True,
+    enable_rate_limiter=True,
+    limit=3,             # max requests...
+    within_seconds=300,  # ...per 5 minutes, per IP
+    ipv4_address=request.remote_addr,
+)
+```
+
+## Choosing a service
+
+```python
+resp = client.send(
+    to="you@example.com",
+    subject="Hello",
+    text="Sent via Postmark",
+    service="postmark",  # "zepto" (default) or "postmark"
+)
+```
+
+## Handling the response
+
+`send()` returns a `SendResponse` with:
+
+- `result`: a `SendResult` enum member
+- `errors`: the API's `errors` field (or `None`), e.g. per-field validation messages
+- `ok`: `True` when the email was accepted for delivery
+
+```python
+from notifyvia_email.v2 import SendResult
+
+resp = client.send(to="not-an-email", subject="Hi", text="Hello")
+
+match resp.result:
+    case SendResult.EMAIL_PROVISIONING:
+        print("Sent")
+    case SendResult.INVALID:
+        print("Validation failed:", resp.errors)
+        # {'to': ['Not a valid email address.']}
+    case SendResult.RATE_LIMIT_EXCEEDED:
+        print("Too many requests, try again later")
+    case SendResult.SPAM_DETECTED:
+        print("Message rejected as spam")
+    case SendResult.CONNECTION_ERROR:
+        print("Could not reach notifyvia.email:", resp.errors)
+    case _:
+        print("Failed:", resp.result.name, resp.errors)
+```
+
+| `SendResult`                | HTTP | Meaning                                          |
+|-----------------------------|------|--------------------------------------------------|
+| `EMAIL_PROVISIONING`        | 200  | Accepted and queued for delivery                 |
+| `AUTHORIZATION_REQUIRED`    | 401  | Missing or invalid API key                       |
+| `RATE_LIMIT_EXCEEDED`       | 429  | Too many requests from this IP in the window     |
+| `INVALID`                   | 460  | Request validation failed (see `errors`)         |
+| `INVALID_ACCOUNT`           | 461  | API key accepted but no matching account         |
+| `INVALID_SERVICE`           | 462  | `service` is not a supported provider            |
+| `INSUFFICIENT_CREDITS`      | 463  | Not enough credits to send                       |
+| `IPV4_ADDRESS_NOT_PROVIDED` | 464  | Rate limiter enabled without `ipv4_address`      |
+| `SPAM_DETECTED`             | 465  | Body matched the spam dictionary                 |
+| `SENDER_IPV4_BLOCKED`       | 466  | Sender IP is on the global block list            |
+| `UNKNOWN_ERROR`             | -    | Unexpected status code from the API              |
+| `CONNECTION_ERROR`          | -    | Network failure or timeout; `errors` has details |
+
+## Configuration
+
+```python
+client = NotifyViaEmail(api_key="your-api-key", timeout=5.0)  # seconds, default 10
+```
+
+See the [notifyvia.email docs](https://notifyvia.email/docs) for full API details.

notifyvia_email-0.1.0/README.md

@@ -0,0 +1,141 @@
+# notifyvia-email
+
+The frontend Python library for [notifyvia.email](https://notifyvia.email/docs).
+
+## Installation
+
+```bash
+pip install notifyvia-email
+```
+
+or with uv:
+
+```bash
+uv add notifyvia-email
+```
+
+Requires Python 3.13+.
+
+## Quick start
+
+```python
+from notifyvia_email.v2 import NotifyViaEmail, SendResult
+
+client = NotifyViaEmail(api_key="your-api-key")
+
+resp = client.send(
+    to="you@example.com",
+    subject="A message from your website",
+    text="Do you have any strawberry cheesecake?",
+)
+
+if resp.ok:
+    print("Email queued for delivery")
+else:
+    print(resp.result, resp.errors)
+```
+
+## API versions
+
+Each API version has its own client with the same interface:
+
+```python
+from notifyvia_email.v1 import NotifyViaEmail  # POST /api/v1/send
+from notifyvia_email.v2 import NotifyViaEmail  # POST /api/v2/send
+```
+
+v2 adds the `reply_to` parameter. Everything else is shared.
+
+## Sending HTML
+
+Provide `html`, `text`, or both. At least one is required, otherwise `send()` raises `ValueError`.
+
+```python
+resp = client.send(
+    to="you@example.com",
+    subject="Welcome!",
+    html="<h1>Welcome</h1><p>Thanks for signing up.</p>",
+    text="Welcome! Thanks for signing up.",
+    reply_to="support@example.com",  # v2 only
+)
+```
+
+## Spam checking and rate limiting
+
+A typical contact form setup. The rate limiter needs the sender's IPv4 address.
+
+```python
+resp = client.send(
+    to="owner@example.com",
+    subject="New contact form submission",
+    text=form_message,
+    enable_spam_checker=True,
+    enable_rate_limiter=True,
+    limit=3,             # max requests...
+    within_seconds=300,  # ...per 5 minutes, per IP
+    ipv4_address=request.remote_addr,
+)
+```
+
+## Choosing a service
+
+```python
+resp = client.send(
+    to="you@example.com",
+    subject="Hello",
+    text="Sent via Postmark",
+    service="postmark",  # "zepto" (default) or "postmark"
+)
+```
+
+## Handling the response
+
+`send()` returns a `SendResponse` with:
+
+- `result`: a `SendResult` enum member
+- `errors`: the API's `errors` field (or `None`), e.g. per-field validation messages
+- `ok`: `True` when the email was accepted for delivery
+
+```python
+from notifyvia_email.v2 import SendResult
+
+resp = client.send(to="not-an-email", subject="Hi", text="Hello")
+
+match resp.result:
+    case SendResult.EMAIL_PROVISIONING:
+        print("Sent")
+    case SendResult.INVALID:
+        print("Validation failed:", resp.errors)
+        # {'to': ['Not a valid email address.']}
+    case SendResult.RATE_LIMIT_EXCEEDED:
+        print("Too many requests, try again later")
+    case SendResult.SPAM_DETECTED:
+        print("Message rejected as spam")
+    case SendResult.CONNECTION_ERROR:
+        print("Could not reach notifyvia.email:", resp.errors)
+    case _:
+        print("Failed:", resp.result.name, resp.errors)
+```
+
+| `SendResult`                | HTTP | Meaning                                          |
+|-----------------------------|------|--------------------------------------------------|
+| `EMAIL_PROVISIONING`        | 200  | Accepted and queued for delivery                 |
+| `AUTHORIZATION_REQUIRED`    | 401  | Missing or invalid API key                       |
+| `RATE_LIMIT_EXCEEDED`       | 429  | Too many requests from this IP in the window     |
+| `INVALID`                   | 460  | Request validation failed (see `errors`)         |
+| `INVALID_ACCOUNT`           | 461  | API key accepted but no matching account         |
+| `INVALID_SERVICE`           | 462  | `service` is not a supported provider            |
+| `INSUFFICIENT_CREDITS`      | 463  | Not enough credits to send                       |
+| `IPV4_ADDRESS_NOT_PROVIDED` | 464  | Rate limiter enabled without `ipv4_address`      |
+| `SPAM_DETECTED`             | 465  | Body matched the spam dictionary                 |
+| `SENDER_IPV4_BLOCKED`       | 466  | Sender IP is on the global block list            |
+| `UNKNOWN_ERROR`             | -    | Unexpected status code from the API              |
+| `CONNECTION_ERROR`          | -    | Network failure or timeout; `errors` has details |
+
+## Configuration
+
+```python
+client = NotifyViaEmail(api_key="your-api-key", timeout=5.0)  # seconds, default 10
+```
+
+See the [notifyvia.email docs](https://notifyvia.email/docs) for full API details.

notifyvia_email-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "notifyvia-email"
+version = "0.1.0"
+description = "The frontend Python library for notifyvia.email"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["requests>=2.34.2"]
+
+[dependency-groups]
+dev = ["pyqwe>=3.2.0"]
+
+[tool.pyqwe]
+sync = "*:uv run --env-file .index-notifyviaemail -- uv sync"
+build = "*:uv build"
+publish = "*:uv run --env-file .index-notifyviaemail -- uv publish --index uilix-forgejo"
+uv = "*>:uv run --env-file .index-notifyviaemail -- uv"
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.12"]
+build-backend = "uv_build"

notifyvia_email-0.1.0/pyproject.toml.orig

@@ -0,0 +1,24 @@
+[project]
+name = "notifyvia-email"
+version = "0.1.0"
+description = "The frontend Python library for notifyvia.email"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "requests>=2.34.2",
+]
+
+[dependency-groups]
+dev = [
+    "pyqwe>=3.2.0",
+]
+
+[tool.pyqwe]
+sync = "*:uv run --env-file .index-notifyviaemail -- uv sync"
+build = "*:uv build"
+publish = "*:uv run --env-file .index-notifyviaemail -- uv publish --index uilix-forgejo"
+uv = "*>:uv run --env-file .index-notifyviaemail -- uv"
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.12"]
+build-backend = "uv_build"

notifyvia_email-0.1.0/src/notifyvia_email/_base.py

@@ -0,0 +1,112 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Literal
+
+import requests
+
+BASE_URL = "https://notifyvia.email/api"
+
+Service = Literal["zepto", "postmark"]
+
+
+class SendResult(Enum):
+    """Outcome of a send request, mapped from the API's HTTP status code."""
+
+    EMAIL_PROVISIONING = 200
+    RATE_LIMIT_EXCEEDED = 429
+    AUTHORIZATION_REQUIRED = 401
+    INVALID = 460
+    INVALID_ACCOUNT = 461
+    INVALID_SERVICE = 462
+    INSUFFICIENT_CREDITS = 463
+    IPV4_ADDRESS_NOT_PROVIDED = 464
+    SPAM_DETECTED = 465
+    SENDER_IPV4_BLOCKED = 466
+    UNKNOWN_ERROR = -1
+    CONNECTION_ERROR = -2
+
+    @property
+    def ok(self) -> bool:
+        return self is SendResult.EMAIL_PROVISIONING
+
+    @classmethod
+    def from_status_code(cls, status_code: int) -> "SendResult":
+        try:
+            return cls(status_code)
+        except ValueError:
+            return cls.UNKNOWN_ERROR
+
+
+@dataclass(frozen=True)
+class SendResponse:
+    """The result enum plus the API's ``errors`` field (e.g. per-field messages on INVALID)."""
+
+    result: SendResult
+    errors: Any = None
+
+    @property
+    def ok(self) -> bool:
+        return self.result.ok
+
+
+class BaseNotifyViaEmail:
+    version: str
+
+    def __init__(self, api_key: str, timeout: float = 10.0):
+        self.api_key = api_key
+        self.timeout = timeout
+
+    @property
+    def url(self) -> str:
+        return f"{BASE_URL}/{self.version}/send"
+
+    def _post(self, payload: dict[str, Any]) -> SendResponse:
+        try:
+            response = requests.post(
+                self.url,
+                json=payload,
+                headers={"X-Api-Key": self.api_key},
+                timeout=self.timeout,
+            )
+        except requests.RequestException as e:
+            return SendResponse(SendResult.CONNECTION_ERROR, errors=str(e))
+
+        try:
+            errors = response.json().get("errors")
+        except (ValueError, AttributeError):
+            errors = None
+
+        return SendResponse(SendResult.from_status_code(response.status_code), errors)
+
+    @staticmethod
+    def _build_payload(
+        to: str,
+        subject: str,
+        html: str | None,
+        text: str | None,
+        enable_spam_checker: bool,
+        enable_rate_limiter: bool,
+        limit: int,
+        within_seconds: int,
+        ipv4_address: str | None,
+        service: Service,
+    ) -> dict[str, Any]:
+        if html is None and text is None:
+            raise ValueError("Either html or text must be provided")
+
+        payload: dict[str, Any] = {
+            "to": to,
+            "subject": subject,
+            "enable_spam_checker": enable_spam_checker,
+            "enable_rate_limiter": enable_rate_limiter,
+            "limit": limit,
+            "within_seconds": within_seconds,
+            "service": service,
+        }
+        if html is not None:
+            payload["html"] = html
+        if text is not None:
+            payload["text"] = text
+        if ipv4_address is not None:
+            payload["ipv4_address"] = ipv4_address
+        return payload

notifyvia_email-0.1.0/src/notifyvia_email/v1/__init__.py

@@ -0,0 +1,36 @@
+from .._base import BaseNotifyViaEmail, SendResponse, SendResult, Service
+
+__all__ = ["NotifyViaEmail", "SendResponse", "SendResult"]
+
+
+class NotifyViaEmail(BaseNotifyViaEmail):
+    """Client for POST https://notifyvia.email/api/v1/send"""
+
+    version = "v1"
+
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html: str | None = None,
+        text: str | None = None,
+        enable_spam_checker: bool = False,
+        enable_rate_limiter: bool = False,
+        limit: int = 3,
+        within_seconds: int = 300,
+        ipv4_address: str | None = None,
+        service: Service = "zepto",
+    ) -> SendResponse:
+        payload = self._build_payload(
+            to=to,
+            subject=subject,
+            html=html,
+            text=text,
+            enable_spam_checker=enable_spam_checker,
+            enable_rate_limiter=enable_rate_limiter,
+            limit=limit,
+            within_seconds=within_seconds,
+            ipv4_address=ipv4_address,
+            service=service,
+        )
+        return self._post(payload)

notifyvia_email-0.1.0/src/notifyvia_email/v2/__init__.py

@@ -0,0 +1,39 @@
+from .._base import BaseNotifyViaEmail, SendResponse, SendResult, Service
+
+__all__ = ["NotifyViaEmail", "SendResponse", "SendResult"]
+
+
+class NotifyViaEmail(BaseNotifyViaEmail):
+    """Client for POST https://notifyvia.email/api/v2/send"""
+
+    version = "v2"
+
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html: str | None = None,
+        text: str | None = None,
+        reply_to: str | None = None,
+        enable_spam_checker: bool = False,
+        enable_rate_limiter: bool = False,
+        limit: int = 3,
+        within_seconds: int = 300,
+        ipv4_address: str | None = None,
+        service: Service = "zepto",
+    ) -> SendResponse:
+        payload = self._build_payload(
+            to=to,
+            subject=subject,
+            html=html,
+            text=text,
+            enable_spam_checker=enable_spam_checker,
+            enable_rate_limiter=enable_rate_limiter,
+            limit=limit,
+            within_seconds=within_seconds,
+            ipv4_address=ipv4_address,
+            service=service,
+        )
+        if reply_to is not None:
+            payload["reply_to"] = reply_to
+        return self._post(payload)