sendkit 1.0.0__tar.gz

sendkit-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,62 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+    tags: ['[0-9]*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13']
+
+    name: Python ${{ matrix.python }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install package and test dependencies
+        run: pip install -e . && pip install pytest
+
+      - name: Run tests
+        run: python -m pytest -v
+
+  release:
+    needs: tests
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        run: gh release create ${{ github.ref_name }} --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sendkit-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

sendkit-1.0.0/CLAUDE.md

@@ -0,0 +1,38 @@
+# SendKit Python SDK
+
+## Project Overview
+
+Python SDK for the SendKit email API. Uses `urllib` (stdlib), zero external dependencies.
+
+## Architecture
+
+```
+src/sendkit/
+├── __init__.py    # Public exports (SendKit, SendKitError)
+├── client.py      # SendKit client: holds API key, _post() method
+├── emails.py      # Emails service (send, send_mime)
+└── errors.py      # SendKitError exception class
+```
+
+- `SendKit` class is the entry point, accepts api_key + optional base_url
+- `client.emails` exposes email operations
+- Uses keyword-only arguments for send() params
+- `from_` parameter (trailing underscore) avoids Python reserved word conflict
+- API errors raise `SendKitError` with name, message, status_code
+- `POST /v1/emails` for structured emails, `POST /v1/emails/mime` for raw MIME
+
+## Testing
+
+- Tests use `unittest` + `http.server` for mock HTTP servers
+- Run tests: `python -m pytest`
+- No external test dependencies beyond pytest
+
+## Releasing
+
+- Tags use numeric format: `1.0.0` (no `v` prefix)
+- CI runs tests on Python 3.10, 3.11, 3.12, 3.13
+- Pushing a tag creates GitHub Release + publishes to PyPI via trusted publishing
+
+## Git
+
+- NEVER add `Co-Authored-By` lines to commit messages

sendkit-1.0.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: sendkit
+Version: 1.0.0
+Summary: Python SDK for the SendKit email API
+Project-URL: Homepage, https://sendkit.com
+Project-URL: Repository, https://github.com/sendkitdev/sendkit-python
+Project-URL: Issues, https://github.com/sendkitdev/sendkit-python/issues
+License-Expression: MIT
+Keywords: api,email,sdk,sendkit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SendKit Python SDK
+
+Official Python SDK for the [SendKit](https://sendkit.com) email API.
+
+## Installation
+
+```bash
+pip install sendkit
+```
+
+## Usage
+
+### Create a Client
+
+```python
+from sendkit import SendKit
+
+client = SendKit("sk_your_api_key")
+```
+
+### Send an Email
+
+```python
+result = client.emails.send(
+    from_="you@example.com",
+    to="recipient@example.com",
+    subject="Hello from SendKit",
+    html="<h1>Welcome!</h1>",
+)
+
+print(result["id"])
+```
+
+### Send a MIME Email
+
+```python
+result = client.emails.send_mime(
+    envelope_from="you@example.com",
+    envelope_to="recipient@example.com",
+    raw_message=mime_string,
+)
+```
+
+### Error Handling
+
+API errors raise `SendKitError`:
+
+```python
+from sendkit import SendKit, SendKitError
+
+client = SendKit("sk_your_api_key")
+
+try:
+    client.emails.send(...)
+except SendKitError as e:
+    print(e.name)        # e.g. "validation_error"
+    print(e.message)     # e.g. "The to field is required."
+    print(e.status_code) # e.g. 422
+```
+
+### Configuration
+
+```python
+# Read API key from SENDKIT_API_KEY environment variable
+client = SendKit()
+
+# Custom base URL
+client = SendKit("sk_...", base_url="https://custom.api.com")
+```

sendkit-1.0.0/README.md

@@ -0,0 +1,69 @@
+# SendKit Python SDK
+
+Official Python SDK for the [SendKit](https://sendkit.com) email API.
+
+## Installation
+
+```bash
+pip install sendkit
+```
+
+## Usage
+
+### Create a Client
+
+```python
+from sendkit import SendKit
+
+client = SendKit("sk_your_api_key")
+```
+
+### Send an Email
+
+```python
+result = client.emails.send(
+    from_="you@example.com",
+    to="recipient@example.com",
+    subject="Hello from SendKit",
+    html="<h1>Welcome!</h1>",
+)
+
+print(result["id"])
+```
+
+### Send a MIME Email
+
+```python
+result = client.emails.send_mime(
+    envelope_from="you@example.com",
+    envelope_to="recipient@example.com",
+    raw_message=mime_string,
+)
+```
+
+### Error Handling
+
+API errors raise `SendKitError`:
+
+```python
+from sendkit import SendKit, SendKitError
+
+client = SendKit("sk_your_api_key")
+
+try:
+    client.emails.send(...)
+except SendKitError as e:
+    print(e.name)        # e.g. "validation_error"
+    print(e.message)     # e.g. "The to field is required."
+    print(e.status_code) # e.g. 422
+```
+
+### Configuration
+
+```python
+# Read API key from SENDKIT_API_KEY environment variable
+client = SendKit()
+
+# Custom base URL
+client = SendKit("sk_...", base_url="https://custom.api.com")
+```

sendkit-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sendkit"
+version = "1.0.0"
+description = "Python SDK for the SendKit email API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["sendkit", "email", "api", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://sendkit.com"
+Repository = "https://github.com/sendkitdev/sendkit-python"
+Issues = "https://github.com/sendkitdev/sendkit-python/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sendkit-1.0.0/src/sendkit/__init__.py

@@ -0,0 +1,4 @@
+from .client import SendKit
+from .errors import SendKitError
+
+__all__ = ["SendKit", "SendKitError"]

sendkit-1.0.0/src/sendkit/client.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+from .emails import Emails
+from .errors import SendKitError
+
+_DEFAULT_BASE_URL = "https://api.sendkit.com"
+
+
+class SendKit:
+    """SendKit API client.
+
+    Args:
+        api_key: Your SendKit API key. If not provided, reads from
+            the ``SENDKIT_API_KEY`` environment variable.
+        base_url: Override the API base URL.
+    """
+
+    def __init__(self, api_key: str | None = None, *, base_url: str = _DEFAULT_BASE_URL) -> None:
+        self.api_key = api_key or os.environ.get("SENDKIT_API_KEY", "")
+
+        if not self.api_key:
+            raise ValueError(
+                'Missing API key. Pass it to the constructor `SendKit("sk_...")` '
+                "or set the SENDKIT_API_KEY environment variable."
+            )
+
+        self.base_url = base_url
+        self.emails = Emails(self)
+
+    def _post(self, path: str, body: dict[str, Any]) -> Any:
+        data = json.dumps(body).encode()
+        req = Request(
+            f"{self.base_url}{path}",
+            data=data,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+        try:
+            with urlopen(req) as resp:
+                return json.loads(resp.read())
+        except HTTPError as exc:
+            try:
+                error_body = json.loads(exc.read())
+                raise SendKitError(
+                    message=error_body.get("message", exc.reason),
+                    status_code=exc.code,
+                    name=error_body.get("name", "application_error"),
+                ) from None
+            except (json.JSONDecodeError, AttributeError):
+                raise SendKitError(
+                    message=str(exc.reason),
+                    status_code=exc.code,
+                ) from None

sendkit-1.0.0/src/sendkit/emails.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .client import SendKit
+
+
+class Emails:
+    """Handles communication with the email related methods of the SendKit API."""
+
+    def __init__(self, client: SendKit) -> None:
+        self._client = client
+
+    def send(
+        self,
+        *,
+        from_: str,
+        to: str | list[str],
+        subject: str,
+        html: str | None = None,
+        text: str | None = None,
+        cc: str | list[str] | None = None,
+        bcc: str | list[str] | None = None,
+        reply_to: str | None = None,
+        headers: dict[str, str] | None = None,
+        tags: list[str] | None = None,
+        scheduled_at: str | None = None,
+        attachments: list[dict[str, Any]] | None = None,
+    ) -> dict[str, str]:
+        """Send a structured email.
+
+        Returns a dict with the email ``id``.
+        """
+        payload: dict[str, Any] = {
+            "from": from_,
+            "to": to,
+            "subject": subject,
+        }
+
+        if html is not None:
+            payload["html"] = html
+        if text is not None:
+            payload["text"] = text
+        if cc is not None:
+            payload["cc"] = cc
+        if bcc is not None:
+            payload["bcc"] = bcc
+        if reply_to is not None:
+            payload["reply_to"] = reply_to
+        if headers is not None:
+            payload["headers"] = headers
+        if tags is not None:
+            payload["tags"] = tags
+        if scheduled_at is not None:
+            payload["scheduled_at"] = scheduled_at
+        if attachments is not None:
+            payload["attachments"] = attachments
+
+        return self._client._post("/v1/emails", payload)
+
+    def send_mime(
+        self,
+        *,
+        envelope_from: str,
+        envelope_to: str,
+        raw_message: str,
+    ) -> dict[str, str]:
+        """Send a raw MIME email.
+
+        Returns a dict with the email ``id``.
+        """
+        return self._client._post("/v1/emails/mime", {
+            "envelope_from": envelope_from,
+            "envelope_to": envelope_to,
+            "raw_message": raw_message,
+        })

sendkit-1.0.0/src/sendkit/errors.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+
+class SendKitError(Exception):
+    """Represents an error response from the SendKit API."""
+
+    def __init__(self, message: str, status_code: int | None = None, name: str = "application_error") -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"SendKitError(name={self.name!r}, status_code={self.status_code}, message={self.message!r})"

sendkit-1.0.0/tests/test_sendkit.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import json
+import os
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from threading import Thread
+from typing import Any
+from unittest import TestCase
+
+from sendkit import SendKit, SendKitError
+
+
+def _make_server(handler_class: type[BaseHTTPRequestHandler]) -> tuple[HTTPServer, str]:
+    server = HTTPServer(("127.0.0.1", 0), handler_class)
+    port = server.server_address[1]
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    return server, f"http://127.0.0.1:{port}"
+
+
+class TestNewClient(TestCase):
+    def test_with_api_key(self) -> None:
+        client = SendKit("sk_test_123")
+        self.assertEqual(client.api_key, "sk_test_123")
+
+    def test_missing_api_key(self) -> None:
+        os.environ.pop("SENDKIT_API_KEY", None)
+        with self.assertRaises(ValueError):
+            SendKit()
+
+    def test_from_env_variable(self) -> None:
+        os.environ["SENDKIT_API_KEY"] = "sk_from_env"
+        try:
+            client = SendKit()
+            self.assertEqual(client.api_key, "sk_from_env")
+        finally:
+            del os.environ["SENDKIT_API_KEY"]
+
+    def test_custom_base_url(self) -> None:
+        client = SendKit("sk_test_123", base_url="https://custom.api.com")
+        self.assertEqual(client.base_url, "https://custom.api.com")
+
+
+class TestEmailsSend(TestCase):
+    def test_send_email(self) -> None:
+        captured: dict[str, Any] = {}
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self) -> None:
+                captured["path"] = self.path
+                captured["method"] = self.command
+                captured["auth"] = self.headers.get("Authorization")
+                length = int(self.headers.get("Content-Length", 0))
+                captured["body"] = json.loads(self.rfile.read(length))
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(json.dumps({"id": "email-uuid-123"}).encode())
+
+            def log_message(self, *args: Any) -> None:
+                pass
+
+        server, url = _make_server(Handler)
+        try:
+            client = SendKit("sk_test_123", base_url=url)
+            result = client.emails.send(
+                from_="sender@example.com",
+                to="recipient@example.com",
+                subject="Test Email",
+                html="<p>Hello</p>",
+            )
+
+            self.assertEqual(result["id"], "email-uuid-123")
+            self.assertEqual(captured["path"], "/v1/emails")
+            self.assertEqual(captured["method"], "POST")
+            self.assertEqual(captured["auth"], "Bearer sk_test_123")
+            self.assertEqual(captured["body"]["from"], "sender@example.com")
+            self.assertEqual(captured["body"]["to"], "recipient@example.com")
+            self.assertEqual(captured["body"]["subject"], "Test Email")
+        finally:
+            server.shutdown()
+
+    def test_send_with_optional_fields(self) -> None:
+        captured: dict[str, Any] = {}
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self) -> None:
+                length = int(self.headers.get("Content-Length", 0))
+                captured["body"] = json.loads(self.rfile.read(length))
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(json.dumps({"id": "email-uuid-456"}).encode())
+
+            def log_message(self, *args: Any) -> None:
+                pass
+
+        server, url = _make_server(Handler)
+        try:
+            client = SendKit("sk_test_123", base_url=url)
+            client.emails.send(
+                from_="sender@example.com",
+                to="recipient@example.com",
+                subject="Test",
+                html="<p>Hi</p>",
+                reply_to="reply@example.com",
+                scheduled_at="2026-03-01T10:00:00Z",
+            )
+
+            self.assertEqual(captured["body"]["reply_to"], "reply@example.com")
+            self.assertEqual(captured["body"]["scheduled_at"], "2026-03-01T10:00:00Z")
+        finally:
+            server.shutdown()
+
+    def test_send_mime_email(self) -> None:
+        captured: dict[str, Any] = {}
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self) -> None:
+                captured["path"] = self.path
+                length = int(self.headers.get("Content-Length", 0))
+                captured["body"] = json.loads(self.rfile.read(length))
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(json.dumps({"id": "mime-uuid-789"}).encode())
+
+            def log_message(self, *args: Any) -> None:
+                pass
+
+        server, url = _make_server(Handler)
+        try:
+            client = SendKit("sk_test_123", base_url=url)
+            result = client.emails.send_mime(
+                envelope_from="sender@example.com",
+                envelope_to="recipient@example.com",
+                raw_message="From: sender@example.com\r\nTo: recipient@example.com\r\n\r\nHello",
+            )
+
+            self.assertEqual(result["id"], "mime-uuid-789")
+            self.assertEqual(captured["path"], "/v1/emails/mime")
+            self.assertEqual(captured["body"]["envelope_from"], "sender@example.com")
+            self.assertEqual(captured["body"]["envelope_to"], "recipient@example.com")
+        finally:
+            server.shutdown()
+
+    def test_api_error(self) -> None:
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self) -> None:
+                self.send_response(422)
+                self.end_headers()
+                self.wfile.write(json.dumps({
+                    "name": "validation_error",
+                    "message": "The to field is required.",
+                    "statusCode": 422,
+                }).encode())
+
+            def log_message(self, *args: Any) -> None:
+                pass
+
+        server, url = _make_server(Handler)
+        try:
+            client = SendKit("sk_test_123", base_url=url)
+            with self.assertRaises(SendKitError) as ctx:
+                client.emails.send(
+                    from_="sender@example.com",
+                    to="",
+                    subject="Test",
+                    html="<p>Hi</p>",
+                )
+
+            err = ctx.exception
+            self.assertEqual(err.name, "validation_error")
+            self.assertEqual(err.status_code, 422)
+            self.assertEqual(err.message, "The to field is required.")
+        finally:
+            server.shutdown()