smtpfast 0.1.0__tar.gz

smtpfast-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e '.[dev]'
+      # The generated code must be exactly what the spec in the repo produces.
+      - name: Generated code is up to date
+        run: python scripts/generate.py && git diff --exit-code
+      - run: ruff check src tests scripts
+      - run: mypy
+      - run: pytest -q
+
+  # Read-only calls to the real API, checked against the spec. Needs a key
+  # with email:read and domain:read in the SMTPFAST_API_KEY secret.
+  live:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install -e '.[dev]'
+      - run: pytest -q tests/test_live.py
+        env:
+          SMTPFAST_API_KEY: ${{ secrets.SMTPFAST_API_KEY }}

smtpfast-0.1.0/.github/workflows/regenerate.yml

@@ -0,0 +1,50 @@
+name: Regenerate from the API spec
+
+# Pulls the published OpenAPI document, regenerates the SDK and opens a pull
+# request when anything changed. Runs daily, on demand, and when the API repo
+# sends a spec-changed dispatch.
+on:
+  schedule:
+    - cron: "23 5 * * *"
+  workflow_dispatch:
+  repository_dispatch:
+    types: [spec-changed]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install -e '.[dev]'
+      - run: python scripts/pull_spec.py
+      # Until the API publishes x-sdk-group/x-sdk-method, there is nothing to regenerate from.
+      - name: Spec has SDK names
+        id: names
+        run: |
+          if grep -q '"x-sdk-method"' spec/openapi.json; then echo "ok=true" >> "$GITHUB_OUTPUT"; else echo "::notice::The published spec has no x-sdk names yet; skipping."; echo "ok=false" >> "$GITHUB_OUTPUT"; fi
+      - run: python scripts/generate.py
+        if: steps.names.outputs.ok == 'true'
+      - run: mypy
+        if: steps.names.outputs.ok == 'true'
+      - run: pytest -q
+        if: steps.names.outputs.ok == 'true'
+      # A pull request opened with the default GITHUB_TOKEN does not start the
+      # CI workflow. Set SDK_BOT_TOKEN (a GitHub App or fine-grained token with
+      # contents and pull-requests write) so it does.
+      - uses: peter-evans/create-pull-request@v7
+        if: steps.names.outputs.ok == 'true'
+        with:
+          token: ${{ secrets.SDK_BOT_TOKEN || github.token }}
+          branch: spec-sync
+          title: "Sync with the API spec"
+          commit-message: "Sync with the API spec"
+          body: |
+            The published OpenAPI document changed. This regenerates `src/smtpfast/types.py` and `src/smtpfast/_resources.py` from it.
+            Review the diff of `spec/openapi.json` for what changed in the API.

smtpfast-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+# Publish to PyPI when a GitHub release is published, with PyPI trusted
+# publishing (no token). The tag is the version, for example v0.2.0; it must
+# match pyproject.toml.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Tag matches pyproject.toml
+        run: test "v$(python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')" = "${GITHUB_REF_NAME}"
+      - run: pip install -e '.[dev]' build
+      - run: pytest -q
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

smtpfast-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env

smtpfast-0.1.0/LICENSE

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

smtpfast-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: smtpfast
+Version: 0.1.0
+Summary: The official Python SDK for the SMTPfast API.
+Project-URL: Homepage, https://smtpfa.st
+Project-URL: Documentation, https://smtpfa.st/docs
+Project-URL: Source, https://github.com/smtpfast/smtpfast-python
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,email,sdk,smtpfast,transactional-email
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.22; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SMTPfast Python SDK
+
+The official Python SDK for the [SMTPfast](https://smtpfa.st) API. It covers every endpoint in the API, sync and async, with types for every request and response. It needs Python 3.10+ and depends only on `httpx`.
+
+```bash
+pip install smtpfast
+```
+
+## Send an email
+
+```python
+from smtpfast import SMTPfast
+
+client = SMTPfast()  # reads SMTPFAST_API_KEY
+
+email = client.emails.send({
+    "from": "Acme <hello@yourdomain.com>",
+    "to": ["customer@example.org"],
+    "subject": "Your receipt",
+    "html": "<p>Thanks for your order.</p>",
+    "category": "transactional",
+})
+print(email["id"])
+```
+
+Email is marketing unless you set `category` to `transactional`. Marketing email gets a one-click unsubscribe header and is not sent to people who unsubscribed. Set `transactional` on receipts, password resets and account alerts so a marketing opt-out does not block them.
+
+Requests and responses are plain dicts, typed with `TypedDict`s from `smtpfast.types`, so your editor and type checker know every field. A new field or value from the API never breaks your code, because the SDK does not validate responses at runtime.
+
+Every API operation is a method, named after its path: `client.domains.verify(id)`, `client.contacts.segments.add(contact_id, segment_id)`, `client.inboxes.threads.emails.reply(inbox_id, thread_id, email_id, params)`. Path parameters come first, then the request body, and query parameters are keyword arguments: `client.emails.list(limit=20, status="bounced")`.
+
+## Async
+
+```python
+from smtpfast import AsyncSMTPfast
+
+async with AsyncSMTPfast() as client:
+    await client.emails.send({...})
+```
+
+## Options
+
+```python
+client = SMTPfast(
+    api_key="sf_...",            # default: SMTPFAST_API_KEY
+    base_url="https://smtpfa.st/api",
+    max_retries=2,                # after 429 (with Retry-After), 408, 5xx and dropped connections
+    timeout=60.0,                 # per attempt, in seconds
+)
+
+client.emails.send(params, idempotency_key="order-1234", options={"timeout": 10})
+```
+
+## Retries and idempotency
+
+Reads, `PUT` and `DELETE` are retried after a 5xx answer or a dropped connection. A send, reply or forward is retried with the same `Idempotency-Key`, so the API returns the first answer instead of sending twice. When you do not give a key, the SDK makes one per call. Other `POST` and `PATCH` calls are retried only after a per-second rate limit, which the API rejects before doing any work.
+
+## Errors
+
+Every error is an `SMTPfastError`. An answer outside 2xx raises an `APIError` with `status`, `body` and `headers`, as one of `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`, `RateLimitError` or `InternalServerError`. No answer at all raises `APIConnectionError` or `APITimeoutError`.
+
+```python
+import smtpfast
+
+try:
+    client.emails.get("em_missing")
+except smtpfast.NotFoundError as err:
+    print(err.status, err.body)
+```
+
+## Pagination
+
+Lists that page with a cursor also have a `..._all` method that fetches the next pages as you iterate:
+
+```python
+for email in client.emails.list_all(limit=100):
+    print(email["id"], email["status"])
+```
+
+## Webhooks
+
+```python
+from smtpfast import webhooks
+
+# The raw body, before any JSON parsing.
+event = webhooks.parse(request.body, request.headers, secret=os.environ["SMTPFAST_WEBHOOK_SECRET"])
+if event["type"] == "email.bounced":
+    ...
+```
+
+`webhooks.verify_signature(payload, signature, secret)` returns a bool if you only need the check.
+
+## How this SDK is made
+
+The SDK is generated from the [OpenAPI document](https://smtpfa.st/api/v1/openapi.json), so it follows the API without hand edits. `scripts/generate.py` (standard library only) writes `src/smtpfast/types.py` and `src/smtpfast/_resources.py`, naming every method from the `x-sdk-group` and `x-sdk-method` the spec gives each operation; the SDKs for other languages use the same names. `_core.py`, `_errors.py` and `webhooks.py` are written by hand.
+
+```bash
+python scripts/pull_spec.py   # download the published spec into spec/openapi.json
+python scripts/generate.py    # regenerate types.py and _resources.py
+pytest -q                     # unit tests, including one call per operation
+SMTPFAST_API_KEY=sf_... pytest tests/test_live.py   # read-only calls, checked against the spec
+```
+
+A daily workflow pulls the spec and opens a pull request when it changed.
+
+## License
+
+MIT

smtpfast-0.1.0/README.md

@@ -0,0 +1,108 @@
+# SMTPfast Python SDK
+
+The official Python SDK for the [SMTPfast](https://smtpfa.st) API. It covers every endpoint in the API, sync and async, with types for every request and response. It needs Python 3.10+ and depends only on `httpx`.
+
+```bash
+pip install smtpfast
+```
+
+## Send an email
+
+```python
+from smtpfast import SMTPfast
+
+client = SMTPfast()  # reads SMTPFAST_API_KEY
+
+email = client.emails.send({
+    "from": "Acme <hello@yourdomain.com>",
+    "to": ["customer@example.org"],
+    "subject": "Your receipt",
+    "html": "<p>Thanks for your order.</p>",
+    "category": "transactional",
+})
+print(email["id"])
+```
+
+Email is marketing unless you set `category` to `transactional`. Marketing email gets a one-click unsubscribe header and is not sent to people who unsubscribed. Set `transactional` on receipts, password resets and account alerts so a marketing opt-out does not block them.
+
+Requests and responses are plain dicts, typed with `TypedDict`s from `smtpfast.types`, so your editor and type checker know every field. A new field or value from the API never breaks your code, because the SDK does not validate responses at runtime.
+
+Every API operation is a method, named after its path: `client.domains.verify(id)`, `client.contacts.segments.add(contact_id, segment_id)`, `client.inboxes.threads.emails.reply(inbox_id, thread_id, email_id, params)`. Path parameters come first, then the request body, and query parameters are keyword arguments: `client.emails.list(limit=20, status="bounced")`.
+
+## Async
+
+```python
+from smtpfast import AsyncSMTPfast
+
+async with AsyncSMTPfast() as client:
+    await client.emails.send({...})
+```
+
+## Options
+
+```python
+client = SMTPfast(
+    api_key="sf_...",            # default: SMTPFAST_API_KEY
+    base_url="https://smtpfa.st/api",
+    max_retries=2,                # after 429 (with Retry-After), 408, 5xx and dropped connections
+    timeout=60.0,                 # per attempt, in seconds
+)
+
+client.emails.send(params, idempotency_key="order-1234", options={"timeout": 10})
+```
+
+## Retries and idempotency
+
+Reads, `PUT` and `DELETE` are retried after a 5xx answer or a dropped connection. A send, reply or forward is retried with the same `Idempotency-Key`, so the API returns the first answer instead of sending twice. When you do not give a key, the SDK makes one per call. Other `POST` and `PATCH` calls are retried only after a per-second rate limit, which the API rejects before doing any work.
+
+## Errors
+
+Every error is an `SMTPfastError`. An answer outside 2xx raises an `APIError` with `status`, `body` and `headers`, as one of `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`, `RateLimitError` or `InternalServerError`. No answer at all raises `APIConnectionError` or `APITimeoutError`.
+
+```python
+import smtpfast
+
+try:
+    client.emails.get("em_missing")
+except smtpfast.NotFoundError as err:
+    print(err.status, err.body)
+```
+
+## Pagination
+
+Lists that page with a cursor also have a `..._all` method that fetches the next pages as you iterate:
+
+```python
+for email in client.emails.list_all(limit=100):
+    print(email["id"], email["status"])
+```
+
+## Webhooks
+
+```python
+from smtpfast import webhooks
+
+# The raw body, before any JSON parsing.
+event = webhooks.parse(request.body, request.headers, secret=os.environ["SMTPFAST_WEBHOOK_SECRET"])
+if event["type"] == "email.bounced":
+    ...
+```
+
+`webhooks.verify_signature(payload, signature, secret)` returns a bool if you only need the check.
+
+## How this SDK is made
+
+The SDK is generated from the [OpenAPI document](https://smtpfa.st/api/v1/openapi.json), so it follows the API without hand edits. `scripts/generate.py` (standard library only) writes `src/smtpfast/types.py` and `src/smtpfast/_resources.py`, naming every method from the `x-sdk-group` and `x-sdk-method` the spec gives each operation; the SDKs for other languages use the same names. `_core.py`, `_errors.py` and `webhooks.py` are written by hand.
+
+```bash
+python scripts/pull_spec.py   # download the published spec into spec/openapi.json
+python scripts/generate.py    # regenerate types.py and _resources.py
+pytest -q                     # unit tests, including one call per operation
+SMTPFAST_API_KEY=sf_... pytest tests/test_live.py   # read-only calls, checked against the spec
+```
+
+A daily workflow pulls the spec and opens a pull request when it changed.
+
+## License
+
+MIT

smtpfast-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "smtpfast"
+version = "0.1.0"
+description = "The official Python SDK for the SMTPfast API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1", "typing_extensions>=4.7"]
+keywords = ["smtpfast", "email", "transactional-email", "api", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Topic :: Communications :: Email",
+]
+
+[project.urls]
+Homepage = "https://smtpfa.st"
+Documentation = "https://smtpfa.st/docs"
+Source = "https://github.com/smtpfast/smtpfast-python"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.10", "jsonschema>=4.22", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/smtpfast"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+files = ["src/smtpfast"]
+
+[[tool.mypy.overrides]]
+module = ["smtpfast._resources", "smtpfast._core"]
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+disallow_incomplete_defs = false

smtpfast-0.1.0/ruff.toml

@@ -0,0 +1,5 @@
+line-length = 140
+extend-exclude = ["src/smtpfast/types.py", "src/smtpfast/_resources.py"]
+
+[lint.per-file-ignores]
+"tests/*" = ["E731"]