mailhive 0.1.0__py3-none-any.whl

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",
+]

mailhive/_client.py

@@ -0,0 +1,287 @@
+"""The Mailhive Send clients: Mailhive (sync) and AsyncMailhive."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import os
+import platform
+import random
+import time
+import uuid
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+import httpx
+
+from ._errors import APIConnectionError, APIError, MailhiveError, error_for
+from ._types import AcceptedEmail, Email, SendEmailParams
+from ._version import __version__
+from ._webhooks import verify as _verify_webhook
+
+DEFAULT_BASE_URL = "https://api.mailhive.africa/v1"
+_MAX_RETRY_AFTER = 60.0
+
+
+def _backoff(attempt: int) -> float:
+    """About 0.5s, 1s, 2s … up to 8s, with jitter."""
+    ceiling = min(8.0, 0.5 * 2**attempt)
+    return ceiling / 2 + random.random() * ceiling / 2
+
+
+def _retry_after(headers: Mapping[str, str]) -> Optional[float]:
+    value = headers.get("retry-after")
+    try:
+        seconds = float(value) if value not in (None, "") else None
+    except ValueError:
+        return None
+    return seconds if seconds is not None and seconds >= 0 else None
+
+
+def _encode_email(params: Mapping[str, Any]) -> Dict[str, Any]:
+    email = dict(params)
+    if "from_" in email:
+        email["from"] = email.pop("from_")
+    attachments = email.get("attachments")
+    if attachments:
+        email["attachments"] = [
+            {**a, "content": base64.b64encode(a["content"]).decode()} if isinstance(a.get("content"), (bytes, bytearray)) else dict(a)
+            for a in attachments
+        ]
+    return email
+
+
+class _Base:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        key = api_key or os.environ.get("MAILHIVE_API_KEY")
+        if not key:
+            raise MailhiveError(
+                "No API key. Pass one to Mailhive(...) or set MAILHIVE_API_KEY. "
+                "Create keys under Mailhive Send → API keys."
+            )
+        if key.startswith("mhp_"):
+            raise MailhiveError(
+                "That's a form's publishable key (mhp_…). The server SDK needs a secret API key (mhs_…) "
+                "from Mailhive Send → API keys."
+            )
+        self._api_key = key
+        self.base_url = (base_url or os.environ.get("MAILHIVE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+
+    def __repr__(self) -> str:  # never shows the key
+        return f"{type(self).__name__}(base_url={self.base_url!r})"
+
+    def _prepare(self, method: str, body: Any, idempotency_key: Optional[str]) -> Tuple[Dict[str, str], Optional[bytes]]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"mailhive-python/{__version__} python/{platform.python_version()}",
+        }
+        content = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            content = json.dumps(body).encode()
+        if method == "POST":
+            # One key per call, reused on every retry: a retry never sends twice.
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        return headers, content
+
+    @staticmethod
+    def _error(response: httpx.Response) -> APIError:
+        try:
+            error = response.json().get("error") or {}
+        except (ValueError, AttributeError):
+            error = {}
+        return error_for(
+            error.get("message") or f"HTTP {response.status_code} {response.reason_phrase}".strip(),
+            status=response.status_code,
+            code=error.get("code") or "http_error",
+            details=error.get("details"),
+            request_id=error.get("request_id") or response.headers.get("x-request-id"),
+            headers=response.headers,
+        )
+
+    def _wait_before_retry(self, error: APIError, attempt: int) -> Optional[float]:
+        """Seconds to wait before retrying, or None to give up. Only a rate
+        limit and server errors are worth retrying."""
+        if attempt >= self.max_retries:
+            return None
+        if not (error.status >= 500 or (error.status == 429 and error.code == "rate_limited")):
+            return None
+        wait = _retry_after({k.lower(): v for k, v in error.headers.items()})
+        if wait is not None and wait > _MAX_RETRY_AFTER:
+            return None
+        return _backoff(attempt) if wait is None else wait
+
+
+class Emails:
+    def __init__(self, client: "Mailhive") -> None:
+        self._client = client
+
+    def send(
+        self, params: Optional[SendEmailParams] = None, *, idempotency_key: Optional[str] = None, **fields: Any
+    ) -> AcceptedEmail:
+        """Sends one email. Pass the fields as a dict, or as keyword
+        arguments with ``from_`` for ``from``."""
+        return self._client._request("POST", "/send/emails", _encode_email({**(params or {}), **fields}), idempotency_key)
+
+    def send_batch(self, emails: List[SendEmailParams], *, idempotency_key: Optional[str] = None) -> List[AcceptedEmail]:
+        """Up to 100 independent emails; all are accepted, or none."""
+        response = self._client._request(
+            "POST", "/send/emails/batch", {"emails": [_encode_email(e) for e in emails]}, idempotency_key
+        )
+        return response["data"]
+
+    def get(self, email_id: str) -> Email:
+        return self._client._request("GET", f"/send/emails/{_quote(email_id)}", None, None)
+
+
+class AsyncEmails:
+    def __init__(self, client: "AsyncMailhive") -> None:
+        self._client = client
+
+    async def send(
+        self, params: Optional[SendEmailParams] = None, *, idempotency_key: Optional[str] = None, **fields: Any
+    ) -> AcceptedEmail:
+        return await self._client._request("POST", "/send/emails", _encode_email({**(params or {}), **fields}), idempotency_key)
+
+    async def send_batch(self, emails: List[SendEmailParams], *, idempotency_key: Optional[str] = None) -> List[AcceptedEmail]:
+        response = await self._client._request(
+            "POST", "/send/emails/batch", {"emails": [_encode_email(e) for e in emails]}, idempotency_key
+        )
+        return response["data"]
+
+    async def get(self, email_id: str) -> Email:
+        return await self._client._request("GET", f"/send/emails/{_quote(email_id)}", None, None)
+
+
+def _quote(value: str) -> str:
+    from urllib.parse import quote
+
+    return quote(value, safe="")
+
+
+class _Webhooks:
+    @staticmethod
+    def verify(payload, signature, secret, *, tolerance: int = 300, now: Optional[float] = None) -> Dict[str, Any]:
+        return _verify_webhook(payload, signature, secret, tolerance=tolerance, now=now)
+
+
+class Mailhive(_Base):
+    """The Mailhive Send API client.
+
+    ``Mailhive()`` reads MAILHIVE_API_KEY. Use it as a context manager, or
+    call ``close()``, to release its connections."""
+
+    webhooks = _Webhooks()
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+        self.emails = Emails(self)
+
+    def _request(self, method: str, path: str, body: Any, idempotency_key: Optional[str]) -> Any:
+        headers, content = self._prepare(method, body, idempotency_key)
+        url = f"{self.base_url}{path}"
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(method, url, headers=headers, content=content, timeout=self.timeout)
+            except httpx.TransportError as exc:
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(_connection_message(exc, self)) from exc
+            if response.is_success:
+                return response.json()
+            error = self._error(response)
+            wait = self._wait_before_retry(error, attempt)
+            if wait is None:
+                raise error
+            time.sleep(wait)
+            attempt += 1
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Mailhive":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncMailhive(_Base):
+    """The async client: ``await client.emails.send(...)``."""
+
+    webhooks = _Webhooks()
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_http = http_client is None
+        self.emails = AsyncEmails(self)
+
+    async def _request(self, method: str, path: str, body: Any, idempotency_key: Optional[str]) -> Any:
+        headers, content = self._prepare(method, body, idempotency_key)
+        url = f"{self.base_url}{path}"
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(method, url, headers=headers, content=content, timeout=self.timeout)
+            except httpx.TransportError as exc:
+                if attempt < self.max_retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(_connection_message(exc, self)) from exc
+            if response.is_success:
+                return response.json()
+            error = self._error(response)
+            wait = self._wait_before_retry(error, attempt)
+            if wait is None:
+                raise error
+            await asyncio.sleep(wait)
+            attempt += 1
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncMailhive":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+def _connection_message(exc: Exception, client: _Base) -> str:
+    if isinstance(exc, httpx.TimeoutException):
+        return f"The Mailhive API didn't answer within {client.timeout:g} seconds."
+    return f"Couldn't reach the Mailhive API at {client.base_url}."

mailhive/_errors.py

@@ -0,0 +1,102 @@
+"""Every error the SDK raises is a MailhiveError. Errors from the API carry
+the HTTP status, Mailhive's stable error ``code`` and the ``request_id`` to
+quote to support."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class MailhiveError(Exception):
+    """Base class for everything this SDK raises."""
+
+
+class APIError(MailhiveError):
+    """An error response from the API. Check ``code``, not ``message``."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        details: Any = None,
+        request_id: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.details = details
+        self.request_id = request_id
+        self.headers = dict(headers or {})
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status={self.status}, code={self.code!r}, request_id={self.request_id!r})"
+
+
+class AuthenticationError(APIError):
+    """401: missing, unknown or revoked API key."""
+
+
+class BillingError(APIError):
+    """402: Mailhive Send is paused over an unpaid invoice."""
+
+
+class PermissionDeniedError(APIError):
+    """403: Send isn't activated, or the stream is paused."""
+
+
+class NotFoundError(APIError):
+    """404"""
+
+
+class ConflictError(APIError):
+    """409: e.g. an Idempotency-Key reused for a different request."""
+
+
+class ValidationError(APIError):
+    """422: the request is invalid; ``details`` lists every problem."""
+
+
+class RateLimitError(APIError):
+    """429: ``rate_limited`` (retried for you), or ``monthly_quota_reached``
+    / ``daily_cap_reached`` (not retried: waiting won't help)."""
+
+    @property
+    def retry_after(self) -> Optional[float]:
+        value = {k.lower(): v for k, v in self.headers.items()}.get("retry-after")
+        try:
+            return float(value) if value not in (None, "") else None
+        except ValueError:
+            return None
+
+
+class APIConnectionError(MailhiveError):
+    """The API couldn't be reached, or didn't answer in time."""
+
+
+class WebhookVerificationError(MailhiveError):
+    """A webhook's signature didn't check out. ``reason`` is ``header``,
+    ``timestamp`` or ``signature``."""
+
+    def __init__(self, message: str, reason: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+_BY_STATUS = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: BillingError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+def error_for(message: str, **kwargs: Any) -> APIError:
+    return _BY_STATUS.get(kwargs["status"], APIError)(message, **kwargs)

mailhive/_types.py

@@ -0,0 +1,73 @@
+"""Request and response shapes. Keys match the REST API exactly, so the API
+reference applies as written (``from`` is a Python keyword, hence the
+functional TypedDict syntax)."""
+
+from __future__ import annotations
+
+import sys
+from typing import Dict, List, Optional, Union
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict
+else:  # pragma: no cover
+    from typing_extensions import NotRequired, TypedDict
+
+Recipients = Union[str, List[str]]
+
+
+class Attachment(TypedDict):
+    filename: str
+    #: The file: base64 text, or bytes (encoded for you).
+    content: Union[str, bytes]
+    content_type: NotRequired[str]
+
+
+SendEmailParams = TypedDict(
+    "SendEmailParams",
+    {
+        "from": str,
+        "to": Recipients,
+        "cc": NotRequired[Recipients],
+        "bcc": NotRequired[Recipients],
+        "subject": NotRequired[str],
+        "html": NotRequired[str],
+        "text": NotRequired[str],
+        "template_id": NotRequired[str],
+        "variables": NotRequired[Dict[str, Union[str, int, float, bool, None]]],
+        "reply_to": NotRequired[Recipients],
+        "headers": NotRequired[Dict[str, str]],
+        "tags": NotRequired[Dict[str, str]],
+        "attachments": NotRequired[List[Attachment]],
+    },
+)
+
+
+class AcceptedEmail(TypedDict):
+    id: str
+    status: str
+    suppressed: List[str]
+    #: True when sent with a test key (mhs_test_…): delivery is simulated.
+    test: bool
+
+
+Email = TypedDict(
+    "Email",
+    {
+        "id": str,
+        "status": str,
+        "stream": str,
+        "test": bool,
+        "from": str,
+        "to": List[str],
+        "cc": List[str],
+        "bcc": List[str],
+        "subject": str,
+        "suppressed": List[str],
+        "tags": Dict[str, str],
+        "template_id": Optional[str],
+        "template_version": Optional[int],
+        "created_at": Optional[str],
+        "sent_at": Optional[str],
+        "last_event_at": Optional[str],
+    },
+)

mailhive/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mailhive/_webhooks.py

@@ -0,0 +1,67 @@
+"""Checking Mailhive-Signature on webhooks."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from ._errors import WebhookVerificationError
+
+_V1 = re.compile(r"^[0-9a-fA-F]{64}$")
+
+
+def _parse(header: str) -> Optional[tuple]:
+    timestamp: Optional[int] = None
+    signatures: List[str] = []
+    for part in header.split(","):
+        key, sep, value = part.partition("=")
+        if not sep:
+            continue
+        key, value = key.strip(), value.strip()
+        if key == "t" and value.isdigit():
+            timestamp = int(value)
+        elif key == "v1" and _V1.match(value):
+            signatures.append(value.lower())
+    if timestamp is None or not signatures:
+        return None
+    return timestamp, signatures
+
+
+def verify(
+    payload: Union[str, bytes],
+    signature: Optional[str],
+    secret: str,
+    *,
+    tolerance: int = 300,
+    now: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Checks a webhook's ``Mailhive-Signature`` header (HMAC-SHA256 of
+    ``"<t>.<raw body>"`` with the endpoint's secret) and returns the parsed
+    event. ``payload`` must be the raw body exactly as received: parsing and
+    re-serializing it changes the bytes. Several ``v1=`` values are accepted,
+    so secrets can be rotated. Raises WebhookVerificationError."""
+    if isinstance(payload, (dict, list)):
+        raise TypeError(
+            "verify() needs the raw request body (str or bytes), not parsed JSON: "
+            "re-serializing changes the bytes, so the signature can't match."
+        )
+    body = payload.encode() if isinstance(payload, str) else bytes(payload)
+    parsed = _parse(signature) if signature else None
+    if parsed is None:
+        raise WebhookVerificationError("Missing or malformed Mailhive-Signature header.", "header")
+    timestamp, signatures = parsed
+    current = time.time() if now is None else now
+    if abs(current - timestamp) > tolerance:
+        raise WebhookVerificationError(
+            f"The webhook's timestamp is more than {tolerance} seconds from now; it may be a replay.", "timestamp"
+        )
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
+    if not any(hmac.compare_digest(expected, candidate) for candidate in signatures):
+        raise WebhookVerificationError(
+            "The webhook's signature doesn't match. Check the endpoint's signing secret.", "signature"
+        )
+    return json.loads(body)

mailhive/django.py

@@ -0,0 +1,127 @@
+"""A Django email backend that sends through Mailhive Send.
+
+    # settings.py, Django 6.1+
+    MAILERS = {"default": {"BACKEND": "mailhive.django.EmailBackend", "OPTIONS": {"api_key": env("MAILHIVE_API_KEY")}}}
+
+    # settings.py, earlier versions
+    EMAIL_BACKEND = "mailhive.django.EmailBackend"
+    MAILHIVE_API_KEY = env("MAILHIVE_API_KEY")   # or leave it in the environment
+
+Everything Django sends then goes through the API: send_mail, EmailMessage,
+EmailMultiAlternatives (the text/html alternative becomes ``html``),
+attachments, cc, bcc, reply_to and extra headers. Mailhive features: set
+``message.mailhive_tags = {...}`` or ``message.mailhive_idempotency_key``.
+"""
+
+from __future__ import annotations
+
+from email.mime.base import MIMEBase
+from typing import Any, Dict, List, Optional, Sequence
+
+from django.conf import settings
+from django.core.mail.backends.base import BaseEmailBackend
+from django.core.mail.message import EmailMessage
+
+from ._client import Mailhive
+from ._errors import MailhiveError
+
+
+def _attachment(item: Any) -> Dict[str, Any]:
+    if isinstance(item, MIMEBase):
+        return {
+            "filename": item.get_filename() or "attachment",
+            "content": item.get_payload(decode=True) or b"",
+            "content_type": item.get_content_type(),
+        }
+    filename, content, mimetype = item[0], item[1], item[2] if len(item) > 2 else None
+    data = content.encode() if isinstance(content, str) else bytes(content)
+    return {"filename": filename or "attachment", "content": data, **({"content_type": mimetype} if mimetype else {})}
+
+
+def message_params(message: EmailMessage) -> Dict[str, Any]:
+    """The API request for one Django message."""
+    params: Dict[str, Any] = {
+        "from": message.from_email or settings.DEFAULT_FROM_EMAIL,
+        "to": list(message.to),
+        "subject": message.subject,
+    }
+    if message.cc:
+        params["cc"] = list(message.cc)
+    if message.bcc:
+        params["bcc"] = list(message.bcc)
+    if message.reply_to:
+        params["reply_to"] = list(message.reply_to)
+    if message.content_subtype == "html":
+        params["html"] = message.body
+    elif message.body:
+        params["text"] = message.body
+    for content, mimetype in getattr(message, "alternatives", None) or []:
+        if mimetype == "text/html":
+            params["html"] = content
+    if message.extra_headers:
+        params["headers"] = {k: str(v) for k, v in message.extra_headers.items()}
+    if message.attachments:
+        params["attachments"] = [_attachment(a) for a in message.attachments]
+    tags = getattr(message, "mailhive_tags", None)
+    if tags:
+        params["tags"] = dict(tags)
+    return params
+
+
+class EmailBackend(BaseEmailBackend):
+    def __init__(
+        self,
+        fail_silently: bool = False,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        # fail_silently is kept here rather than passed up: Django 6.1+
+        # deprecates it on the base class. alias and anything unknown go up,
+        # so Django can report a misconfigured MAILERS entry.
+        super().__init__(**kwargs)
+        self.fail_silently = fail_silently
+        self.api_key = api_key or getattr(settings, "MAILHIVE_API_KEY", None)
+        self.base_url = base_url or getattr(settings, "MAILHIVE_BASE_URL", None)
+        self._client: Optional[Mailhive] = None
+
+    def open(self) -> bool:
+        if self._client is not None:
+            return False
+        try:
+            self._client = Mailhive(self.api_key, base_url=self.base_url)
+        except MailhiveError:
+            if not self.fail_silently:
+                raise
+            return False
+        return True
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def send_messages(self, email_messages: Sequence[EmailMessage]) -> int:
+        if not email_messages:
+            return 0
+        opened = self.open()
+        if self._client is None:
+            return 0
+        sent = 0
+        try:
+            for message in email_messages:
+                if not message.recipients():
+                    continue
+                try:
+                    self._client.emails.send(
+                        message_params(message), idempotency_key=getattr(message, "mailhive_idempotency_key", None)
+                    )
+                    sent += 1
+                except MailhiveError:
+                    if not self.fail_silently:
+                        raise
+        finally:
+            if opened:
+                self.close()
+        return sent

mailhive-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+mailhive/__init__.py,sha256=Jz4m4yQJ3b61wWDqfyM88Y_ySuHTPdbYgdlg57Lyg44,1173
+mailhive/_client.py,sha256=Ab6DVD7AdhRJ1xPCozvYttFITeRCA8iN9Y70BMuykSk,10677
+mailhive/_errors.py,sha256=82x1rJW3NZW2jzwk8makQHHOgoHU9Di6TNCxenfFcMQ,2821
+mailhive/_types.py,sha256=SxJBbKhTjpvcWC3G63xbYz5yDSDVfLHY1xqWuA04e0A,1953
+mailhive/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+mailhive/_webhooks.py,sha256=L5P7670JoT_VqlnyG0TbgenrNvl64ioEl9126XJgcrI,2540
+mailhive/django.py,sha256=5u7zG1TqVQPI3Ioww1Vr1QiNiMYTdWyf0GNlSZ29dkY,4671
+mailhive/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mailhive-0.1.0.dist-info/METADATA,sha256=6FuBf4sxGSoO0V2rfsBU8Orw_O764gxpjaraYUcJaYY,5084
+mailhive-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mailhive-0.1.0.dist-info/licenses/LICENSE,sha256=HBvBAv8I3cl7npvnos9QQGJvogd1MuCtOo9G7bZhvt8,1063
+mailhive-0.1.0.dist-info/RECORD,,

mailhive-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mailhive-0.1.0.dist-info/licenses/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.