postilon 1.0.0__tar.gz

postilon-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/

postilon-1.0.0/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.

postilon-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,125 @@
+# 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/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "postilon"
+version = "1.0.0"
+description = "Python SDK for the Postilon transactional email API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kulina Pte. Ltd.", email = "hello@postilon.com" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["postilon", "email", "transactional-email", "smtp", "webhooks"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Email",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://postilon.com"
+Documentation = "https://postilon.com/docs"
+Source = "https://github.com/postilon/postilon-python"
+Issues = "https://github.com/postilon/postilon-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/postilon"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/postilon", "tests", "README.md", "LICENSE"]

postilon-1.0.0/src/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-1.0.0/src/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"]