postilon 1.0.0__py3-none-any.whl

postilon/__init__.py

@@ -0,0 +1,21 @@
+"""Python client for the Postilon transactional email API (https://postilon.com/docs)."""
+
+from ._client import Domains, Emails, Files, Inbound, Postilon, Suppressions, Templates, Webhooks
+from ._errors import PostilonError
+from ._signature import verify_webhook_signature
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Postilon",
+    "PostilonError",
+    "verify_webhook_signature",
+    "Emails",
+    "Domains",
+    "Templates",
+    "Files",
+    "Suppressions",
+    "Webhooks",
+    "Inbound",
+    "__version__",
+]

postilon/_client.py

@@ -0,0 +1,275 @@
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional, Union, cast
+
+from ._errors import error_from_response
+from ._signature import verify_webhook_signature
+from .types import (
+    CreateDomainParams,
+    CreateSuppressionParams,
+    CreateTemplateParams,
+    CreateWebhookParams,
+    Deleted,
+    Domain,
+    DomainVerification,
+    Email,
+    FileObject,
+    InboundEmail,
+    ListPage,
+    SendBatchParams,
+    SendBatchResponse,
+    SendEmailParams,
+    SendEmailResponse,
+    Suppression,
+    Template,
+    UpdateDomainParams,
+    UpdateTemplateParams,
+    UpdateWebhookParams,
+    UploadFileParams,
+    Webhook,
+    WebhookDelivery,
+)
+
+DEFAULT_BASE_URL = "https://api.postilon.com"
+USER_AGENT = "postilon-python/1.0.0"
+
+Query = Dict[str, Union[str, int, None]]
+
+
+def _id(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+class _Transport:
+    def __init__(self, api_key: str, base_url: str, timeout: float) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Query] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        raw: bool = False,
+    ) -> Any:
+        url = self._base_url + path
+        params = {k: str(v) for k, v in (query or {}).items() if v is not None}
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as res:
+                content = res.read()
+        except urllib.error.HTTPError as err:
+            raise error_from_response(err.code, err.headers, err.read()) from None
+        if raw:
+            return content
+        return json.loads(content.decode("utf-8")) if content else None
+
+
+class Postilon:
+    """Client for the Postilon API. Every method returns the parsed JSON response as a ``dict``,
+    and raises ``PostilonError`` when the API answers with an error.
+
+    >>> postilon = Postilon(os.environ["POSTILON_API_KEY"])
+    >>> postilon.emails.send({"from": "hello@acme.com", "to": "jane@example.com", "subject": "Hi", "text": "Hello"})
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0) -> None:
+        """``api_key`` is a ``ps_live_…`` or ``ps_test_…`` key. ``timeout`` is in seconds."""
+        if not api_key:
+            raise ValueError("Postilon: an API key is required (ps_live_… or ps_test_…).")
+        transport = _Transport(api_key, base_url, timeout)
+        self.emails = Emails(transport)
+        self.domains = Domains(transport)
+        self.templates = Templates(transport)
+        self.files = Files(transport)
+        self.suppressions = Suppressions(transport)
+        self.webhooks = Webhooks(transport)
+        self.inbound = Inbound(transport)
+
+
+class _Resource:
+    def __init__(self, transport: _Transport) -> None:
+        self._t = transport
+
+
+class Emails(_Resource):
+    def send(self, params: SendEmailParams, *, idempotency_key: Optional[str] = None) -> SendEmailResponse:
+        """``POST /v1/emails``. ``idempotency_key`` is sent as the ``Idempotency-Key`` header: a retry
+        with the same key and body returns the original response instead of sending again."""
+        return cast(SendEmailResponse, self._t.request("POST", "/v1/emails", body=params, idempotency_key=idempotency_key))
+
+    def send_batch(self, params: SendBatchParams) -> SendBatchResponse:
+        """``POST /v1/emails/batch``: up to 100 emails, all or nothing."""
+        return cast(SendBatchResponse, self._t.request("POST", "/v1/emails/batch", body=params))
+
+    def get(self, email_id: str) -> Email:
+        """``GET /v1/emails/{id}``, with its events."""
+        return cast(Email, self._t.request("GET", f"/v1/emails/{_id(email_id)}"))
+
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        status: Optional[str] = None,
+        q: Optional[str] = None,
+        source: Optional[str] = None,
+        days: Optional[int] = None,
+    ) -> ListPage:
+        """``GET /v1/emails``, newest first. ``q`` searches the subject, ID, sender and recipients;
+        ``source`` is ``api`` or ``smtp``; ``days`` keeps emails from the last N days."""
+        query: Query = {"limit": limit, "offset": offset, "status": status, "q": q, "source": source, "days": days}
+        return cast(ListPage, self._t.request("GET", "/v1/emails", query=query))
+
+    def cancel(self, email_id: str) -> Email:
+        """A queued or scheduled email; fails with ``409 cannot_cancel`` once delivery started."""
+        return cast(Email, self._t.request("POST", f"/v1/emails/{_id(email_id)}/cancel"))
+
+
+class Domains(_Resource):
+    def create(self, params: CreateDomainParams) -> Domain:
+        return cast(Domain, self._t.request("POST", "/v1/domains", body=params))
+
+    def list(self, *, limit: Optional[int] = None, offset: Optional[int] = None) -> ListPage:
+        return cast(ListPage, self._t.request("GET", "/v1/domains", query={"limit": limit, "offset": offset}))
+
+    def get(self, domain_id: str) -> Domain:
+        return cast(Domain, self._t.request("GET", f"/v1/domains/{_id(domain_id)}"))
+
+    def verify(self, domain_id: str) -> DomainVerification:
+        """Checks the domain's DNS records now."""
+        return cast(DomainVerification, self._t.request("POST", f"/v1/domains/{_id(domain_id)}/verify"))
+
+    def update(self, domain_id: str, params: UpdateDomainParams) -> Domain:
+        """Turns open or click tracking on or off, or inbound email (``inbound_domain``, ``""`` for off)."""
+        return cast(Domain, self._t.request("PATCH", f"/v1/domains/{_id(domain_id)}", body=params))
+
+    def delete(self, domain_id: str) -> Deleted:
+        return cast(Deleted, self._t.request("DELETE", f"/v1/domains/{_id(domain_id)}"))
+
+
+class Templates(_Resource):
+    def create(self, params: CreateTemplateParams) -> Template:
+        return cast(Template, self._t.request("POST", "/v1/templates", body=params))
+
+    def list(self, *, limit: Optional[int] = None, offset: Optional[int] = None) -> ListPage:
+        return cast(ListPage, self._t.request("GET", "/v1/templates", query={"limit": limit, "offset": offset}))
+
+    def get(self, template_id: str) -> Template:
+        return cast(Template, self._t.request("GET", f"/v1/templates/{_id(template_id)}"))
+
+    def update(self, template_id: str, params: UpdateTemplateParams) -> Template:
+        return cast(Template, self._t.request("PATCH", f"/v1/templates/{_id(template_id)}", body=params))
+
+    def delete(self, template_id: str) -> Deleted:
+        return cast(Deleted, self._t.request("DELETE", f"/v1/templates/{_id(template_id)}"))
+
+
+class Files(_Resource):
+    def upload(self, params: UploadFileParams) -> FileObject:
+        """Uploads an attachment to reuse in many emails as ``{"file_id": …}``."""
+        return cast(FileObject, self._t.request("POST", "/v1/files", body=params))
+
+    def list(self, *, limit: Optional[int] = None, offset: Optional[int] = None) -> ListPage:
+        return cast(ListPage, self._t.request("GET", "/v1/files", query={"limit": limit, "offset": offset}))
+
+    def delete(self, file_id: str) -> Deleted:
+        return cast(Deleted, self._t.request("DELETE", f"/v1/files/{_id(file_id)}"))
+
+
+class Suppressions(_Resource):
+    def list(self, *, limit: Optional[int] = None, offset: Optional[int] = None) -> ListPage:
+        return cast(ListPage, self._t.request("GET", "/v1/suppressions", query={"limit": limit, "offset": offset}))
+
+    def create(self, params: CreateSuppressionParams) -> Suppression:
+        return cast(Suppression, self._t.request("POST", "/v1/suppressions", body=params))
+
+    def delete(self, suppression_id: str) -> Deleted:
+        """Removes a suppression (``sup_…``), so the address can be sent to again."""
+        return cast(Deleted, self._t.request("DELETE", f"/v1/suppressions/{_id(suppression_id)}"))
+
+
+class Webhooks(_Resource):
+    def create(self, params: CreateWebhookParams) -> Webhook:
+        """The response's ``signing_secret`` is the key for ``verify_signature``."""
+        return cast(Webhook, self._t.request("POST", "/v1/webhooks", body=params))
+
+    def list(self, *, limit: Optional[int] = None, offset: Optional[int] = None) -> ListPage:
+        return cast(ListPage, self._t.request("GET", "/v1/webhooks", query={"limit": limit, "offset": offset}))
+
+    def get(self, webhook_id: str) -> Webhook:
+        return cast(Webhook, self._t.request("GET", f"/v1/webhooks/{_id(webhook_id)}"))
+
+    def update(self, webhook_id: str, params: UpdateWebhookParams) -> Webhook:
+        return cast(Webhook, self._t.request("PATCH", f"/v1/webhooks/{_id(webhook_id)}", body=params))
+
+    def delete(self, webhook_id: str) -> Deleted:
+        return cast(Deleted, self._t.request("DELETE", f"/v1/webhooks/{_id(webhook_id)}"))
+
+    def test(self, webhook_id: str) -> WebhookDelivery:
+        """Sends a ``webhook.test`` event to the endpoint."""
+        return cast(WebhookDelivery, self._t.request("POST", f"/v1/webhooks/{_id(webhook_id)}/test"))
+
+    def list_event_types(self) -> Dict[str, List[str]]:
+        """``GET /v1/webhooks/events``: the event types an endpoint can subscribe to."""
+        return cast(Dict[str, List[str]], self._t.request("GET", "/v1/webhooks/events"))
+
+    def list_deliveries(
+        self, *, webhook_id: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> ListPage:
+        """Recent deliveries, optionally of one endpoint (``webhook_id``)."""
+        query: Query = {"webhook_id": webhook_id, "limit": limit, "offset": offset}
+        return cast(ListPage, self._t.request("GET", "/v1/webhooks/deliveries", query=query))
+
+    def replay_delivery(self, delivery_id: str) -> WebhookDelivery:
+        """Sends a delivery again, as a new delivery."""
+        return cast(WebhookDelivery, self._t.request("POST", f"/v1/webhooks/deliveries/{_id(delivery_id)}/replay"))
+
+    @staticmethod
+    def verify_signature(
+        raw_body: Union[str, bytes], header: Optional[str], secret: str, *, tolerance_seconds: int = 300
+    ) -> bool:
+        """Same as ``postilon.verify_webhook_signature``."""
+        return verify_webhook_signature(raw_body, header, secret, tolerance_seconds=tolerance_seconds)
+
+
+class Inbound(_Resource):
+    """Email received on an inbound domain (https://postilon.com/docs/inbound)."""
+
+    def list(self, *, q: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> ListPage:
+        """``GET /v1/inbound``, newest first; ``q`` searches the subject, sender and recipient."""
+        return cast(ListPage, self._t.request("GET", "/v1/inbound", query={"q": q, "limit": limit, "offset": offset}))
+
+    def get(self, inbound_id: str) -> InboundEmail:
+        """``GET /v1/inbound/{id}``, with its headers."""
+        return cast(InboundEmail, self._t.request("GET", f"/v1/inbound/{_id(inbound_id)}"))
+
+    def attachment(self, inbound_id: str, index: int) -> bytes:
+        """Attachment ``index`` (from 0, as in ``attachments``), as bytes."""
+        return cast(bytes, self._t.request("GET", f"/v1/inbound/{_id(inbound_id)}/attachments/{int(index)}", raw=True))
+
+    def raw(self, inbound_id: str) -> bytes:
+        """The message as received (RFC 5322), as bytes for ``email.message_from_bytes``."""
+        return cast(bytes, self._t.request("GET", f"/v1/inbound/{_id(inbound_id)}/raw", raw=True))
+
+
+__all__ = ["Postilon", "Emails", "Domains", "Templates", "Files", "Suppressions", "Webhooks", "Inbound"]

postilon/_errors.py

@@ -0,0 +1,54 @@
+import json
+from typing import Any, Optional, Protocol
+
+
+class _Headers(Protocol):
+    def get(self, name: str, /) -> Any: ...
+
+
+class PostilonError(Exception):
+    """An error answered by the Postilon API: ``{"error": {"code", "message"}}`` with an HTTP status.
+
+    See https://postilon.com/docs/errors for the codes. Network failures are not wrapped: they
+    raise the ``urllib.error.URLError`` (or ``OSError``) that ``urllib`` raised.
+    """
+
+    status: int
+    """HTTP status, such as 403."""
+    code: str
+    """Error code, such as ``domain_not_verified``; ``http_error`` when the body was not a Postilon error."""
+    message: str
+    rate_limit_reset: Optional[int]
+    """For ``429 rate_limit_exceeded``: when the rate limit window resets, in Unix seconds
+    (the ``X-RateLimit-Reset`` header). Retry after this time."""
+
+    def __init__(self, status: int, code: str, message: str, rate_limit_reset: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.rate_limit_reset = rate_limit_reset
+
+    def __repr__(self) -> str:
+        return f"PostilonError(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+def error_from_response(status: int, headers: _Headers, body: bytes) -> PostilonError:
+    """Builds the error for a non-2xx response from its status, headers and body."""
+    code, message = "http_error", f"HTTP {status}"
+    try:
+        err = json.loads(body.decode("utf-8")).get("error")
+        if isinstance(err, dict) and isinstance(err.get("code"), str):
+            code = err["code"]
+            if isinstance(err.get("message"), str) and err["message"]:
+                message = err["message"]
+    except (ValueError, AttributeError):
+        pass  # Not JSON (a proxy's error page, say): keep the generic code and message.
+    reset = None
+    if status == 429 and code == "rate_limit_exceeded":
+        try:
+            n = int(headers.get("X-RateLimit-Reset") or "")
+            reset = n if n > 0 else None
+        except ValueError:
+            pass
+    return PostilonError(status, code, message, reset)

postilon/_signature.py

@@ -0,0 +1,44 @@
+import hashlib
+import hmac
+import re
+import time
+from typing import Optional, Union
+
+_HEX64 = re.compile(r"^[0-9a-fA-F]{64}$")
+_DIGITS = re.compile(r"^\d+$")
+
+
+def verify_webhook_signature(
+    raw_body: Union[str, bytes],
+    header: Optional[str],
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+) -> bool:
+    """Checks the ``X-Postilon-Signature`` header of a webhook request.
+
+    The header is ``t=<unix>,v1=<hex>``, where ``v1`` is the HMAC-SHA256 of ``"<t>.<raw body>"``
+    keyed with the endpoint's signing secret. Pass the body exactly as received, before any JSON
+    parsing. Returns False, never raises, for a missing or malformed header, a wrong signature or
+    a timestamp more than ``tolerance_seconds`` away from now.
+    """
+    if not isinstance(header, str) or not secret:
+        return False
+    timestamp = None
+    signatures = []
+    for part in header.split(","):
+        key, eq, value = part.partition("=")
+        if not eq:
+            continue
+        key, value = key.strip(), value.strip()
+        if key == "t":
+            timestamp = value
+        elif key == "v1" and _HEX64.match(value):
+            signatures.append(bytes.fromhex(value))
+    if not timestamp or not _DIGITS.match(timestamp) or not signatures:
+        return False
+    if abs(time.time() - int(timestamp)) > tolerance_seconds:
+        return False
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else bytes(raw_body)
+    expected = hmac.new(secret.encode("utf-8"), timestamp.encode("ascii") + b"." + body, hashlib.sha256).digest()
+    return any(hmac.compare_digest(sig, expected) for sig in signatures)

postilon/types.py

@@ -0,0 +1,401 @@
+"""Request and response shapes of the Postilon API (https://postilon.com/docs/api).
+
+Every shape is a plain ``dict`` at runtime; these ``TypedDict`` definitions are for type
+checkers and editors. Field names are the API's own, in snake_case, so a field named ``from``
+uses the functional ``TypedDict`` syntax. Times are RFC 3339 strings in UTC.
+"""
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+# Lists
+
+
+class ListPage(TypedDict):
+    """One page of a list. Ask for the next with ``offset + count`` while ``has_more`` is true."""
+
+    object: Literal["list"]
+    data: List[Dict[str, Any]]
+    count: int
+    total: int
+    has_more: bool
+
+
+class Deleted(TypedDict):
+    deleted: bool
+
+
+# Emails
+
+EmailStatus = Literal[
+    "scheduled", "queued", "sent", "delivered", "opened", "clicked", "bounced", "complained", "suppressed", "failed", "canceled"
+]
+
+
+class Tag(TypedDict):
+    name: str
+    value: str
+
+
+class InlineAttachment(TypedDict):
+    """A file sent inline, its ``content`` encoded in Base64."""
+
+    filename: str
+    content_type: str
+    content: str
+
+
+class _FileAttachmentBase(TypedDict):
+    file_id: str
+
+
+class FileAttachment(_FileAttachmentBase, total=False):
+    """A file uploaded earlier with ``files.upload``."""
+
+    filename: str
+    content_type: str
+
+
+Attachment = Union[InlineAttachment, FileAttachment]
+
+_SendEmailRequired = TypedDict("_SendEmailRequired", {"from": str, "to": Union[str, List[str]]})
+
+
+class SendEmailParams(_SendEmailRequired, total=False):
+    """``from`` is ``hello@acme.com`` or ``Acme <hello@acme.com>``; with a live key its domain must
+    be verified. ``subject`` is required unless ``template_id`` is set."""
+
+    cc: Union[str, List[str]]
+    bcc: Union[str, List[str]]
+    subject: str
+    html: str
+    text: str
+    reply_to: str
+    template_id: str
+    variables: Dict[str, str]
+    attachments: List[Attachment]
+    headers: Dict[str, str]
+    tags: List[Tag]
+    scheduled_at: str
+
+
+SendEmailResponse = TypedDict(
+    "SendEmailResponse",
+    {
+        "id": str,
+        "status": Literal["queued", "scheduled"],
+        "from": str,
+        "to": List[str],
+        "environment": Literal["live", "test"],
+        "credits_used": int,
+        "scheduled_at": Optional[str],
+        "created_at": str,
+    },
+)
+
+
+class BatchRecipient(TypedDict, total=False):
+    to: str
+    variables: Dict[str, str]
+
+
+_SendBatchRequired = TypedDict("_SendBatchRequired", {"from": str, "batch": List[BatchRecipient]})
+
+
+class SendBatchParams(_SendBatchRequired, total=False):
+    """``batch`` holds 1 to 100 emails, each with its own recipient and variables."""
+
+    subject: str
+    html: str
+    text: str
+    template_id: str
+
+
+class SendBatchResponse(TypedDict):
+    object: Literal["batch_result"]
+    count: int
+    data: List[Dict[str, str]]
+
+
+class EmailEvent(TypedDict, total=False):
+    id: str
+    email_id: str
+    event_type: str
+    recipient: str
+    metadata: Dict[str, str]
+    occurred_at: str
+
+
+Email = TypedDict(
+    "Email",
+    {
+        "id": str,
+        "workspace_id": str,
+        "from": str,
+        "to": List[str],
+        "cc": List[str],
+        "bcc": List[str],
+        "reply_to": str,
+        "subject": str,
+        "html": str,
+        "text": str,
+        "attachments": List[Attachment],
+        "variables": Dict[str, str],
+        "headers": Dict[str, str],
+        "template_id": str,
+        "tags": List[Tag],
+        "status": EmailStatus,
+        "environment": Literal["live", "test"],
+        "transport": Literal["rest_api", "rest_api_batch", "smtp_relay"],
+        "source": Literal["api", "smtp"],
+        "credits_used": int,
+        "dkim_signed": bool,
+        "events": List[EmailEvent],
+        "scheduled_at": str,
+        "sent_at": str,
+        "delivered_at": str,
+        "created_at": str,
+        "content_purged_at": str,
+    },
+    total=False,
+)
+
+# Domains
+
+
+class DnsRecord(TypedDict, total=False):
+    type: str
+    name: str
+    value: str
+    priority: int
+    purpose: str
+    status: Literal["pending", "verified"]
+    required: bool
+    """False for a recommended record (DMARC), which is not needed to verify the domain."""
+
+
+class Domain(TypedDict, total=False):
+    id: str
+    workspace_id: str
+    domain_name: str
+    status: Literal["pending", "verified", "failed"]
+    dkim_selector: str
+    dkim_public_key: str
+    dmarc_record: str
+    return_path_domain: str
+    dns_records: List[DnsRecord]
+    open_tracking_enabled: bool
+    click_tracking_enabled: bool
+    inbound_domain: str
+    """The domain (or its subdomain) that receives email; empty while inbound is off."""
+    inbound_record: DnsRecord
+    """The MX record the inbound domain needs; on a single domain while inbound is on."""
+    verified_at: str
+    created_at: str
+
+
+class CreateDomainParams(TypedDict):
+    domain_name: str
+
+
+class UpdateDomainParams(TypedDict, total=False):
+    open_tracking_enabled: bool
+    click_tracking_enabled: bool
+    inbound_domain: str
+    """Receive email on this domain or a subdomain of it; ``""`` turns inbound off."""
+
+
+class DomainVerification(TypedDict):
+    domain: Domain
+    dns_verification: Dict[str, Any]
+
+
+# Templates
+
+
+class Template(TypedDict, total=False):
+    id: str
+    workspace_id: str
+    name: str
+    subject_template: str
+    html_template: str
+    text_template: str
+    variables: List[str]
+    updated_at: str
+    created_at: str
+
+
+class _CreateTemplateRequired(TypedDict):
+    name: str
+
+
+class CreateTemplateParams(_CreateTemplateRequired, total=False):
+    subject_template: str
+    html_template: str
+    text_template: str
+    variables: List[str]
+
+
+class UpdateTemplateParams(TypedDict, total=False):
+    """Fields left out (or empty) keep their current value."""
+
+    name: str
+    subject_template: str
+    html_template: str
+    text_template: str
+    variables: List[str]
+
+
+# Files
+
+
+class _UploadFileRequired(TypedDict):
+    filename: str
+    content: str
+    """The file encoded in Base64, such as ``base64.b64encode(data).decode()``."""
+
+
+class UploadFileParams(_UploadFileRequired, total=False):
+    content_type: str
+
+
+class FileObject(TypedDict, total=False):
+    id: str
+    workspace_id: str
+    filename: str
+    content_type: str
+    size_bytes: int
+    expires_at: str
+    created_at: str
+
+
+# Suppressions
+
+
+class Suppression(TypedDict, total=False):
+    id: str
+    workspace_id: str
+    email_address: str
+    reason: Literal["hard_bounce", "complaint", "unsubscribe", "manual"]
+    source_email_id: str
+    created_at: str
+
+
+class CreateSuppressionParams(TypedDict):
+    email_address: str
+
+
+# Inbound
+
+AuthResult = str
+"""An SPF, DKIM or DMARC result: ``pass``, ``fail``, ``softfail``, ``neutral``, ``none``,
+``temperror`` or ``permerror``."""
+
+
+class InboundAttachment(TypedDict, total=False):
+    filename: str
+    content_type: str
+    size: int
+    """Bytes."""
+    content_id: str
+    """Set for an inline image the HTML shows as ``cid:<content_id>``."""
+
+
+InboundEmail = TypedDict(
+    "InboundEmail",
+    {
+        "id": str,
+        "workspace_id": str,
+        "domain_id": str,
+        "envelope_from": str,
+        "recipient": str,
+        "remote_ip": str,
+        "from": str,
+        "to": List[str],
+        "cc": List[str],
+        "reply_to": str,
+        "subject": str,
+        "message_id": str,
+        "in_reply_to": str,
+        "references": str,
+        "text": str,
+        "html": str,
+        "headers": Dict[str, List[str]],
+        "attachments": List[InboundAttachment],
+        "size_bytes": int,
+        "spf": AuthResult,
+        "dkim": AuthResult,
+        "dmarc": AuthResult,
+        "spam": bool,
+        "credits_used": int,
+        "content_purged_at": str,
+        "created_at": str,
+    },
+    total=False,
+)
+"""One inbound email per recipient; ``headers`` only from ``inbound.get``, and the content is
+deleted 30 days after it arrived (``content_purged_at``)."""
+
+# Webhooks
+
+WebhookEventType = Literal[
+    "email.sent", "email.delivered", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.failed", "email.received"
+]
+
+
+class Webhook(TypedDict, total=False):
+    id: str
+    workspace_id: str
+    url: str
+    description: str
+    signing_secret: str
+    """``whsec_…``: the key for ``verify_signature``."""
+    subscribed_events: List[WebhookEventType]
+    is_active: bool
+    created_at: str
+
+
+class _CreateWebhookRequired(TypedDict):
+    url: str
+    """HTTPS and reachable from the internet."""
+
+
+class CreateWebhookParams(_CreateWebhookRequired, total=False):
+    description: str
+    subscribed_events: List[WebhookEventType]
+    """Leave out to receive every event."""
+
+
+class UpdateWebhookParams(TypedDict, total=False):
+    url: str
+    description: str
+    subscribed_events: List[WebhookEventType]
+    is_active: bool
+
+
+class WebhookDelivery(TypedDict, total=False):
+    id: str
+    webhook_id: str
+    workspace_id: str
+    url: str
+    event_type: str
+    payload: str
+    """The JSON body that was sent, as a string."""
+    signature: str
+    response_status: int
+    attempt_count: int
+    status: Literal["pending", "delivered", "failed"]
+    next_attempt_at: str
+    last_error: str
+    created_at: str
+
+
+class WebhookEvent(TypedDict):
+    """The JSON body Postilon posts to a webhook endpoint. ``data`` depends on ``type``: an email
+    event carries ``email_id``, ``recipient`` and ``status``; ``email.received`` carries the
+    received email (``inbound_id``, ``text``, ``html``, ``attachments``, ``auth``, ``spam`` …)."""
+
+    id: str
+    type: str
+    created_at: str
+    workspace_id: str
+    data: Dict[str, Any]

postilon-1.0.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: postilon
+Version: 1.0.0
+Summary: Python SDK for the Postilon transactional email API
+Project-URL: Homepage, https://postilon.com
+Project-URL: Documentation, https://postilon.com/docs
+Project-URL: Source, https://github.com/postilon/postilon-python
+Project-URL: Issues, https://github.com/postilon/postilon-python/issues
+Author-email: "Kulina Pte. Ltd." <hello@postilon.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email,postilon,smtp,transactional-email,webhooks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# postilon
+
+Python client for the [Postilon](https://postilon.com) transactional email API. Typed, no dependencies, Python 3.9 or later.
+
+Full API documentation: [postilon.com/docs](https://postilon.com/docs).
+
+## Install
+
+```bash
+pip install postilon
+```
+
+## Send an email
+
+Create an API key in the dashboard under **API Keys**, and keep it in an environment variable.
+
+```python
+import os
+from postilon import Postilon
+
+postilon = Postilon(os.environ["POSTILON_API_KEY"])
+
+email = postilon.emails.send({
+    "from": "Acme <hello@acme.com>",
+    "to": "jane@example.com",
+    "subject": "Your sign-in code",
+    "html": "<p>Your code is <strong>482913</strong>.</p>",
+    "text": "Your code is 482913.",
+})
+# {"id": "msg_…", "status": "queued", …}
+```
+
+Requests are plain dicts with the API's own field names (`from` is a Python keyword, so there are no keyword arguments for them), and every method returns the parsed JSON response as a dict. `send` takes every field of [`POST /v1/emails`](https://postilon.com/docs/sending): `cc`, `bcc`, `reply_to`, `headers`, `tags`, `attachments` (Base64 `content`, or a `file_id` from `postilon.files.upload`), `template_id` with `variables`, and `scheduled_at`. `postilon.types` has `TypedDict` definitions for type checkers.
+
+The client also covers `emails.send_batch`, `get`, `list` and `cancel`, and `domains`, `templates`, `files`, `suppressions`, `webhooks` and `inbound`. `Postilon(key, base_url=…, timeout=30.0)` changes the API address or the timeout in seconds.
+
+## Test keys
+
+`ps_test_…` keys are for development: emails are accepted, rendered and reported like real ones, but nothing is delivered and no credits are used, and any `from` address works. `ps_live_…` keys send real mail from a [verified domain](https://postilon.com/docs/domains). The SDK treats both the same.
+
+## Idempotency
+
+Pass an idempotency key, such as the order or event ID the email is for, so a retried request never sends twice. It is sent as the `Idempotency-Key` header:
+
+```python
+postilon.emails.send(
+    {"from": "billing@acme.com", "to": "jane@example.com", "subject": "Receipt for order #123", "text": "Thanks."},
+    idempotency_key="receipt-order-123",
+)
+```
+
+A retry with the same key and body returns the original response. The same key with a different body fails with `409 idempotency_key_reused`, so use one key per email.
+
+## Errors
+
+When the API answers with an error, the call raises `PostilonError` with the HTTP `status`, the `code` and the `message` ([list of codes](https://postilon.com/docs/errors)). Network failures raise the `urllib.error.URLError` that `urllib` raised.
+
+```python
+from postilon import PostilonError
+
+try:
+    postilon.emails.send({"from": "hello@acme.com", "to": "jane@example.com", "subject": "Hi", "text": "Hi"})
+except PostilonError as err:
+    if err.code == "rate_limit_exceeded":
+        ...  # err.rate_limit_reset: when the window resets, in Unix seconds (X-RateLimit-Reset)
+    else:
+        print(err.status, err.code, err.message)  # 403 domain_not_verified …
+```
+
+A workspace can make 100 requests per second; use `emails.send_batch` for many emails at once. `429 daily_limit_reached` means the daily sending limit is reached, and retrying within the second will not help. An error response that is not JSON (from a proxy, say) gets the code `http_error`.
+
+## Pagination
+
+Lists return `{"object": "list", "data", "count", "total", "has_more"}` and take `limit` (default 100, at most 1000) and `offset`, newest first:
+
+```python
+offset = 0
+while True:
+    page = postilon.emails.list(status="bounced", limit=100, offset=offset)
+    for email in page["data"]:
+        print(email["id"], email["to"])
+    if not page["has_more"]:
+        break
+    offset += page["count"]
+```
+
+## Verify webhooks
+
+Each webhook request carries `X-Postilon-Signature: t=<unix>,v1=<hex>`. Verify it against the **raw** body, before any JSON parsing, with the endpoint's signing secret (`whsec_…`, returned when the endpoint is created). Signatures older than 5 minutes are refused; change that with `tolerance_seconds=`.
+
+```python
+import json
+import os
+from flask import Flask, request
+from postilon import verify_webhook_signature
+
+app = Flask(__name__)
+
+@app.post("/webhooks/postilon")
+def postilon_webhook():
+    body = request.get_data()  # the raw bytes
+    if not verify_webhook_signature(body, request.headers.get("X-Postilon-Signature"), os.environ["POSTILON_WEBHOOK_SECRET"]):
+        return "", 400
+    event = json.loads(body)
+    if event["type"] == "email.bounced":
+        ...  # event["data"]["recipient"] bounced
+    return "", 200
+```
+
+`postilon.webhooks.verify_signature(...)` is the same function. Answer with a `2xx` within 8 seconds and do slow work afterwards. Events can arrive more than once and out of order, so use the event `id` to ignore duplicates. See [Webhooks](https://postilon.com/docs/webhooks).
+
+## Receive email
+
+Turn on inbound for a verified domain (or a subdomain of it), and add the MX record it returns:
+
+```python
+domain = postilon.domains.update("dom_…", {"inbound_domain": "reply.acme.com"})
+# domain["inbound_record"]: {"type": "MX", "name": "reply.acme.com", "value": "inbound.postilon.com", "priority": 10, …}
+```
+
+Each message then reaches your webhooks as `email.received`, with its text and HTML (up to 256 KB), attachment list, SPF, DKIM and DMARC results and a `spam` flag. Read received email with `postilon.inbound.list`, `get`, `attachment(id, index)` and `raw(id)`; the last two return `bytes` (`email.message_from_bytes` parses the raw message). See [Inbound email](https://postilon.com/docs/inbound).
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

postilon-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+postilon/__init__.py,sha256=FW4m2LE27hfwwMg-qrca9Ysmpft5qWO1TcZ3mK3sfw4,509
+postilon/_client.py,sha256=pu_WqPyDc3tN-QpNs4IZiKmrNC_7lOd7WW1qy56urbc,12226
+postilon/_errors.py,sha256=46hS5hIDNKKTwsQFXJWkZViK_ma3EXveWYzxIajABi4,2170
+postilon/_signature.py,sha256=Zlpj3UkJDsWwkRRG0oLu4RvCcKaQVCpjDLE3fJDiJwU,1639
+postilon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+postilon/types.py,sha256=i2ZOo4CFLjELNcVCbNfUqpj1U5NRUIHlXEWwMwDRjSI,9626
+postilon-1.0.0.dist-info/METADATA,sha256=cNcuihwUcxmFx_6W2YTxSTueZW0zQ_Hv98n_UppySiU,6579
+postilon-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+postilon-1.0.0.dist-info/licenses/LICENSE,sha256=lYZN5_OMo6MvDAbxXk0W0RtH4U572Ytb01OA-X6090c,1073
+postilon-1.0.0.dist-info/RECORD,,

postilon-1.0.0.dist-info/WHEEL

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

postilon-1.0.0.dist-info/licenses/LICENSE

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