mailengin 0.1.0__tar.gz

mailengin-0.1.0/.gitignore

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

mailengin-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this package will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+### Added
+
+- Initial Python SDK with synchronous and asynchronous clients.
+- Typed single and personalized bulk email operations.
+- Template, raw HTML, variables, sender override, and reply-routing support.
+- Structured API, timeout, malformed-response, and network errors.
+- HTTPX transport injection, tests, CI, and trusted PyPI publishing.
+
+### Fixed
+
+- Make release tag validation safe for Bash quoting on GitHub Actions.
+
+### Fixed
+
+- Make release tag validation safe for Bash quoting on GitHub Actions.

mailengin-0.1.0/LICENSE

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

mailengin-0.1.0/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.5
+Name: mailengin
+Version: 0.1.0
+Summary: Official Python SDK for the MailEngin Email API
+Project-URL: Homepage, https://mailengin.app
+Project-URL: Repository, https://github.com/mailengin/mailengin-python-sdk
+Project-URL: Issues, https://github.com/mailengin/mailengin-python-sdk/issues
+Project-URL: Documentation, https://mailengin.app/dashboard/docs
+Author: MailEngin
+License: MIT License
+        
+        Copyright (c) 2026 MailEngin
+        
+        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,email-api,mailengin,transactional-email
+Classifier: Development Status :: 3 - Alpha
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.6
+Description-Content-Type: text/markdown
+
+# MailEngin Python SDK
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776ab.svg)](https://www.python.org/)
+[![Typing](https://img.shields.io/badge/typing-strict-2563eb.svg)](https://mypy.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-111827.svg)](./LICENSE)
+
+The official Python SDK for sending transactional email through [MailEngin](https://mailengin.app). It provides synchronous and asynchronous clients, typed dataclass models, configurable timeouts, and structured errors.
+
+> [!IMPORTANT]
+> This package is for server-side applications only. Never expose a MailEngin API key in browser, mobile, desktop, or other client-distributed code.
+
+## Requirements
+
+- Python 3.10 or newer
+- A MailEngin API key
+- A verified sending domain
+
+## Installation
+
+```bash
+python -m pip install mailengin
+```
+
+For a specific version:
+
+```bash
+python -m pip install "mailengin==0.1.0"
+```
+
+## Before You Send
+
+1. [Verify a sending domain](https://mailengin.app/dashboard/domains).
+2. [Create an API key](https://mailengin.app/dashboard/api-keys) and save the full secret.
+3. [Create and publish a Developer Template](https://mailengin.app/dashboard/dev-templates).
+4. Copy the template API name, such as `welcome-email`.
+
+Store the API key in a server-side environment variable:
+
+```env
+MAILENGIN_API_KEY=re_your_full_secret_key
+```
+
+MailEngin displays the full key only once. A masked key cannot authenticate requests.
+
+## Quick Start
+
+```python
+import os
+
+from mailengin import MailEngin, SendEmailRequest
+
+with MailEngin(os.environ["MAILENGIN_API_KEY"]) as client:
+    email = client.emails.send(
+        SendEmailRequest(
+            to="user@example.com",
+            from_email="hello@yourdomain.com",
+            template_name="welcome-email",
+            variables={"first_name": "Asha"},
+        )
+    )
+
+print(email.id)
+```
+
+The published template supplies the subject and HTML. Values in `variables` replace matching template variables such as `{{first_name}}`.
+
+## Async Client
+
+`AsyncMailEngin` exposes the same email methods as coroutines and uses `httpx.AsyncClient` internally:
+
+```python
+import asyncio
+import os
+
+from mailengin import AsyncMailEngin, SendEmailRequest
+
+
+async def main() -> None:
+    async with AsyncMailEngin(os.environ["MAILENGIN_API_KEY"]) as client:
+        email = await client.emails.send(
+            SendEmailRequest(
+                to="user@example.com",
+                template_name="welcome-email",
+                variables={"first_name": "Asha"},
+            )
+        )
+        print(email.id)
+
+
+asyncio.run(main())
+```
+
+Cancel the surrounding asyncio task to cancel an in-flight asynchronous request.
+
+## Send One Email
+
+```python
+request = SendEmailRequest(
+    to="customer@example.com",
+    from_email="hello@yourdomain.com",
+    template_name="account-verification",
+    variables={
+        "first_name": "Asha",
+        "verification_url": "https://yourapp.com/verify/token",
+    },
+    reply_to_mailengin=True,
+)
+
+email = client.emails.send(request)
+print(email.id, email.from_email, email.created_at)
+```
+
+### Send request fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `to` | `str` | Yes | Recipient email address. |
+| `template_name` | `str` | Recommended | Published template API name or exact display name. |
+| `template_id` | `str` | No | Legacy template identifier. Prefer `template_name`. |
+| `variables` | `dict[str, Any]` | No | Values used to render template variables. |
+| `subject` | `str` | Raw HTML only | Template subject override, or required subject for raw HTML. |
+| `from_email` | `str` | Recommended | Sender on a verified domain authorized for the API key. |
+| `html` | `str` | Advanced | Raw HTML used when no template is supplied. |
+| `reply_to_mailengin` | `bool` | No | Route recipient replies into the MailEngin inbox. |
+
+Exactly one content source is required: `template_name`, `template_id`, or `html`. Raw HTML sends also require `subject`.
+
+## Send Personalized Bulk Email
+
+Bulk requests support up to 1,000 recipients. Request-level variables apply to every recipient; recipient variables take precedence.
+
+```python
+from mailengin import BulkRecipient, SendBulkEmailRequest
+
+job = client.emails.send_bulk(
+    SendBulkEmailRequest(
+        to=[
+            BulkRecipient(
+                email="asha@example.com",
+                variables={"first_name": "Asha"},
+            ),
+            BulkRecipient(
+                email="ben@example.com",
+                variables={"first_name": "Ben"},
+            ),
+        ],
+        from_email="hello@yourdomain.com",
+        template_name="product-update",
+        variables={"product_name": "MailEngin"},
+    )
+)
+
+print(job.job_id, job.queued_count)
+```
+
+For the same content without recipient-specific variables, use strings:
+
+```python
+job = client.emails.send_bulk(
+    SendBulkEmailRequest(
+        to=["a@example.com", "b@example.com"],
+        template_name="maintenance-notice",
+    )
+)
+```
+
+A successful bulk response confirms that recipients were queued. It is not a guarantee that every message was delivered.
+
+## Send Raw HTML
+
+Published templates are recommended for reusable product email. For a one-off message, provide both `subject` and `html`:
+
+```python
+email = client.emails.send(
+    SendEmailRequest(
+        to="user@example.com",
+        from_email="reports@yourdomain.com",
+        subject="Your report is ready",
+        html="<h1>Report ready</h1><p>You can download it now.</p>",
+    )
+)
+```
+
+## Sender Selection
+
+MailEngin resolves the sender in this order:
+
+1. `from_email` supplied in the request.
+2. Sender saved in the published Developer Template.
+3. `noreply@<authorized-domain>` fallback.
+
+The sender domain must be verified and authorized for the API key. Set the sender in the template or request for predictable production sends.
+
+## Error Handling
+
+API, timeout, malformed-response, and network failures raise `MailEnginError`:
+
+```python
+from mailengin import MailEnginError, SendEmailRequest
+
+try:
+    client.emails.send(
+        SendEmailRequest(
+            to="user@example.com",
+            template_name="welcome-email",
+        )
+    )
+except MailEnginError as error:
+    print(error)
+    print(error.status)        # HTTP status, when available
+    print(error.code)          # Machine-readable error code
+    print(error.request_id)    # Include when contacting support
+    print(error.retry_after)   # Seconds supplied with HTTP 429
+    print(error.body)          # Parsed JSON or response text
+    print(error.is_retryable)
+```
+
+`is_retryable` is true for network errors, timeouts, HTTP `408`, HTTP `429`, and `5xx` responses. The SDK never retries sends automatically because a retry could create a duplicate email until idempotency keys are supported.
+
+## Configuration
+
+```python
+client = MailEngin(
+    os.environ["MAILENGIN_API_KEY"],
+    base_url="https://api.mailengin.app",
+    timeout=15.0,
+)
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `api_key` | None | Full server-side MailEngin API key. |
+| `base_url` | `https://api.mailengin.app` | Override for local, test, or dedicated environments. |
+| `timeout` | `30.0` | Request timeout in seconds. |
+| `http_client` | New HTTPX client | Injectable `httpx.Client` or `httpx.AsyncClient`. |
+
+When you inject an HTTP client, your application owns its lifecycle. Otherwise, use the client as a context manager or call `close()` when finished.
+
+## Testing With an Injected Transport
+
+No real API key is required in unit tests. Inject an HTTPX client backed by `MockTransport`:
+
+```python
+import httpx
+
+from mailengin import MailEngin
+
+
+def handler(request: httpx.Request) -> httpx.Response:
+    assert request.headers["authorization"] == "Bearer test_key"
+    return httpx.Response(
+        200,
+        json={
+            "id": "email_123",
+            "from": "hello@example.com",
+            "to": "user@example.com",
+            "template_name": "welcome-email",
+            "created_at": "2026-08-31T12:00:00Z",
+        },
+    )
+
+
+http_client = httpx.Client(transport=httpx.MockTransport(handler))
+client = MailEngin("test_key", http_client=http_client)
+```
+
+## Development
+
+```bash
+python -m pip install -e . pytest pytest-asyncio ruff mypy build twine
+ruff check .
+mypy src
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution rules and [PUBLISHING.md](./PUBLISHING.md) for maintainer release instructions.
+
+## Resources
+
+- [MailEngin API documentation](https://mailengin.app/dashboard/docs)
+- [Developer Templates](https://mailengin.app/dashboard/dev-templates)
+- [API keys](https://mailengin.app/dashboard/api-keys)
+- [Security policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
+
+## License
+
+Released under the [MIT License](./LICENSE). Copyright 2026 MailEngin.

mailengin-0.1.0/README.md

@@ -0,0 +1,290 @@
+# MailEngin Python SDK
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776ab.svg)](https://www.python.org/)
+[![Typing](https://img.shields.io/badge/typing-strict-2563eb.svg)](https://mypy.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-111827.svg)](./LICENSE)
+
+The official Python SDK for sending transactional email through [MailEngin](https://mailengin.app). It provides synchronous and asynchronous clients, typed dataclass models, configurable timeouts, and structured errors.
+
+> [!IMPORTANT]
+> This package is for server-side applications only. Never expose a MailEngin API key in browser, mobile, desktop, or other client-distributed code.
+
+## Requirements
+
+- Python 3.10 or newer
+- A MailEngin API key
+- A verified sending domain
+
+## Installation
+
+```bash
+python -m pip install mailengin
+```
+
+For a specific version:
+
+```bash
+python -m pip install "mailengin==0.1.0"
+```
+
+## Before You Send
+
+1. [Verify a sending domain](https://mailengin.app/dashboard/domains).
+2. [Create an API key](https://mailengin.app/dashboard/api-keys) and save the full secret.
+3. [Create and publish a Developer Template](https://mailengin.app/dashboard/dev-templates).
+4. Copy the template API name, such as `welcome-email`.
+
+Store the API key in a server-side environment variable:
+
+```env
+MAILENGIN_API_KEY=re_your_full_secret_key
+```
+
+MailEngin displays the full key only once. A masked key cannot authenticate requests.
+
+## Quick Start
+
+```python
+import os
+
+from mailengin import MailEngin, SendEmailRequest
+
+with MailEngin(os.environ["MAILENGIN_API_KEY"]) as client:
+    email = client.emails.send(
+        SendEmailRequest(
+            to="user@example.com",
+            from_email="hello@yourdomain.com",
+            template_name="welcome-email",
+            variables={"first_name": "Asha"},
+        )
+    )
+
+print(email.id)
+```
+
+The published template supplies the subject and HTML. Values in `variables` replace matching template variables such as `{{first_name}}`.
+
+## Async Client
+
+`AsyncMailEngin` exposes the same email methods as coroutines and uses `httpx.AsyncClient` internally:
+
+```python
+import asyncio
+import os
+
+from mailengin import AsyncMailEngin, SendEmailRequest
+
+
+async def main() -> None:
+    async with AsyncMailEngin(os.environ["MAILENGIN_API_KEY"]) as client:
+        email = await client.emails.send(
+            SendEmailRequest(
+                to="user@example.com",
+                template_name="welcome-email",
+                variables={"first_name": "Asha"},
+            )
+        )
+        print(email.id)
+
+
+asyncio.run(main())
+```
+
+Cancel the surrounding asyncio task to cancel an in-flight asynchronous request.
+
+## Send One Email
+
+```python
+request = SendEmailRequest(
+    to="customer@example.com",
+    from_email="hello@yourdomain.com",
+    template_name="account-verification",
+    variables={
+        "first_name": "Asha",
+        "verification_url": "https://yourapp.com/verify/token",
+    },
+    reply_to_mailengin=True,
+)
+
+email = client.emails.send(request)
+print(email.id, email.from_email, email.created_at)
+```
+
+### Send request fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `to` | `str` | Yes | Recipient email address. |
+| `template_name` | `str` | Recommended | Published template API name or exact display name. |
+| `template_id` | `str` | No | Legacy template identifier. Prefer `template_name`. |
+| `variables` | `dict[str, Any]` | No | Values used to render template variables. |
+| `subject` | `str` | Raw HTML only | Template subject override, or required subject for raw HTML. |
+| `from_email` | `str` | Recommended | Sender on a verified domain authorized for the API key. |
+| `html` | `str` | Advanced | Raw HTML used when no template is supplied. |
+| `reply_to_mailengin` | `bool` | No | Route recipient replies into the MailEngin inbox. |
+
+Exactly one content source is required: `template_name`, `template_id`, or `html`. Raw HTML sends also require `subject`.
+
+## Send Personalized Bulk Email
+
+Bulk requests support up to 1,000 recipients. Request-level variables apply to every recipient; recipient variables take precedence.
+
+```python
+from mailengin import BulkRecipient, SendBulkEmailRequest
+
+job = client.emails.send_bulk(
+    SendBulkEmailRequest(
+        to=[
+            BulkRecipient(
+                email="asha@example.com",
+                variables={"first_name": "Asha"},
+            ),
+            BulkRecipient(
+                email="ben@example.com",
+                variables={"first_name": "Ben"},
+            ),
+        ],
+        from_email="hello@yourdomain.com",
+        template_name="product-update",
+        variables={"product_name": "MailEngin"},
+    )
+)
+
+print(job.job_id, job.queued_count)
+```
+
+For the same content without recipient-specific variables, use strings:
+
+```python
+job = client.emails.send_bulk(
+    SendBulkEmailRequest(
+        to=["a@example.com", "b@example.com"],
+        template_name="maintenance-notice",
+    )
+)
+```
+
+A successful bulk response confirms that recipients were queued. It is not a guarantee that every message was delivered.
+
+## Send Raw HTML
+
+Published templates are recommended for reusable product email. For a one-off message, provide both `subject` and `html`:
+
+```python
+email = client.emails.send(
+    SendEmailRequest(
+        to="user@example.com",
+        from_email="reports@yourdomain.com",
+        subject="Your report is ready",
+        html="<h1>Report ready</h1><p>You can download it now.</p>",
+    )
+)
+```
+
+## Sender Selection
+
+MailEngin resolves the sender in this order:
+
+1. `from_email` supplied in the request.
+2. Sender saved in the published Developer Template.
+3. `noreply@<authorized-domain>` fallback.
+
+The sender domain must be verified and authorized for the API key. Set the sender in the template or request for predictable production sends.
+
+## Error Handling
+
+API, timeout, malformed-response, and network failures raise `MailEnginError`:
+
+```python
+from mailengin import MailEnginError, SendEmailRequest
+
+try:
+    client.emails.send(
+        SendEmailRequest(
+            to="user@example.com",
+            template_name="welcome-email",
+        )
+    )
+except MailEnginError as error:
+    print(error)
+    print(error.status)        # HTTP status, when available
+    print(error.code)          # Machine-readable error code
+    print(error.request_id)    # Include when contacting support
+    print(error.retry_after)   # Seconds supplied with HTTP 429
+    print(error.body)          # Parsed JSON or response text
+    print(error.is_retryable)
+```
+
+`is_retryable` is true for network errors, timeouts, HTTP `408`, HTTP `429`, and `5xx` responses. The SDK never retries sends automatically because a retry could create a duplicate email until idempotency keys are supported.
+
+## Configuration
+
+```python
+client = MailEngin(
+    os.environ["MAILENGIN_API_KEY"],
+    base_url="https://api.mailengin.app",
+    timeout=15.0,
+)
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `api_key` | None | Full server-side MailEngin API key. |
+| `base_url` | `https://api.mailengin.app` | Override for local, test, or dedicated environments. |
+| `timeout` | `30.0` | Request timeout in seconds. |
+| `http_client` | New HTTPX client | Injectable `httpx.Client` or `httpx.AsyncClient`. |
+
+When you inject an HTTP client, your application owns its lifecycle. Otherwise, use the client as a context manager or call `close()` when finished.
+
+## Testing With an Injected Transport
+
+No real API key is required in unit tests. Inject an HTTPX client backed by `MockTransport`:
+
+```python
+import httpx
+
+from mailengin import MailEngin
+
+
+def handler(request: httpx.Request) -> httpx.Response:
+    assert request.headers["authorization"] == "Bearer test_key"
+    return httpx.Response(
+        200,
+        json={
+            "id": "email_123",
+            "from": "hello@example.com",
+            "to": "user@example.com",
+            "template_name": "welcome-email",
+            "created_at": "2026-08-31T12:00:00Z",
+        },
+    )
+
+
+http_client = httpx.Client(transport=httpx.MockTransport(handler))
+client = MailEngin("test_key", http_client=http_client)
+```
+
+## Development
+
+```bash
+python -m pip install -e . pytest pytest-asyncio ruff mypy build twine
+ruff check .
+mypy src
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution rules and [PUBLISHING.md](./PUBLISHING.md) for maintainer release instructions.
+
+## Resources
+
+- [MailEngin API documentation](https://mailengin.app/dashboard/docs)
+- [Developer Templates](https://mailengin.app/dashboard/dev-templates)
+- [API keys](https://mailengin.app/dashboard/api-keys)
+- [Security policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
+
+## License
+
+Released under the [MIT License](./LICENSE). Copyright 2026 MailEngin.

mailengin-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailengin"
+version = "0.1.0"
+description = "Official Python SDK for the MailEngin Email API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "MailEngin" }]
+keywords = ["mailengin", "email", "transactional-email", "email-api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1", "typing-extensions>=4.6"]
+
+[project.urls]
+Homepage = "https://mailengin.app"
+Repository = "https://github.com/mailengin/mailengin-python-sdk"
+Issues = "https://github.com/mailengin/mailengin-python-sdk/issues"
+Documentation = "https://mailengin.app/dashboard/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailengin"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mailengin", "tests", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["mailengin"]

mailengin-0.1.0/src/mailengin/__init__.py

@@ -0,0 +1,22 @@
+from .client import AsyncMailEngin, MailEngin
+from .errors import MailEnginError
+from .models import (
+    BulkRecipient,
+    SendBulkEmailRequest,
+    SendBulkEmailResponse,
+    SendEmailRequest,
+    SendEmailResponse,
+)
+
+__all__ = [
+    "AsyncMailEngin",
+    "BulkRecipient",
+    "MailEngin",
+    "MailEnginError",
+    "SendBulkEmailRequest",
+    "SendBulkEmailResponse",
+    "SendEmailRequest",
+    "SendEmailResponse",
+]
+
+__version__ = "0.1.0"

mailengin-0.1.0/src/mailengin/client.py

@@ -0,0 +1,145 @@
+import json
+from typing import Any
+
+import httpx
+from typing_extensions import Self
+
+from .emails import AsyncEmails, Emails
+from .errors import MailEnginError
+
+DEFAULT_BASE_URL = "https://api.mailengin.app"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "mailengin-python/0.1.0"
+
+
+def _api_error(response: httpx.Response) -> MailEnginError:
+    raw = response.text
+    try:
+        body: Any = response.json() if raw else None
+    except json.JSONDecodeError:
+        body = raw
+    message = body.get("message") if isinstance(body, dict) else None
+    code = body.get("code") if isinstance(body, dict) else None
+    retry_after: float | None = None
+    try:
+        retry_after = float(response.headers["retry-after"])
+    except (KeyError, ValueError):
+        pass
+    return MailEnginError(
+        message or f"MailEngin API request failed with status {response.status_code}.",
+        status=response.status_code,
+        code=code if isinstance(code, str) else None,
+        request_id=response.headers.get("x-request-id"),
+        retry_after=retry_after,
+        body=body,
+    )
+
+
+class MailEngin:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("MailEngin requires a non-empty api_key.")
+        if timeout <= 0:
+            raise ValueError("MailEngin timeout must be positive.")
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+        self._api_key = api_key.strip()
+        self._base_url = base_url.rstrip("/")
+        self.emails = Emails(self._post)
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = self._client.post(
+                f"{self._base_url}{path}",
+                json=body,
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Accept": "application/json",
+                    "User-Agent": USER_AGENT,
+                },
+            )
+        except httpx.TimeoutException as error:
+            raise MailEnginError("MailEngin request timed out.", code="request_timeout") from error
+        except httpx.RequestError as error:
+            raise MailEnginError("Unable to reach the MailEngin API.", code="network_error") from error
+        if not response.is_success:
+            raise _api_error(response)
+        try:
+            data = response.json()
+        except json.JSONDecodeError as error:
+            raise MailEnginError("MailEngin API returned invalid JSON.", code="invalid_response") from error
+        if not isinstance(data, dict):
+            raise MailEnginError("MailEngin API returned an invalid response.", code="invalid_response")
+        return data
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncMailEngin:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("AsyncMailEngin requires a non-empty api_key.")
+        if timeout <= 0:
+            raise ValueError("AsyncMailEngin timeout must be positive.")
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = http_client is None
+        self._api_key = api_key.strip()
+        self._base_url = base_url.rstrip("/")
+        self.emails = AsyncEmails(self._post)
+
+    async def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = await self._client.post(
+                f"{self._base_url}{path}",
+                json=body,
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Accept": "application/json",
+                    "User-Agent": USER_AGENT,
+                },
+            )
+        except httpx.TimeoutException as error:
+            raise MailEnginError("MailEngin request timed out.", code="request_timeout") from error
+        except httpx.RequestError as error:
+            raise MailEnginError("Unable to reach the MailEngin API.", code="network_error") from error
+        if not response.is_success:
+            raise _api_error(response)
+        try:
+            data = response.json()
+        except json.JSONDecodeError as error:
+            raise MailEnginError("MailEngin API returned invalid JSON.", code="invalid_response") from error
+        if not isinstance(data, dict):
+            raise MailEnginError("MailEngin API returned an invalid response.", code="invalid_response")
+        return data
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

mailengin-0.1.0/src/mailengin/emails.py

@@ -0,0 +1,105 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import asdict
+from typing import Any
+
+from .errors import MailEnginError
+from .models import (
+    SendBulkEmailRequest,
+    SendBulkEmailResponse,
+    SendEmailRequest,
+    SendEmailResponse,
+)
+
+Post = Callable[[str, dict[str, Any]], dict[str, Any]]
+AsyncPost = Callable[[str, dict[str, Any]], Awaitable[dict[str, Any]]]
+
+
+def _require_content(template_name: str | None, template_id: str | None, html: str | None, subject: str | None) -> None:
+    has_template = bool((template_name or "").strip() or (template_id or "").strip())
+    has_html = bool((html or "").strip())
+    if not has_template and not has_html:
+        raise ValueError("Provide template_name (recommended), template_id, or html.")
+    if not has_template and not (subject or "").strip():
+        raise ValueError("Raw HTML sends require subject.")
+
+
+def _without_none(value: dict[str, Any]) -> dict[str, Any]:
+    return {key: item for key, item in value.items() if item is not None}
+
+
+def _send_payload(request: SendEmailRequest) -> dict[str, Any]:
+    if not request.to.strip():
+        raise ValueError("mailengin.emails.send requires to.")
+    _require_content(request.template_name, request.template_id, request.html, request.subject)
+    return _without_none(asdict(request))
+
+
+def _bulk_payload(request: SendBulkEmailRequest) -> dict[str, Any]:
+    if not request.to:
+        raise ValueError("mailengin.emails.send_bulk requires a non-empty to list.")
+    if len(request.to) > 1_000:
+        raise ValueError("mailengin.emails.send_bulk accepts up to 1000 recipients.")
+    recipients: list[str | dict[str, Any]] = []
+    for recipient in request.to:
+        email = recipient if isinstance(recipient, str) else recipient.email
+        if not email.strip():
+            raise ValueError("Every bulk recipient must include a non-empty email address.")
+        recipients.append(recipient if isinstance(recipient, str) else _without_none(asdict(recipient)))
+    _require_content(request.template_name, request.template_id, request.html, request.subject)
+    payload = _without_none(asdict(request))
+    payload["to"] = recipients
+    return payload
+
+
+def _send_response(data: dict[str, Any]) -> SendEmailResponse:
+    try:
+        return SendEmailResponse(
+            id=str(data["id"]),
+            from_email=str(data["from"]),
+            to=str(data["to"]),
+            template_name=data.get("template_name"),
+            created_at=str(data["created_at"]),
+        )
+    except (KeyError, TypeError, ValueError) as error:
+        raise MailEnginError(
+            "MailEngin API returned an invalid response.", code="invalid_response", body=data
+        ) from error
+
+
+def _bulk_response(data: dict[str, Any]) -> SendBulkEmailResponse:
+    try:
+        return SendBulkEmailResponse(
+            success=bool(data["success"]),
+            job_id=str(data["jobId"]),
+            queued_count=int(data["queued_count"]),
+            sent_count=data.get("sent_count"),
+            failed_count=data.get("failed_count"),
+            template_name=data.get("template_name"),
+            message=str(data["message"]),
+        )
+    except (KeyError, TypeError, ValueError) as error:
+        raise MailEnginError(
+            "MailEngin API returned an invalid response.", code="invalid_response", body=data
+        ) from error
+
+
+class Emails:
+    def __init__(self, post: Post) -> None:
+        self._post = post
+
+    def send(self, request: SendEmailRequest) -> SendEmailResponse:
+        return _send_response(self._post("/api/developer/send", _send_payload(request)))
+
+    def send_bulk(self, request: SendBulkEmailRequest) -> SendBulkEmailResponse:
+        return _bulk_response(self._post("/api/developer/send-bulk", _bulk_payload(request)))
+
+
+class AsyncEmails:
+    def __init__(self, post: AsyncPost) -> None:
+        self._post = post
+
+    async def send(self, request: SendEmailRequest) -> SendEmailResponse:
+        return _send_response(await self._post("/api/developer/send", _send_payload(request)))
+
+    async def send_bulk(self, request: SendBulkEmailRequest) -> SendBulkEmailResponse:
+        return _bulk_response(await self._post("/api/developer/send-bulk", _bulk_payload(request)))

mailengin-0.1.0/src/mailengin/errors.py

@@ -0,0 +1,27 @@
+from typing import Any
+
+
+class MailEnginError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+        retry_after: float | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body
+
+    @property
+    def is_retryable(self) -> bool:
+        return self.code in {"network_error", "request_timeout"} or self.status in {
+            408,
+            429,
+        } or (self.status is not None and self.status >= 500)

mailengin-0.1.0/src/mailengin/models.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+Variables = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class BulkRecipient:
+    email: str
+    variables: Variables | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SendEmailRequest:
+    to: str
+    template_name: str | None = None
+    template_id: str | None = None
+    variables: Variables | None = None
+    subject: str | None = None
+    from_email: str | None = None
+    html: str | None = None
+    reply_to_mailengin: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SendEmailResponse:
+    id: str
+    from_email: str
+    to: str
+    template_name: str | None
+    created_at: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SendBulkEmailRequest:
+    to: list[str | BulkRecipient]
+    template_name: str | None = None
+    template_id: str | None = None
+    variables: Variables | None = None
+    subject: str | None = None
+    from_email: str | None = None
+    html: str | None = None
+    reply_to_mailengin: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SendBulkEmailResponse:
+    success: bool
+    job_id: str
+    queued_count: int
+    template_name: str | None
+    message: str
+    sent_count: int | None = field(default=None)
+    failed_count: int | None = field(default=None)

mailengin-0.1.0/src/mailengin/py.typed

@@ -0,0 +1 @@
+

mailengin-0.1.0/tests/test_mailengin.py

@@ -0,0 +1,135 @@
+import json
+
+import httpx
+import pytest
+
+from mailengin import (
+    AsyncMailEngin,
+    BulkRecipient,
+    MailEngin,
+    MailEnginError,
+    SendBulkEmailRequest,
+    SendEmailRequest,
+)
+
+
+def test_send_maps_request_and_response() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url == "https://api.mailengin.app/api/developer/send"
+        assert request.headers["authorization"] == "Bearer re_test_key"
+        assert request.headers["user-agent"] == "mailengin-python/0.1.0"
+        assert json.loads(request.content) == {
+            "to": "person@example.com",
+            "template_name": "welcome-email",
+            "variables": {"first_name": "Asha"},
+            "from_email": "hello@example.com",
+            "reply_to_mailengin": True,
+        }
+        return httpx.Response(200, json={
+            "id": "msg_123", "from": "hello@example.com", "to": "person@example.com",
+            "template_name": "welcome-email", "created_at": "2026-08-18T10:00:00Z",
+        })
+
+    client = MailEngin("re_test_key", http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+    result = client.emails.send(SendEmailRequest(
+        to="person@example.com", template_name="welcome-email",
+        variables={"first_name": "Asha"}, from_email="hello@example.com",
+        reply_to_mailengin=True,
+    ))
+    assert result.id == "msg_123"
+    assert result.template_name == "welcome-email"
+
+
+def test_bulk_and_rate_limit_error() -> None:
+    calls = 0
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal calls
+        calls += 1
+        payload = json.loads(request.content)
+        assert payload["to"][0] == {"email": "a@example.com", "variables": {"name": "A"}}
+        return httpx.Response(429, headers={"Retry-After": "12", "x-request-id": "req_1"}, json={
+            "message": "Rate limit exceeded", "code": "rate_limited",
+        })
+
+    client = MailEngin("re_test_key", http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+    with pytest.raises(MailEnginError) as caught:
+        client.emails.send_bulk(SendBulkEmailRequest(
+            to=[BulkRecipient("a@example.com", {"name": "A"})], template_name="welcome",
+        ))
+    assert calls == 1
+    assert caught.value.status == 429
+    assert caught.value.retry_after == 12
+    assert caught.value.request_id == "req_1"
+    assert caught.value.is_retryable
+
+
+def test_validates_before_request() -> None:
+    called = False
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        nonlocal called
+        called = True
+        return httpx.Response(200, json={})
+
+    client = MailEngin("re_test_key", http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+    with pytest.raises(ValueError, match="Raw HTML"):
+        client.emails.send(SendEmailRequest(to="person@example.com", html="<p>Hello</p>"))
+    assert not called
+
+
+def test_bulk_success_and_recipient_limit() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        payload = json.loads(request.content)
+        assert payload["to"] == ["a@example.com", {"email": "b@example.com", "variables": {"name": "B"}}]
+        return httpx.Response(200, json={
+            "success": True, "jobId": "bulk_1", "queued_count": 2,
+            "template_name": "welcome", "message": "Queued",
+        })
+
+    client = MailEngin("re_test_key", http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+    result = client.emails.send_bulk(SendBulkEmailRequest(
+        to=["a@example.com", BulkRecipient("b@example.com", {"name": "B"})],
+        template_name="welcome",
+    ))
+    assert result.job_id == "bulk_1"
+    with pytest.raises(ValueError, match="1000"):
+        client.emails.send_bulk(SendBulkEmailRequest(
+            to=["a@example.com"] * 1_001, template_name="welcome",
+        ))
+
+
+def test_invalid_response_and_network_failure() -> None:
+    invalid = MailEngin("re_test_key", http_client=httpx.Client(
+        transport=httpx.MockTransport(lambda _: httpx.Response(200, json={})),
+    ))
+    with pytest.raises(MailEnginError) as malformed:
+        invalid.emails.send(SendEmailRequest(to="person@example.com", template_name="welcome"))
+    assert malformed.value.code == "invalid_response"
+
+    def fail(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("offline", request=request)
+
+    offline = MailEngin("re_test_key", http_client=httpx.Client(transport=httpx.MockTransport(fail)))
+    with pytest.raises(MailEnginError) as network:
+        offline.emails.send(SendEmailRequest(to="person@example.com", template_name="welcome"))
+    assert network.value.code == "network_error"
+    assert network.value.is_retryable
+
+
+@pytest.mark.asyncio
+async def test_async_client() -> None:
+    async def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={
+            "id": "msg_async", "from": "hello@example.com", "to": "person@example.com",
+            "template_name": None, "created_at": "2026-08-18T10:00:00Z",
+        })
+
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.AsyncClient(transport=transport)
+    client = AsyncMailEngin("re_test_key", http_client=http_client)
+    result = await client.emails.send(SendEmailRequest(
+        to="person@example.com", subject="Hello", html="<p>Hello</p>",
+    ))
+    assert result.id == "msg_async"
+    await http_client.aclose()