sendclipper 0.1.0__py3-none-any.whl

sendclipper/_errors.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Optional
+
+__all__ = [
+    "SendClipperError",
+    "SendClipperApiError",
+    "SendClipperConnectionError",
+    "WebhookVerificationError",
+]
+
+
+class SendClipperError(Exception):
+    """Base class for everything this SDK raises on purpose."""
+
+
+class SendClipperApiError(SendClipperError):
+    """
+    The API answered with a non-2xx status. ``code`` is the API's own
+    machine-readable reason (``domain_not_verified``, ``template_variables_missing``,
+    ``rate_limited``, ...) and is the field to branch on; ``message`` is a
+    sentence meant for a person.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        detail: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.detail = detail
+        self.headers: dict[str, str] = dict(headers or {})
+
+    def __repr__(self) -> str:
+        return f"SendClipperApiError(status={self.status!r}, code={self.code!r}, message={self.message!r})"
+
+
+class SendClipperConnectionError(SendClipperError):
+    """The request never got an answer: DNS, TLS, a reset socket or the timeout."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.__cause__ = cause
+
+
+class WebhookVerificationError(SendClipperError):
+    """
+    ``verify_webhook()`` refused a delivery. ``reason`` says which check failed:
+    ``missing_header``, ``malformed_header``, ``timestamp_out_of_tolerance``,
+    ``signature_mismatch`` or ``invalid_payload``.
+    """
+
+    def __init__(self, reason: str, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.message = message
+
+
+def to_api_error(status: int, text: str, headers: Optional[Mapping[str, str]] = None) -> SendClipperApiError:
+    """
+    The API answers refusals in two shapes: the house envelope
+    ``{ error: { code, message, detail? } }`` and Nest's default
+    ``{ statusCode, message: str | list[str], error }`` (request validation).
+    """
+    try:
+        parsed: Any = json.loads(text)
+    except ValueError:
+        parsed = None
+    obj: dict[str, Any] = parsed if isinstance(parsed, dict) else {}
+
+    env = obj.get("error")
+    if isinstance(env, dict):
+        detail = env.get("detail", env.get("details"))
+        return SendClipperApiError(
+            status,
+            str(env.get("code") or _code_for_status(status)),
+            str(env.get("message") or f"HTTP {status}"),
+            detail,
+            headers,
+        )
+
+    msg = obj.get("message")
+    if isinstance(msg, dict) and isinstance(msg.get("error"), dict):
+        inner = msg["error"]
+        return SendClipperApiError(
+            status,
+            str(inner.get("code") or _code_for_status(status)),
+            str(inner.get("message") or f"HTTP {status}"),
+            inner.get("detail"),
+            headers,
+        )
+    if isinstance(msg, list):
+        return SendClipperApiError(status, "validation_failed", "; ".join(str(m) for m in msg), msg, headers)
+    if isinstance(msg, str):
+        return SendClipperApiError(status, _code_for_status(status), msg, None, headers)
+
+    snippet = text.strip()[:300]
+    return SendClipperApiError(status, _code_for_status(status), snippet or f"HTTP {status}", None, headers)
+
+
+def _code_for_status(status: int) -> str:
+    return {
+        400: "bad_request",
+        401: "unauthorized",
+        403: "forbidden",
+        404: "not_found",
+        409: "conflict",
+        413: "payload_too_large",
+        429: "rate_limited",
+    }.get(status, f"http_{status}")

sendclipper/_version.py

@@ -0,0 +1,3 @@
+"""Kept equal to the release tag by the publish workflow."""
+
+__version__ = "0.1.0"

sendclipper/_webhooks.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Iterable, List, Mapping, Optional, Tuple, Union
+
+from ._errors import WebhookVerificationError
+from .types import WebhookEvent
+
+__all__ = [
+    "WEBHOOK_TOLERANCE_SECONDS",
+    "SIGNATURE_HEADER",
+    "verify_webhook",
+    "sign_payload",
+    "signature_header",
+    "parse_signature_header",
+]
+
+#: SendClipper's documented tolerance: five minutes.
+WEBHOOK_TOLERANCE_SECONDS = 300
+
+SIGNATURE_HEADER = "x-sendclipper-signature-v2"
+
+#: The request's headers (any mapping: Flask, Django, Starlette, a dict), raw
+#: ASGI ``(name, value)`` pairs, or just the ``X-SendClipper-Signature-V2`` value.
+HeaderSource = Union[str, Mapping[str, Any], Iterable[Tuple[Any, Any]]]
+
+Payload = Union[str, bytes, bytearray, memoryview]
+
+
+def verify_webhook(
+    payload: Payload,
+    headers: HeaderSource,
+    secret: str,
+    *,
+    tolerance_seconds: int = WEBHOOK_TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> WebhookEvent:
+    """
+    Verify a webhook delivery and return its parsed event.
+
+    ``payload`` is the body EXACTLY as received (``request.get_data()`` in
+    Flask, ``request.body`` in Django, ``await request.body()`` in FastAPI),
+    never re-serialised JSON.
+
+    SendClipper signs ``f"{timestamp}.{raw_body}"`` with HMAC-SHA256 and sends
+    ``X-SendClipper-Signature-V2: t=<seconds>,v1=<hex>[,v1=<hex>]``. During a
+    secret rotation there are two ``v1=`` values; any match is accepted.
+
+    Raises ``WebhookVerificationError`` when any check fails.
+    """
+    if not secret:
+        raise WebhookVerificationError("missing_header", "No webhook signing secret was given.")
+    if isinstance(payload, str):
+        raw = payload.encode("utf-8")
+    elif isinstance(payload, (bytes, bytearray, memoryview)):
+        raw = bytes(payload)
+    else:
+        raise WebhookVerificationError(
+            "invalid_payload",
+            "payload must be the raw request body (str or bytes), not parsed JSON. "
+            "Use request.get_data() in Flask, request.body in Django or await request.body() in FastAPI.",
+        )
+
+    header = _signature_header_of(headers)
+    if not header:
+        raise WebhookVerificationError("missing_header", "The request carries no X-SendClipper-Signature-V2 header.")
+    timestamp, signatures = parse_signature_header(header)
+    if timestamp is None or not signatures:
+        raise WebhookVerificationError("malformed_header", "X-SendClipper-Signature-V2 has no t= or no v1= value.")
+
+    current = int(time.time()) if now is None else int(now)
+    drift = abs(current - timestamp)
+    if drift > tolerance_seconds:
+        raise WebhookVerificationError(
+            "timestamp_out_of_tolerance",
+            f"The delivery was signed {drift} s from now, outside the {tolerance_seconds} s tolerance.",
+        )
+
+    expected = _sign(secret, timestamp, raw)
+    # ANY match, and every candidate is compared: a rotation sends two.
+    matched = False
+    for candidate in signatures:
+        if hmac.compare_digest(expected, candidate.encode("utf-8")):
+            matched = True
+    if not matched:
+        raise WebhookVerificationError("signature_mismatch", "The signature does not match this secret and body.")
+
+    try:
+        event: WebhookEvent = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        raise WebhookVerificationError("invalid_payload", "The signed body is not JSON.") from None
+    return event
+
+
+def sign_payload(secret: str, timestamp: int, raw_body: Union[str, bytes]) -> str:
+    """``hex(HMAC-SHA256(secret, f"{timestamp}.{raw_body}"))``. Exported for tests of your own handler."""
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    return _sign(secret, timestamp, body).decode("ascii")
+
+
+def signature_header(secret: str, raw_body: Union[str, bytes], timestamp: Optional[int] = None) -> str:
+    """Build a valid header for a body, e.g. to test your endpoint locally."""
+    t = int(time.time()) if timestamp is None else timestamp
+    return f"t={t},v1={sign_payload(secret, t, raw_body)}"
+
+
+def parse_signature_header(header: str) -> Tuple[Optional[int], List[str]]:
+    """``(timestamp, [signatures])`` from ``t=<seconds>,v1=<hex>[,v1=<hex>]``."""
+    timestamp: Optional[int] = None
+    signatures: List[str] = []
+    for part in header.split(","):
+        key, eq, value = part.partition("=")
+        if not eq:
+            continue
+        key, value = key.strip(), value.strip()
+        if key == "t" and value.isdigit() and value.isascii():
+            timestamp = int(value)
+        elif key == "v1" and value:
+            signatures.append(value)
+    return timestamp, signatures
+
+
+def _sign(secret: str, timestamp: int, raw: bytes) -> bytes:
+    return hmac.new(secret.encode("utf-8"), f"{timestamp}.".encode("ascii") + raw, hashlib.sha256).hexdigest().encode("ascii")
+
+
+def _signature_header_of(source: HeaderSource) -> Optional[str]:
+    if isinstance(source, str):
+        return source
+    if isinstance(source, Mapping):
+        items: Iterable[Tuple[Any, Any]] = source.items()
+    else:
+        items = source
+    found: List[str] = []
+    for k, v in items:
+        name = k.decode("latin-1") if isinstance(k, (bytes, bytearray)) else str(k)
+        # Django's request.META spells it HTTP_X_SENDCLIPPER_SIGNATURE_V2.
+        normalised = name.lower().replace("_", "-")
+        if normalised in (SIGNATURE_HEADER, "http-" + SIGNATURE_HEADER):
+            if isinstance(v, (list, tuple)):
+                found.extend(str(x) for x in v)
+            else:
+                found.append(v.decode("latin-1") if isinstance(v, (bytes, bytearray)) else str(v))
+    return ",".join(found) if found else None

sendclipper/resources/__init__.py

@@ -0,0 +1 @@
+"""One class per API resource. Reach them through ``SendClipper``: ``sc.emails``, ``sc.domains``, ..."""

sendclipper/resources/_base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .._core import HttpClient, RequestOptions
+
+__all__ = ["Resource", "Unpack", "RequestOptions"]
+
+
+class Resource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http

sendclipper/resources/audience.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Dict, Iterator, List, Optional, Tuple, cast
+
+from .._core import Result, multipart, seg, strip_none
+from ._base import Resource
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .._core import RequestOptions
+    from ..types import (
+        AudienceList,
+        Contact,
+        ContactList,
+        CreateContactParams,
+        CreateSuppressionParams,
+        ExportContactsParams,
+        ImportContactsParams,
+        ListContactsParams,
+        ListSuppressionsParams,
+        PreviewContactsParams,
+        Suppression,
+        SuppressionCreated,
+        SuppressionList,
+    )
+
+
+class Contacts(Resource):
+    def list(self, params: Optional[ListContactsParams] = None, **options: Unpack[RequestOptions]) -> Result[ContactList]:
+        return self._http.call("GET", "/contacts", query=strip_none(params), **options)
+
+    def iterate(self, params: Optional[ListContactsParams] = None, **options: Unpack[RequestOptions]) -> Iterator[Contact]:
+        """Every contact, page after page. Raises ``SendClipperApiError`` on a refusal."""
+        query: Dict[str, Any] = strip_none(params)
+        page_size = int(query.get("pageSize") or 200)
+        page = 1
+        while True:
+            res = self.list(cast("ListContactsParams", {**query, "page": page, "pageSize": page_size}), **options).unwrap()
+            yield from res["items"]
+            if page >= res["totalPages"] or not res["items"]:
+                return
+            page += 1
+
+    def create(self, params: CreateContactParams, **options: Unpack[RequestOptions]) -> Result[Contact]:
+        return self._http.call("POST", "/contacts", body=dict(params), **options)
+
+    def import_(self, params: ImportContactsParams, **options: Unpack[RequestOptions]) -> Result[Dict[str, Any]]:
+        """
+        Import a CSV or vCard file. Importing never suppresses anyone. Named
+        ``import_`` because ``import`` is a Python keyword.
+        """
+        return self._http.call("POST", "/contacts/import", form=_import_form(params), **options)
+
+    def import_preview(self, params: PreviewContactsParams, **options: Unpack[RequestOptions]) -> Result[Dict[str, Any]]:
+        """What an import would do, without importing."""
+        return self._http.call("POST", "/contacts/import/preview", form=_import_form(params), **options)
+
+    def export(self, params: Optional[ExportContactsParams] = None, **options: Unpack[RequestOptions]) -> Result[str]:
+        """Every contact as CSV (re-importable) or vCard 4.0 (``{"format": "vcf"}``)."""
+        return self._http.call("GET", "/contacts/export", query=strip_none(params), as_="text", **options)
+
+
+class Audiences(Resource):
+    def list(self, **options: Unpack[RequestOptions]) -> Result[AudienceList]:
+        return self._http.call("GET", "/audiences", **options)
+
+
+class Suppressions(Resource):
+    def list(self, params: Optional[ListSuppressionsParams] = None, **options: Unpack[RequestOptions]) -> Result[SuppressionList]:
+        return self._http.call("GET", "/suppressions", query=strip_none(params), **options)
+
+    def iterate(self, params: Optional[ListSuppressionsParams] = None, **options: Unpack[RequestOptions]) -> Iterator[Suppression]:
+        query: Dict[str, Any] = strip_none(params)
+        while True:
+            res = self.list(query, **options).unwrap()  # type: ignore[arg-type]
+            yield from res["data"]
+            if not res["page"]["hasMore"] or not res["page"]["cursor"]:
+                return
+            query = {**query, "cursor": res["page"]["cursor"]}
+
+    def create(self, params: CreateSuppressionParams, **options: Unpack[RequestOptions]) -> Result[SuppressionCreated]:
+        """
+        Stop all mail to an address (reason ``manual``). ``created`` is ``False``
+        when the address was already suppressed; ``row`` is the entry either way.
+        """
+        return self._http.call("POST", "/suppressions", body=dict(params), **options)
+
+    def remove(self, id: str, reason: str, **options: Unpack[RequestOptions]) -> Result[Dict[str, Any]]:
+        """
+        Lift a suppression. ``reason`` (10+ characters) is recorded. Complaint and
+        provider suppressions cannot be removed (``suppression_not_removable``).
+        """
+        return self._http.call("DELETE", f"/suppressions/{seg(id)}", body={"reason": reason}, **options)
+
+    def export(self, params: Optional[ListSuppressionsParams] = None, **options: Unpack[RequestOptions]) -> Result[str]:
+        """The list as CSV."""
+        query = {k: v for k, v in strip_none(params).items() if k not in ("cursor", "limit")}
+        return self._http.call("GET", "/suppressions/export", query=query, as_="text", **options)
+
+
+def _import_form(params: Any) -> Tuple[bytes, str]:
+    name = params.get("filename") or "contacts.csv"
+    ctype = "text/vcard" if name.lower().endswith(".vcf") else "text/csv"
+    data = params["file"]
+    content = data.encode("utf-8") if isinstance(data, str) else bytes(data)
+    fields: List[Tuple[str, str]] = []
+    if params.get("audienceId"):
+        fields.append(("audienceId", params["audienceId"]))
+    if params.get("newAudience"):
+        fields.append(("newAudience", params["newAudience"]))
+    if params.get("createAudiences") is not None:
+        fields.append(("createAudiences", "true" if params["createAudiences"] else "false"))
+    if params.get("onDuplicate"):
+        fields.append(("onDuplicate", params["onDuplicate"]))
+    if params.get("mapping"):
+        fields.append(("mapping", json.dumps(params["mapping"])))
+    return multipart(fields, [("file", name, ctype, content)])

sendclipper/resources/domains.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List
+
+from .._core import Result, seg
+from ._base import Resource
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .._core import RequestOptions
+    from ..types import CreateDomainParams, Domain, DomainRecords, DomainRegion
+
+
+class Domains(Resource):
+    def list(self, **options: Unpack[RequestOptions]) -> Result[List[Domain]]:
+        return self._http.call("GET", "/domains", **options)
+
+    def create(self, params: CreateDomainParams, **options: Unpack[RequestOptions]) -> Result[Domain]:
+        """Register a sending domain. Next: ``records()``, publish them, then ``verify()``."""
+        return self._http.call("POST", "/domains", body=dict(params), **options)
+
+    def records(self, id: str, **options: Unpack[RequestOptions]) -> Result[DomainRecords]:
+        """The DNS records to publish, each with its current status."""
+        return self._http.call("GET", f"/domains/{seg(id)}/records", **options)
+
+    def verify(self, id: str, **options: Unpack[RequestOptions]) -> Result[Domain]:
+        """Check DNS now instead of waiting for the background check."""
+        return self._http.call("POST", f"/domains/{seg(id)}/verify", **options)
+
+    def enable_receiving(self, id: str, **options: Unpack[RequestOptions]) -> Result[Domain]:
+        """Start receiving mail on this domain. Adds receiving records; never blocks sending."""
+        return self._http.call("POST", f"/domains/{seg(id)}/receiving", **options)
+
+    def disable_receiving(self, id: str, **options: Unpack[RequestOptions]) -> Result[Domain]:
+        return self._http.call("DELETE", f"/domains/{seg(id)}/receiving", **options)
+
+    def set_region(self, id: str, region: DomainRegion, **options: Unpack[RequestOptions]) -> Result[Domain]:
+        """Move a domain to another region. Refused (``region_immutable``) once it holds messages."""
+        return self._http.call("PATCH", f"/domains/{seg(id)}/region", body={"region": region}, **options)
+
+    def deletion_preview(self, id: str, **options: Unpack[RequestOptions]) -> Result[Dict[str, Any]]:
+        """What deleting the domain would take with it."""
+        return self._http.call("GET", f"/domains/{seg(id)}/deletion", **options)
+
+    def remove(self, id: str, **options: Unpack[RequestOptions]) -> Result[None]:
+        return self._http.call("DELETE", f"/domains/{seg(id)}", **options)

sendclipper/resources/emails.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator, List, Optional, cast
+
+from .._core import Result, seg, strip_none
+from ._base import Resource
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .._core import RequestOptions
+    from ..types import EmailDetail, EmailList, EmailRow, EmailStats, ListEmailsParams, SendBatchResponse, SendEmailParams, SentEmail
+
+
+class Emails(Resource):
+    def send(self, params: SendEmailParams, **options: Unpack[RequestOptions]) -> Result[SentEmail]:
+        """
+        Send one message. Returns once SendClipper accepted it (status ``queued``);
+        delivery is reported later through ``emails.get()`` and webhooks.
+
+        Every call carries an ``Idempotency-Key``, so the SDK's own retries never
+        send twice. Pass ``idempotency_key=`` yourself to make YOUR retries safe too.
+        """
+        return self._http.call("POST", "/emails", body=dict(params), **options)
+
+    def send_batch(self, emails: List[SendEmailParams], **options: Unpack[RequestOptions]) -> Result[SendBatchResponse]:
+        """Same as ``batch.send()``."""
+        return _send_batch(self, emails, **options)
+
+    def get(self, id: str, **options: Unpack[RequestOptions]) -> Result[EmailDetail]:
+        """One message with its body and event timeline."""
+        return self._http.call("GET", f"/emails/{seg(id)}", **options)
+
+    def list(self, params: Optional[ListEmailsParams] = None, **options: Unpack[RequestOptions]) -> Result[EmailList]:
+        """One page of the sent-mail log, newest first."""
+        return self._http.call("GET", "/emails", query=strip_none(params), **options)
+
+    def iterate(self, params: Optional[ListEmailsParams] = None, **options: Unpack[RequestOptions]) -> Iterator[EmailRow]:
+        """
+        Every message matching ``params``, page after page. Raises
+        ``SendClipperApiError`` on a refusal, since a loop has no ``error`` to return.
+        """
+        query = strip_none(params)
+        page_size = int(query.get("pageSize") or 100)
+        page = 1
+        while True:
+            res = self.list(cast("ListEmailsParams", {**query, "page": page, "pageSize": page_size}), **options).unwrap()
+            yield from res["items"]
+            if len(res["items"]) < page_size or page * page_size >= res["total"]:
+                return
+            page += 1
+
+    def stats(self, **options: Unpack[RequestOptions]) -> Result[EmailStats]:
+        """Counts per status."""
+        return self._http.call("GET", "/emails/stats/summary", **options)
+
+
+class Batch(Resource):
+    def send(self, emails: List[SendEmailParams], **options: Unpack[RequestOptions]) -> Result[SendBatchResponse]:
+        """
+        Up to 500 messages in one request (one recipient each). Every item is
+        accepted or refused on its own; a refused item costs its siblings nothing.
+        """
+        return _send_batch(self, emails, **options)
+
+
+def _send_batch(resource: Resource, emails: List[SendEmailParams], **options: Unpack[RequestOptions]) -> Result[SendBatchResponse]:
+    return resource._http.call("POST", "/emails/batch", body={"emails": [dict(e) for e in emails]}, **options)

sendclipper/resources/mailboxes.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Iterator, List, Optional
+
+from .._core import DownloadedFile, Result, seg, strip_none
+from ._base import Resource
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .._core import RequestOptions
+    from ..types import (
+        CreateMailboxParams,
+        ListMailboxesParams,
+        ListMailboxMessagesParams,
+        Mailbox,
+        MailboxMessage,
+        MailboxMessageList,
+        MailboxMessageRow,
+        UpdateMailboxParams,
+    )
+
+
+class MailboxMessages(Resource):
+    def list(
+        self,
+        mailbox_id: str,
+        params: Optional[ListMailboxMessagesParams] = None,
+        **options: Unpack[RequestOptions],
+    ) -> Result[MailboxMessageList]:
+        """Mail filed under one address. Reading never marks anything read."""
+        return self._http.call("GET", f"/mailboxes/{seg(mailbox_id)}/messages", query=strip_none(params), **options)
+
+    def iterate(
+        self,
+        mailbox_id: str,
+        params: Optional[ListMailboxMessagesParams] = None,
+        **options: Unpack[RequestOptions],
+    ) -> Iterator[MailboxMessageRow]:
+        query: Dict[str, Any] = strip_none(params)
+        while True:
+            res = self.list(mailbox_id, query, **options).unwrap()  # type: ignore[arg-type]
+            yield from res["items"]
+            if not res["page"]["hasMore"] or not res["page"]["cursor"]:
+                return
+            query = {**query, "cursor": res["page"]["cursor"]}
+
+    def get(self, mailbox_id: str, message_id: str, **options: Unpack[RequestOptions]) -> Result[MailboxMessage]:
+        return self._http.call("GET", f"/mailboxes/{seg(mailbox_id)}/messages/{seg(message_id)}", **options)
+
+    def attachment(
+        self,
+        mailbox_id: str,
+        message_id: str,
+        attachment_id: str,
+        **options: Unpack[RequestOptions],
+    ) -> Result[DownloadedFile]:
+        """Download one attachment: ``content`` (bytes), ``content_type`` and ``filename``."""
+        return self._http.call(
+            "GET",
+            f"/mailboxes/{seg(mailbox_id)}/messages/{seg(message_id)}/parts/{seg(attachment_id)}",
+            query={"download": 1},
+            as_="bytes",
+            **options,
+        )
+
+
+class Mailboxes(Resource):
+    def __init__(self, http: Any) -> None:
+        super().__init__(http)
+        self.messages = MailboxMessages(http)
+
+    def list(self, params: Optional[ListMailboxesParams] = None, **options: Unpack[RequestOptions]) -> Result[List[Mailbox]]:
+        """``{"includeArchived": True}`` lists archived addresses too."""
+        return self._http.call("GET", "/mailboxes", query=strip_none(params), **options)
+
+    def get(self, id: str, **options: Unpack[RequestOptions]) -> Result[Mailbox]:
+        return self._http.call("GET", f"/mailboxes/{seg(id)}", **options)
+
+    def create(self, params: CreateMailboxParams, **options: Unpack[RequestOptions]) -> Result[Mailbox]:
+        """A new address on a receiving domain."""
+        return self._http.call("POST", "/mailboxes", body=dict(params), **options)
+
+    def update(self, id: str, params: UpdateMailboxParams, **options: Unpack[RequestOptions]) -> Result[Mailbox]:
+        return self._http.call("PATCH", f"/mailboxes/{seg(id)}", body=dict(params), **options)
+
+    def archive(self, id: str, **options: Unpack[RequestOptions]) -> Result[Mailbox]:
+        """Archives the address. Its mail is kept."""
+        return self._http.call("DELETE", f"/mailboxes/{seg(id)}", **options)