hawkapi-mail 0.1.0__tar.gz

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

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format check
+        run: uv run ruff format --check .
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: pyright
+        run: uv run pyright src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run tests
+        run: uv run pytest tests/ -q

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

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

hawkapi_mail-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+*.log
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+*.swp
+*.swo
+*~
+.DS_Store
+.idea/
+.vscode/
+.history/
+site/
+.remember/

hawkapi_mail-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 — 2026-05-16
+
+Initial release.
+
+- SMTP backend via aiosmtplib (TLS / STARTTLS / SSL).
+- AWS SES backend (raw send via boto3, extras: `[ses]`).
+- SendGrid v3, Mailgun v3, Resend HTTP backends.
+- In-memory backend for tests.
+- `EmailMessage` builder — text + HTML + attachments, to/cc/bcc/reply-to, tags, metadata.
+- Jinja2 `TemplateRenderer` with async rendering + HTML autoescape.
+- Persistent outbox (`MemoryOutbox`, `SQLiteOutbox`) with retry worker + exponential backoff.
+- Webhook helpers: signature verification (Mailgun, Resend/Svix, SendGrid ECDSA) and event parsing (Mailgun, SendGrid, Resend, SES via SNS) normalized to `WebhookEvent`.
+- `init_mail(app, ...)` + `Depends(get_mailer)`.

hawkapi_mail-0.1.0/LICENSE

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

