mailhive 0.1.0__tar.gz

mailhive-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.pytest_cache/

mailhive-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- `Mailhive` and `AsyncMailhive`, with `emails.send`, `emails.send_batch` and `emails.get`.
+- Idempotency keys reused across retries, and `Retry-After` honoured.
+- Typed errors that carry `request_id`.
+- `verify_webhook`, with secret rotation.
+- The Django email backend `mailhive.django.EmailBackend`.

mailhive-0.1.0/LICENSE

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

mailhive-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: mailhive
+Version: 0.1.0
+Summary: The official Python SDK for Mailhive Send: transactional email from Africa.
+Project-URL: Homepage, https://mailhive.africa/docs/sdks/python
+Project-URL: Source, https://github.com/Naszat/mailhive-sdks/tree/main/python
+Project-URL: Issues, https://github.com/Naszat/mailhive-sdks/issues
+Author: Naszat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: africa,django,email,mailhive,transactional-email
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Description-Content-Type: text/markdown
+
+# mailhive
+
+The official Python SDK for [Mailhive Send](https://mailhive.africa/docs/send/overview). It supports Python 3.9+, with sync and async clients and a Django email backend.
+
+```sh
+pip install mailhive
+```
+
+## Send an email
+
+```python
+from mailhive import Mailhive
+
+client = Mailhive()  # reads MAILHIVE_API_KEY
+
+email = client.emails.send({
+    "from": "Acme <hello@acme.com>",
+    "to": "ada@example.com",
+    "subject": "Your receipt",
+    "html": "<p>Thanks for your order.</p>",
+})
+print(email["id"])
+```
+
+The keys match the [API reference](https://mailhive.africa/docs/api/send-email) exactly: `cc`, `bcc`, `reply_to`, `headers`, `tags`, `template_id`, `variables` and `attachments`. You can also pass keyword arguments, with `from_` standing in for `from`:
+
+```python
+client.emails.send(from_="hello@acme.com", to="ada@example.com", subject="Hi", text="Hello")
+```
+
+Attachment `content` can be `bytes`, which are encoded for you, or base64 text.
+
+```python
+client.emails.send_batch([email1, email2])   # up to 100; all accepted or none
+client.emails.get(email_id)                  # status: "delivered", "bounced", …
+```
+
+### Async
+
+```python
+from mailhive import AsyncMailhive
+
+async with AsyncMailhive() as client:
+    await client.emails.send({...})
+```
+
+## Retries and idempotency
+
+Every send carries an `Idempotency-Key`. Retries reuse it, so **a retry never sends twice**.
+
+- **Retried** (up to 2 times, then configurable): network errors, timeouts, 5xx responses, and `429 rate_limited` after the `Retry-After` delay.
+- **Not retried:** a used-up allowance (`monthly_quota_reached`, `daily_cap_reached`) and invalid requests.
+
+To stay safe across restarts, pass your own key:
+
+```python
+client.emails.send(email, idempotency_key=f"order-{order.id}-receipt")
+```
+
+## Errors
+
+```python
+from mailhive import RateLimitError, ValidationError
+
+try:
+    client.emails.send(email)
+except ValidationError as error:
+    print(error.code, error.message, error.details, error.request_id)
+except RateLimitError as error:
+    if error.code == "monthly_quota_reached":
+        ...
+```
+
+| Exception | Status |
+|---|---|
+| `AuthenticationError` | 401 |
+| `BillingError` | 402 |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 (e.g. `idempotency_conflict`) |
+| `ValidationError` | 422 |
+| `RateLimitError` | 429 (`retry_after` in seconds) |
+| `APIError` | other statuses, and the base class of all of the above |
+| `APIConnectionError` | no response |
+
+All of them subclass `MailhiveError`.
+
+## Webhooks
+
+Pass the **raw** body, exactly as received:
+
+```python
+from mailhive import WebhookVerificationError, verify_webhook
+
+# Django
+def mailhive_webhook(request):
+    try:
+        event = verify_webhook(request.body, request.headers.get("Mailhive-Signature"), settings.MAILHIVE_WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        return HttpResponse(status=400)
+    ...
+
+# Flask: verify_webhook(request.get_data(), request.headers.get("Mailhive-Signature"), secret)
+# FastAPI: verify_webhook(await request.body(), request.headers.get("mailhive-signature"), secret)
+```
+
+## Django
+
+```python
+# settings.py, Django 6.1 and later
+MAILERS = {
+    "default": {
+        "BACKEND": "mailhive.django.EmailBackend",
+        "OPTIONS": {"api_key": os.environ["MAILHIVE_API_KEY"]},
+    },
+}
+
+# settings.py, earlier versions
+EMAIL_BACKEND = "mailhive.django.EmailBackend"
+MAILHIVE_API_KEY = os.environ["MAILHIVE_API_KEY"]
+```
+
+`send_mail`, `EmailMessage` and `EmailMultiAlternatives` all send through Mailhive, including HTML alternatives, attachments, cc, bcc, Reply-To and extra headers. You can also set `message.mailhive_tags` or `message.mailhive_idempotency_key` on a message.
+
+## Options
+
+```python
+Mailhive(
+    api_key="mhs_…",                                 # default: MAILHIVE_API_KEY
+    base_url="https://api-beta.mailhive.africa/v1",  # default: MAILHIVE_BASE_URL, then production
+    timeout=30.0,
+    max_retries=2,
+)
+```
+
+**Test keys** (`mhs_test_…`) work unchanged: delivery is simulated and nothing is billed. [More about test keys](https://mailhive.africa/docs/send/api-keys#test-keys).

mailhive-0.1.0/README.md

@@ -0,0 +1,136 @@
+# mailhive
+
+The official Python SDK for [Mailhive Send](https://mailhive.africa/docs/send/overview). It supports Python 3.9+, with sync and async clients and a Django email backend.
+
+```sh
+pip install mailhive
+```
+
+## Send an email
+
+```python
+from mailhive import Mailhive
+
+client = Mailhive()  # reads MAILHIVE_API_KEY
+
+email = client.emails.send({
+    "from": "Acme <hello@acme.com>",
+    "to": "ada@example.com",
+    "subject": "Your receipt",
+    "html": "<p>Thanks for your order.</p>",
+})
+print(email["id"])
+```
+
+The keys match the [API reference](https://mailhive.africa/docs/api/send-email) exactly: `cc`, `bcc`, `reply_to`, `headers`, `tags`, `template_id`, `variables` and `attachments`. You can also pass keyword arguments, with `from_` standing in for `from`:
+
+```python
+client.emails.send(from_="hello@acme.com", to="ada@example.com", subject="Hi", text="Hello")
+```
+
+Attachment `content` can be `bytes`, which are encoded for you, or base64 text.
+
+```python
+client.emails.send_batch([email1, email2])   # up to 100; all accepted or none
+client.emails.get(email_id)                  # status: "delivered", "bounced", …
+```
+
+### Async
+
+```python
+from mailhive import AsyncMailhive
+
+async with AsyncMailhive() as client:
+    await client.emails.send({...})
+```
+
+## Retries and idempotency
+
+Every send carries an `Idempotency-Key`. Retries reuse it, so **a retry never sends twice**.
+
+- **Retried** (up to 2 times, then configurable): network errors, timeouts, 5xx responses, and `429 rate_limited` after the `Retry-After` delay.
+- **Not retried:** a used-up allowance (`monthly_quota_reached`, `daily_cap_reached`) and invalid requests.
+
+To stay safe across restarts, pass your own key:
+
+```python
+client.emails.send(email, idempotency_key=f"order-{order.id}-receipt")
+```
+
+## Errors
+
+```python
+from mailhive import RateLimitError, ValidationError
+
+try:
+    client.emails.send(email)
+except ValidationError as error:
+    print(error.code, error.message, error.details, error.request_id)
+except RateLimitError as error:
+    if error.code == "monthly_quota_reached":
+        ...
+```
+
+| Exception | Status |
+|---|---|
+| `AuthenticationError` | 401 |
+| `BillingError` | 402 |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 (e.g. `idempotency_conflict`) |
+| `ValidationError` | 422 |
+| `RateLimitError` | 429 (`retry_after` in seconds) |
+| `APIError` | other statuses, and the base class of all of the above |
+| `APIConnectionError` | no response |
+
+All of them subclass `MailhiveError`.
+
+## Webhooks
+
+Pass the **raw** body, exactly as received:
+
+```python
+from mailhive import WebhookVerificationError, verify_webhook
+
+# Django
+def mailhive_webhook(request):
+    try:
+        event = verify_webhook(request.body, request.headers.get("Mailhive-Signature"), settings.MAILHIVE_WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        return HttpResponse(status=400)
+    ...
+
+# Flask: verify_webhook(request.get_data(), request.headers.get("Mailhive-Signature"), secret)
+# FastAPI: verify_webhook(await request.body(), request.headers.get("mailhive-signature"), secret)
+```
+
+## Django
+
+```python
+# settings.py, Django 6.1 and later
+MAILERS = {
+    "default": {
+        "BACKEND": "mailhive.django.EmailBackend",
+        "OPTIONS": {"api_key": os.environ["MAILHIVE_API_KEY"]},
+    },
+}
+
+# settings.py, earlier versions
+EMAIL_BACKEND = "mailhive.django.EmailBackend"
+MAILHIVE_API_KEY = os.environ["MAILHIVE_API_KEY"]
+```
+
+`send_mail`, `EmailMessage` and `EmailMultiAlternatives` all send through Mailhive, including HTML alternatives, attachments, cc, bcc, Reply-To and extra headers. You can also set `message.mailhive_tags` or `message.mailhive_idempotency_key` on a message.
+
+## Options
+
+```python
+Mailhive(
+    api_key="mhs_…",                                 # default: MAILHIVE_API_KEY
+    base_url="https://api-beta.mailhive.africa/v1",  # default: MAILHIVE_BASE_URL, then production
+    timeout=30.0,
+    max_retries=2,
+)
+```
+
+**Test keys** (`mhs_test_…`) work unchanged: delivery is simulated and nothing is billed. [More about test keys](https://mailhive.africa/docs/send/api-keys#test-keys).

mailhive-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailhive"
+dynamic = ["version"]
+description = "The official Python SDK for Mailhive Send: transactional email from Africa."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Naszat" }]
+keywords = ["mailhive", "email", "transactional-email", "django", "africa"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Django",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Communications :: Email",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25,<1", "typing-extensions>=4.7; python_version<'3.11'"]
+
+[project.optional-dependencies]
+django = ["django>=4.2"]
+
+[project.urls]
+Homepage = "https://mailhive.africa/docs/sdks/python"
+Source = "https://github.com/Naszat/mailhive-sdks/tree/main/python"
+Issues = "https://github.com/Naszat/mailhive-sdks/issues"
+
+[tool.hatch.version]
+path = "src/mailhive/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailhive"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

mailhive-0.1.0/src/mailhive/__init__.py

@@ -0,0 +1,48 @@
+"""The official Python SDK for Mailhive Send.
+
+    from mailhive import Mailhive
+
+    client = Mailhive()  # reads MAILHIVE_API_KEY
+    client.emails.send({"from": "hello@acme.com", "to": "ada@example.com", "subject": "Hi", "text": "Hello"})
+"""
+
+from ._client import DEFAULT_BASE_URL, AsyncMailhive, Mailhive
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BillingError,
+    ConflictError,
+    MailhiveError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+    WebhookVerificationError,
+)
+from ._types import AcceptedEmail, Attachment, Email, SendEmailParams
+from ._version import __version__
+from ._webhooks import verify as verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIError",
+    "AcceptedEmail",
+    "AsyncMailhive",
+    "Attachment",
+    "AuthenticationError",
+    "BillingError",
+    "ConflictError",
+    "Email",
+    "Mailhive",
+    "MailhiveError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "SendEmailParams",
+    "ValidationError",
+    "WebhookVerificationError",
+    "__version__",
+    "verify_webhook",
+]