hawkapi_mail-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: hawkapi-mail
+Version: 0.1.0
+Summary: Email plugin for HawkAPI — SMTP, SES, SendGrid, Mailgun, Resend, Jinja2, webhooks, persistent outbox
+Project-URL: Homepage, https://pypi.org/project/hawkapi-mail/
+Project-URL: Repository, https://github.com/ashimov/hawkapi-mail
+Project-URL: Issues, https://github.com/ashimov/hawkapi-mail/issues
+Author-email: HawkAPI Contributors <hawkapi@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 HawkAPI Contributors
+        
+        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.
+License-File: LICENSE
+Keywords: email,hawkapi,jinja2,mail,mailgun,resend,sendgrid,ses,smtp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiosmtplib>=3.0
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: hawkapi>=0.1.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: boto3>=1.34; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: ses
+Requires-Dist: boto3>=1.34; extra == 'ses'
+Description-Content-Type: text/markdown
+
+# hawkapi-mail
+
+Email plugin for [HawkAPI](https://github.com/ashimov/HawkAPI). SMTP, AWS SES, SendGrid, Mailgun, Resend, Jinja2 templates, persistent outbox with retry, and webhook handlers for delivery/bounce/complaint events.
+
+## Install
+
+```bash
+pip install hawkapi-mail            # SMTP + SendGrid + Mailgun + Resend + outbox
+pip install 'hawkapi-mail[ses]'     # adds AWS SES backend
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI
+from hawkapi_mail import (
+    EmailMessage,
+    Mailer,
+    SMTPBackend,
+    SMTPConfig,
+    get_mailer,
+    init_mail,
+)
+
+app = HawkAPI()
+init_mail(
+    app,
+    backend=SMTPBackend(SMTPConfig(host="smtp.example.com", port=587, start_tls=True,
+                                    username="api", password="secret")),
+    default_sender="hello@example.com",
+)
+
+
+@app.post("/welcome")
+async def welcome(email: str, mail: Mailer = Depends(get_mailer)):
+    msg = EmailMessage.build(
+        subject="Welcome!", to=email, text="Glad you joined.",
+        html="<h1>Glad you joined.</h1>",
+    )
+    await mail.send(msg)
+    return {"ok": True}
+```
+
+## Backends
+
+```python
+from hawkapi_mail import (
+    InMemoryBackend,                                # tests
+    SMTPBackend, SMTPConfig,                        # SMTP / SMTPS / STARTTLS
+    SESBackend, SESConfig,                          # AWS SES (extras: [ses])
+    SendGridBackend, SendGridConfig,                # SendGrid v3 API
+    MailgunBackend, MailgunConfig,                  # Mailgun v3 API
+    ResendBackend, ResendConfig,                    # Resend HTTP API
+)
+
+sendgrid = SendGridBackend(SendGridConfig(api_key="SG.xxx"))
+mailgun  = MailgunBackend(MailgunConfig(api_key="key-xxx", domain="mg.example.com"))
+resend   = ResendBackend(ResendConfig(api_key="re_xxx"))
+ses      = SESBackend(SESConfig(region="eu-west-1"))   # uses boto3 / IAM
+```
+
+All backends share one async `send(message) -> SendResult` interface; swap them freely.
+
+## Templates
+
+```python
+from hawkapi_mail import TemplateRenderer
+
+templates = TemplateRenderer(directory="emails/")           # or package=..., or templates={...}
+init_mail(app, backend=..., templates=templates, default_sender="hello@example.com")
+
+await mail.send_template(
+    "welcome.html",
+    text_template="welcome.txt",
+    context={"name": "Alice"},
+    subject="Welcome",
+    to="alice@example.com",
+)
+```
+
+Jinja2 with async rendering + HTML autoescape on by default.
+
+## Persistent outbox
+
+```python
+from hawkapi_mail import SQLiteOutbox, RetryPolicy
+
+outbox = SQLiteOutbox(path="mail.db")
+init_mail(
+    app,
+    backend=sendgrid,
+    outbox=outbox,
+    retry=RetryPolicy(max_attempts=5, base_seconds=5, max_seconds=3600),
+    start_worker=True,     # drains the outbox in the background
+)
+
+# Enqueue instead of sending right away:
+entry_id = await mail.send(message, deferred=True)
+```
+
+The worker pulls due entries, calls the backend, and on `SendError` schedules an exponential-backoff retry. After `max_attempts` the entry is dropped (logged at error level). For tests, swap in `MemoryOutbox()`.
+
+## Webhooks
+
+```python
+from hawkapi_mail import (
+    verify_sendgrid, parse_sendgrid,
+    verify_mailgun,  parse_mailgun,
+    verify_resend,   parse_resend,
+    parse_ses_sns,   confirm_ses_subscription,
+)
+
+
+@app.post("/webhooks/mailgun")
+async def mailgun_hook(request):
+    form = await request.form()
+    verify_mailgun(
+        signing_key="…",
+        timestamp=form["timestamp"], token=form["token"], signature=form["signature"],
+    )
+    event = parse_mailgun(await request.body())
+    # event.kind ∈ delivered | bounce | complaint | opened | clicked | unsubscribed | other
+    return {"ok": True}
+
+
+@app.post("/webhooks/ses")
+async def ses_hook(request):
+    body = await request.body()
+    if await confirm_ses_subscription(body):       # SNS SubscriptionConfirmation
+        return {"confirmed": True}
+    for event in parse_ses_sns(body):
+        ...
+    return {"ok": True}
+```
+
+All providers normalize to a single `WebhookEvent(provider, kind, recipient, message_id, timestamp, raw)`.
+
+## Testing
+
+```python
+from hawkapi_mail import InMemoryBackend, init_mail
+
+backend = InMemoryBackend()
+init_mail(app, backend=backend, default_sender="me@x.com")
+
+# After exercising the app:
+assert len(backend.sent) == 1
+assert backend.sent[0].subject == "Welcome"
+backend.clear()
+```
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-mail.git
+cd hawkapi-mail
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_mail-0.1.0/README.md

@@ -0,0 +1,165 @@
+# hawkapi-mail
+
+Email plugin for [HawkAPI](https://github.com/ashimov/HawkAPI). SMTP, AWS SES, SendGrid, Mailgun, Resend, Jinja2 templates, persistent outbox with retry, and webhook handlers for delivery/bounce/complaint events.
+
+## Install
+
+```bash
+pip install hawkapi-mail            # SMTP + SendGrid + Mailgun + Resend + outbox
+pip install 'hawkapi-mail[ses]'     # adds AWS SES backend
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI
+from hawkapi_mail import (
+    EmailMessage,
+    Mailer,
+    SMTPBackend,
+    SMTPConfig,
+    get_mailer,
+    init_mail,
+)
+
+app = HawkAPI()
+init_mail(
+    app,
+    backend=SMTPBackend(SMTPConfig(host="smtp.example.com", port=587, start_tls=True,
+                                    username="api", password="secret")),
+    default_sender="hello@example.com",
+)
+
+
+@app.post("/welcome")
+async def welcome(email: str, mail: Mailer = Depends(get_mailer)):
+    msg = EmailMessage.build(
+        subject="Welcome!", to=email, text="Glad you joined.",
+        html="<h1>Glad you joined.</h1>",
+    )
+    await mail.send(msg)
+    return {"ok": True}
+```
+
+## Backends
+
+```python
+from hawkapi_mail import (
+    InMemoryBackend,                                # tests
+    SMTPBackend, SMTPConfig,                        # SMTP / SMTPS / STARTTLS
+    SESBackend, SESConfig,                          # AWS SES (extras: [ses])
+    SendGridBackend, SendGridConfig,                # SendGrid v3 API
+    MailgunBackend, MailgunConfig,                  # Mailgun v3 API
+    ResendBackend, ResendConfig,                    # Resend HTTP API
+)
+
+sendgrid = SendGridBackend(SendGridConfig(api_key="SG.xxx"))
+mailgun  = MailgunBackend(MailgunConfig(api_key="key-xxx", domain="mg.example.com"))
+resend   = ResendBackend(ResendConfig(api_key="re_xxx"))
+ses      = SESBackend(SESConfig(region="eu-west-1"))   # uses boto3 / IAM
+```
+
+All backends share one async `send(message) -> SendResult` interface; swap them freely.
+
+## Templates
+
+```python
+from hawkapi_mail import TemplateRenderer
+
+templates = TemplateRenderer(directory="emails/")           # or package=..., or templates={...}
+init_mail(app, backend=..., templates=templates, default_sender="hello@example.com")
+
+await mail.send_template(
+    "welcome.html",
+    text_template="welcome.txt",
+    context={"name": "Alice"},
+    subject="Welcome",
+    to="alice@example.com",
+)
+```
+
+Jinja2 with async rendering + HTML autoescape on by default.
+
+## Persistent outbox
+
+```python
+from hawkapi_mail import SQLiteOutbox, RetryPolicy
+
+outbox = SQLiteOutbox(path="mail.db")
+init_mail(
+    app,
+    backend=sendgrid,
+    outbox=outbox,
+    retry=RetryPolicy(max_attempts=5, base_seconds=5, max_seconds=3600),
+    start_worker=True,     # drains the outbox in the background
+)
+
+# Enqueue instead of sending right away:
+entry_id = await mail.send(message, deferred=True)
+```
+
+The worker pulls due entries, calls the backend, and on `SendError` schedules an exponential-backoff retry. After `max_attempts` the entry is dropped (logged at error level). For tests, swap in `MemoryOutbox()`.
+
+## Webhooks
+
+```python
+from hawkapi_mail import (
+    verify_sendgrid, parse_sendgrid,
+    verify_mailgun,  parse_mailgun,
+    verify_resend,   parse_resend,
+    parse_ses_sns,   confirm_ses_subscription,
+)
+
+
+@app.post("/webhooks/mailgun")
+async def mailgun_hook(request):
+    form = await request.form()
+    verify_mailgun(
+        signing_key="…",
+        timestamp=form["timestamp"], token=form["token"], signature=form["signature"],
+    )
+    event = parse_mailgun(await request.body())
+    # event.kind ∈ delivered | bounce | complaint | opened | clicked | unsubscribed | other
+    return {"ok": True}
+
+
+@app.post("/webhooks/ses")
+async def ses_hook(request):
+    body = await request.body()
+    if await confirm_ses_subscription(body):       # SNS SubscriptionConfirmation
+        return {"confirmed": True}
+    for event in parse_ses_sns(body):
+        ...
+    return {"ok": True}
+```
+
+All providers normalize to a single `WebhookEvent(provider, kind, recipient, message_id, timestamp, raw)`.
+
+## Testing
+
+```python
+from hawkapi_mail import InMemoryBackend, init_mail
+
+backend = InMemoryBackend()
+init_mail(app, backend=backend, default_sender="me@x.com")
+
+# After exercising the app:
+assert len(backend.sent) == 1
+assert backend.sent[0].subject == "Welcome"
+backend.clear()
+```
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-mail.git
+cd hawkapi-mail
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_mail-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hawkapi-mail"
+version = "0.1.0"
+description = "Email plugin for HawkAPI — SMTP, SES, SendGrid, Mailgun, Resend, Jinja2, webhooks, persistent outbox"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [
+    { name = "HawkAPI Contributors", email = "hawkapi@users.noreply.github.com" },
+]
+keywords = ["hawkapi", "email", "mail", "smtp", "ses", "sendgrid", "mailgun", "resend", "jinja2"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = [
+    "hawkapi>=0.1.7",
+    "aiosmtplib>=3.0",
+    "httpx>=0.27",
+    "jinja2>=3.1",
+    "aiosqlite>=0.20",
+]
+
+[project.optional-dependencies]
+ses = ["boto3>=1.34"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "boto3>=1.34",
+    "ruff>=0.8",
+    "pyright>=1.1",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/hawkapi-mail/"
+Repository = "https://github.com/ashimov/hawkapi-mail"
+Issues = "https://github.com/ashimov/hawkapi-mail/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hawkapi_mail"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "S"]
+ignore = ["S101", "B008"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportMissingTypeStubs = false