SPB Git

Repository Public

_client.py 21.5 KB 412 lines python

1"""Resource-style client of the SP Mail REST API. Every method maps to one operation of docs/OPENAPI.yaml."""2from __future__ import annotations34import os5import re6import time7import urllib.parse8from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Sequence, Union, cast910from . import _generated as t11from ._errors import TimeoutError12from ._http import HttpClient, Transport13from ._webhooks import Payload, construct_event, sign_webhook_payload, verify_webhook_signature1415#: Statuses after which a send no longer changes (docs/API.md section 7).16FINAL_STATUSES = ("delivered", "bounced", "failed", "cancelled")1718Params = Optional[Mapping[str, Any]]192021def _q(s: str) -> str:22    return urllib.parse.quote(s, safe="")232425def _merge(params: Params, fields: Mapping[str, Any]) -> Dict[str, Any]:26    """Body/query from a mapping and/or keyword arguments. ``from_`` stands for the field ``from``; None values are dropped."""27    out: Dict[str, Any] = dict(params or {})28    for k, v in fields.items():29        if v is not None:30            out["from" if k == "from_" else k] = v31    return out323334class _Resource:35    def __init__(self, http: HttpClient) -> None:36        self._http = http3738    def _paginate(self, fetch: Callable[..., Any], query: Dict[str, Any]) -> Iterator[Any]:39        cursor = query.pop("cursor", None)40        while True:41            page = fetch(**query, cursor=cursor)42            yield from page["data"]43            if not page.get("has_more") or not page.get("next_cursor"):44                return45            cursor = page["next_cursor"]464748class Outbound(_Resource):49    def list(self, **query: Any) -> t.OutboundPage:50        """Sends created by this key, or made from an address it can act as; newest first. ``status=``, ``limit=``, ``cursor=``."""51        return cast(t.OutboundPage, self._http.request("GET", "/messages/outbound", query=query))5253    def iterate(self, **query: Any) -> Iterator[t.OutboundMessage]:54        return self._paginate(self.list, query)5556    def get(self, outbound_id: str) -> t.OutboundMessage:57        """One send, with per-recipient status and SMTP reply."""58        return cast(t.OutboundMessage, self._http.request("GET", f"/messages/outbound/{_q(outbound_id)}"))596061class Scheduled(_Resource):62    def list(self, **query: Any) -> t.OutboundPage:63        return cast(t.OutboundPage, self._http.request("GET", "/messages/scheduled", query=query))6465    def iterate(self, **query: Any) -> Iterator[t.OutboundMessage]:66        return self._paginate(self.list, query)6768    def cancel(self, outbound_id: str) -> t.OutboundMessage:69        """Cancels a scheduled send; ``409 not_cancellable`` once it is no longer scheduled."""70        return cast(t.OutboundMessage, self._http.request("DELETE", f"/messages/scheduled/{_q(outbound_id)}"))717273class DownloadedAttachment:74    """Bytes of an attachment. Untrusted third-party content: never execute or render it blindly."""7576    __slots__ = ("data", "filename", "size")7778    def __init__(self, data: bytes, filename: Optional[str]) -> None:79        self.data = data80        self.filename = filename81        self.size = len(data)8283    def __repr__(self) -> str:84        return f"DownloadedAttachment(filename={self.filename!r}, size={self.size})"858687class Attachments(_Resource):88    def list(self, message_id: str) -> List[t.Attachment]:89        return cast(List[t.Attachment], self._http.request("GET", f"/messages/{_q(message_id)}/attachments")["data"])9091    def download(self, message_id: str, attachment_id: str) -> DownloadedAttachment:92        data, headers = self._http.request("GET", f"/messages/{_q(message_id)}/attachments/{_q(attachment_id)}", binary=True)93        m = re.search(r"filename\*=UTF-8''([^;]+)", headers.get("content-disposition", ""), re.I)94        return DownloadedAttachment(data, urllib.parse.unquote(m.group(1)) if m else None)959697class Messages(_Resource):98    def __init__(self, http: HttpClient) -> None:99        super().__init__(http)100        self.outbound = Outbound(http)101        self.scheduled = Scheduled(http)102        self.attachments = Attachments(http)103104    def send(self, params: Params = None, *, idempotency_key: Optional[str] = None, **fields: Any) -> t.OutboundMessage:105        """Sends a message, or a rendered template with ``template_id=`` + ``variables=``.106107        ``client.messages.send(from_="alerts@example.org", to=["ops@example.org"], subject="Hi", text="...")``108109        Look at ``status`` in the answer: ``sent``/``failed``, ``scheduled``/``pending_approval``/``queued``, ``draft``.110        ``pending_approval`` means NOTHING was sent yet. An ``Idempotency-Key`` is generated for you; pass your own111        ``idempotency_key`` to make a retry of YOUR process idempotent.112        """113        return cast(t.OutboundMessage, self._http.request("POST", "/messages/send", body=_merge(params, fields), idempotent=True, idempotency_key=idempotency_key))114115    def send_batch(self, messages: Sequence[Mapping[str, Any]], *, idempotency_key: Optional[str] = None) -> t.BatchResult:116        """Up to 50 messages; each is validated, authorised and limited independently (``results[i]["ok"]``)."""117        body = {"messages": [_merge(m, {}) for m in messages]}118        return cast(t.BatchResult, self._http.request("POST", "/messages/send-batch", body=body, idempotent=True, idempotency_key=idempotency_key))119120    def list(self, **query: Any) -> t.MessagePage:121        """Newest first. Filters: address, folder, unread, flagged, has_attachment, from_, to, subject, text, label, after, before, limit, cursor."""122        return cast(t.MessagePage, self._http.request("GET", "/messages", query=_merge(None, query)))123124    def iterate(self, **query: Any) -> Iterator[t.MessageSummary]:125        """``for m in client.messages.iterate(folder="inbox", unread=True): ...`` - follows ``next_cursor`` for you."""126        return self._paginate(self.list, query)127128    def get(self, message_id: str) -> t.Message:129        return cast(t.Message, self._http.request("GET", f"/messages/{_q(message_id)}"))130131    def changes(self, **query: Any) -> t.Changes:132        """Incremental sync of one mailbox (``address=``, ``since=``, ``limit=``). ``409 resync_required`` -> list again."""133        return cast(t.Changes, self._http.request("GET", "/messages/changes", query=query))134135    def reply(self, message_id: str, params: Params = None, *, idempotency_key: Optional[str] = None, **fields: Any) -> t.OutboundMessage:136        return cast(t.OutboundMessage, self._http.request("POST", f"/messages/{_q(message_id)}/reply", body=_merge(params, fields), idempotent=True, idempotency_key=idempotency_key))137138    def forward(self, message_id: str, params: Params = None, *, idempotency_key: Optional[str] = None, **fields: Any) -> t.OutboundMessage:139        return cast(t.OutboundMessage, self._http.request("POST", f"/messages/{_q(message_id)}/forward", body=_merge(params, fields), idempotent=True, idempotency_key=idempotency_key))140141    def update(self, message_id: str, params: Params = None, **fields: Any) -> t.MessageSummary:142        """``unread``, ``starred``, ``add_labels``, ``remove_labels``."""143        return cast(t.MessageSummary, self._http.request("PATCH", f"/messages/{_q(message_id)}", body=_merge(params, fields), repeatable=True))144145    def mark_read(self, message_id: str) -> t.MessageSummary:146        return self.update(message_id, unread=False)147148    def mark_unread(self, message_id: str) -> t.MessageSummary:149        return self.update(message_id, unread=True)150151    def move(self, message_id: str, folder: str) -> t.MessageSummary:152        """To a role (``inbox``, ``archive``, ``trash``, ``junk``, ``sent``, ``drafts``) or a folder id of the same mailbox."""153        return cast(t.MessageSummary, self._http.request("POST", f"/messages/{_q(message_id)}/move", body={"folder": folder}, repeatable=True))154155    def archive(self, message_id: str) -> t.MessageSummary:156        return self.move(message_id, "archive")157158    def delete(self, message_id: str, *, permanent: bool = False) -> Dict[str, Any]:159        """Moves to Trash; ``permanent=True`` destroys the message (scope ``mail.delete``; the required confirmation is sent)."""160        if permanent:161            return cast(Dict[str, Any], self._http.request("DELETE", f"/messages/{_q(message_id)}", query={"permanent": True}, body={"confirm": "permanently-delete"}))162        return cast(Dict[str, Any], self._http.request("DELETE", f"/messages/{_q(message_id)}"))163164    def wait_for_delivery(self, outbound_id: str, *, timeout: float = 60.0, interval: float = 1.5) -> t.OutboundMessage:165        """Polls a send until its status is final (delivered, bounced, failed, cancelled) and returns it.166167        ``delivered`` = accepted by the recipient's server, not inbox placement. A send that is ``pending_approval`` or168        ``scheduled`` stays so until someone acts: expect a TimeoutError whose ``details["last"]`` is the last status seen.169        """170        deadline = time.monotonic() + timeout171        interval = max(0.1, interval)172        while True:173            o = self.outbound.get(outbound_id)174            if o["status"] in FINAL_STATUSES:175                return o176            if time.monotonic() + interval > deadline:177                raise TimeoutError(f"Send {outbound_id} is still \"{o['status']}\" after {timeout:g} s", code="timeout", details={"last": o})178            time.sleep(interval)179180181class Threads(_Resource):182    def list(self, **query: Any) -> t.ThreadPage:183        return cast(t.ThreadPage, self._http.request("GET", "/threads", query=_merge(None, query)))184185    def iterate(self, **query: Any) -> Iterator[t.ThreadSummary]:186        return self._paginate(self.list, query)187188    def get(self, thread_id: str) -> t.Thread:189        return cast(t.Thread, self._http.request("GET", f"/threads/{_q(thread_id)}"))190191192class Drafts(_Resource):193    def create(self, params: Params = None, *, idempotency_key: Optional[str] = None, **fields: Any) -> t.OutboundMessage:194        """Only ``from_`` is required. The answer's ``id`` is the draft's ``msg_...`` id."""195        return cast(t.OutboundMessage, self._http.request("POST", "/drafts", body=_merge(params, fields), idempotent=True, idempotency_key=idempotency_key))196197    def list(self, **query: Any) -> t.MessagePage:198        return cast(t.MessagePage, self._http.request("GET", "/drafts", query=query))199200    def iterate(self, **query: Any) -> Iterator[t.MessageSummary]:201        return self._paginate(self.list, query)202203    def get(self, draft_id: str) -> t.Message:204        return cast(t.Message, self._http.request("GET", f"/drafts/{_q(draft_id)}"))205206    def update(self, draft_id: str, params: Params = None, **fields: Any) -> t.OutboundMessage:207        """Replaces the given fields. **The answer carries a NEW ``id``**: the old one is gone."""208        return cast(t.OutboundMessage, self._http.request("PATCH", f"/drafts/{_q(draft_id)}", body=_merge(params, fields)))209210    def delete(self, draft_id: str) -> Dict[str, Any]:211        return cast(Dict[str, Any], self._http.request("DELETE", f"/drafts/{_q(draft_id)}"))212213    def send(self, draft_id: str, *, send_at: Optional[str] = None, idempotency_key: Optional[str] = None) -> t.OutboundMessage:214        return cast(t.OutboundMessage, self._http.request("POST", f"/drafts/{_q(draft_id)}/send", body=_merge(None, {"send_at": send_at}), idempotent=True, idempotency_key=idempotency_key))215216217class Folders(_Resource):218    def list(self, *, address: Optional[str] = None) -> List[t.Folder]:219        return cast(List[t.Folder], self._http.request("GET", "/folders", query={"address": address})["data"])220221    def create(self, *, address: str, name: str, parent_id: Optional[str] = None, idempotency_key: Optional[str] = None) -> t.Folder:222        return cast(t.Folder, self._http.request("POST", "/folders", body=_merge(None, {"address": address, "name": name, "parent_id": parent_id}), idempotent=True, idempotency_key=idempotency_key))223224225class Files(_Resource):226    def upload(self, data: Union[bytes, bytearray, str, "os.PathLike[str]"], *, filename: Optional[str] = None,227               content_type: str = "application/octet-stream", address: Optional[str] = None) -> t.UploadedFile:228        """Uploads raw bytes (max 50 MB) and returns a ``file_...`` id for ``attachments``. Not idempotent: never retried on failure.229230        ``data`` is bytes, or a path (``pathlib.Path``) whose content is read; a ``str`` is text content, not a path.231        """232        if isinstance(data, os.PathLike):233            path = os.fspath(data)234            filename = filename or os.path.basename(path)235            with open(path, "rb") as fh:236                raw = fh.read()237        elif isinstance(data, str):238            raw = data.encode("utf-8")239        else:240            raw = bytes(data)241        return cast(t.UploadedFile, self._http.request("POST", "/files", query={"filename": filename, "address": address}, raw=(raw, content_type)))242243244class _AddressBase(_Resource):245    _base = "/addresses"246247    def list(self, **query: Any) -> List[t.Address]:248        """``kind=``, ``mailbox=``, ``status=``."""249        return cast(List[t.Address], self._http.request("GET", self._base, query=query)["data"])250251    def create(self, params: Params = None, *, idempotency_key: Optional[str] = None, **fields: Any) -> t.Address:252        return cast(t.Address, self._http.request("POST", self._base, body=_merge(params, fields), idempotent=True, idempotency_key=idempotency_key))253254    def update(self, address_id: str, params: Params = None, **fields: Any) -> t.Address:255        """``address_id`` is the UUID or the address itself."""256        body = dict(params or {})257        body.update(fields)  # None is meaningful here (e.g. expires_at=None)258        return cast(t.Address, self._http.request("PATCH", f"{self._base}/{_q(address_id)}", body=body, repeatable=True))259260261class Addresses(_AddressBase):262    def get(self, address_id: str) -> t.Address:263        return cast(t.Address, self._http.request("GET", f"/addresses/{_q(address_id)}"))264265    def delete(self, address_id: str, *, purge_all_mail: bool = False) -> Dict[str, Any]:266        """Alias kinds are removed. A mailbox (``mail.admin``) is detached unless ``purge_all_mail`` - which destroys the account and all its mail."""267        if purge_all_mail:268            return cast(Dict[str, Any], self._http.request("DELETE", f"/addresses/{_q(address_id)}", query={"purge": "delete-all-mail"}, body={"confirm": "delete-all-mail"}))269        return cast(Dict[str, Any], self._http.request("DELETE", f"/addresses/{_q(address_id)}"))270271    def get_automation(self, address_id: str) -> t.Automation:272        return cast(t.Automation, self._http.request("GET", f"/addresses/{_q(address_id)}/automation"))273274    def update_automation(self, address_id: str, params: Params = None, **fields: Any) -> t.Automation:275        body = dict(params or {})276        body.update(fields)  # forward=None removes forwarding277        return cast(t.Automation, self._http.request("PUT", f"/addresses/{_q(address_id)}/automation", body=body))278279280class Aliases(_AddressBase):281    _base = "/aliases"282283    def delete(self, address_id: str) -> Dict[str, Any]:284        return cast(Dict[str, Any], self._http.request("DELETE", f"/aliases/{_q(address_id)}"))285286287class WebhookDeliveries(_Resource):288    def list(self, webhook_id: str, **query: Any) -> t.WebhookDeliveryPage:289        return cast(t.WebhookDeliveryPage, self._http.request("GET", f"/webhooks/{_q(webhook_id)}/deliveries", query=query))290291    def iterate(self, webhook_id: str, **query: Any) -> Iterator[t.WebhookDelivery]:292        return self._paginate(lambda **q: self.list(webhook_id, **q), query)293294    def replay(self, delivery_id: str) -> t.WebhookDelivery:295        return cast(t.WebhookDelivery, self._http.request("POST", f"/webhook-deliveries/{_q(delivery_id)}/replay"))296297298class Webhooks(_Resource):299    def __init__(self, http: HttpClient) -> None:300        super().__init__(http)301        self.deliveries = WebhookDeliveries(http)302303    def create(self, params: Params = None, *, idempotency_key: Optional[str] = None, **fields: Any) -> t.Webhook:304        """The answer carries ``secret`` (``whsec_...``) - shown ONCE: store it now."""305        return cast(t.Webhook, self._http.request("POST", "/webhooks", body=_merge(params, fields), idempotent=True, idempotency_key=idempotency_key))306307    def list(self) -> List[t.Webhook]:308        return cast(List[t.Webhook], self._http.request("GET", "/webhooks")["data"])309310    def get(self, webhook_id: str) -> t.Webhook:311        return cast(t.Webhook, self._http.request("GET", f"/webhooks/{_q(webhook_id)}"))312313    def update(self, webhook_id: str, params: Params = None, **fields: Any) -> t.Webhook:314        """``rotate_secret=True`` returns the new secret once."""315        return cast(t.Webhook, self._http.request("PATCH", f"/webhooks/{_q(webhook_id)}", body=_merge(params, fields)))316317    def delete(self, webhook_id: str) -> Dict[str, Any]:318        return cast(Dict[str, Any], self._http.request("DELETE", f"/webhooks/{_q(webhook_id)}"))319320    def test(self, webhook_id: str) -> t.WebhookTestResult:321        """Sends a signed ``webhook.test`` event now."""322        return cast(t.WebhookTestResult, self._http.request("POST", f"/webhooks/{_q(webhook_id)}/test"))323324    def replay(self, delivery_id: str) -> t.WebhookDelivery:325        return self.deliveries.replay(delivery_id)326327    @staticmethod328    def verify_signature(payload: Payload, header: Optional[str], secret: str, *, tolerance: float = 300) -> bool:329        return verify_webhook_signature(payload, header, secret, tolerance=tolerance)330331    @staticmethod332    def construct_event(payload: Payload, header: Optional[str], secret: str, *, tolerance: float = 300) -> Dict[str, Any]:333        return construct_event(payload, header, secret, tolerance=tolerance)334335    @staticmethod336    def sign(payload: Payload, secret: str, *, timestamp: Optional[float] = None) -> str:337        return sign_webhook_payload(payload, secret, timestamp=timestamp)338339340class Events(_Resource):341    def list(self, **query: Any) -> t.EventPage:342        """Recent events visible to the key, newest first, metadata only (``type=``, ``limit=``, ``cursor=``)."""343        return cast(t.EventPage, self._http.request("GET", "/events", query=query))344345    def iterate(self, **query: Any) -> Iterator[t.Event]:346        return self._paginate(self.list, query)347348349class Templates(_Resource):350    def list(self) -> List[t.TemplateSummary]:351        return cast(List[t.TemplateSummary], self._http.request("GET", "/templates")["templates"])352353    def get(self, template_id: str) -> t.Template:354        return cast(t.Template, self._http.request("GET", f"/templates/{_q(template_id)}"))355356    def render(self, template_id: str, variables: Optional[Mapping[str, str]] = None, *, use_examples: Optional[bool] = None) -> t.RenderedTemplate:357        """Renders without sending; ``missing`` lists the required variables that were not supplied."""358        body = _merge(None, {"variables": dict(variables) if variables is not None else None, "use_examples": use_examples})359        return cast(t.RenderedTemplate, self._http.request("POST", f"/templates/{_q(template_id)}/render", body=body, repeatable=True))360361362class SPMail:363    """Client of the SP Mail REST API.364365    ``client = SPMail(api_key=os.environ["SPMAIL_API_KEY"])`` - or ``SPMail()`` to read ``SPMAIL_API_KEY`` and366    ``SPMAIL_BASE_URL`` from the environment.367    """368369    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, *, timeout: float = 30.0, max_retries: int = 2,370                 max_retry_delay: float = 60.0, allow_insecure_http: bool = False, transport: Optional[Transport] = None,371                 default_headers: Optional[Mapping[str, str]] = None) -> None:372        http = HttpClient(api_key if api_key is not None else os.environ.get("SPMAIL_API_KEY", ""),373                          base_url or os.environ.get("SPMAIL_BASE_URL") or "https://mail.spboucher.ai",374                          timeout=timeout, max_retries=max_retries, max_retry_delay=max_retry_delay,375                          allow_insecure_http=allow_insecure_http, transport=transport, default_headers=default_headers)376        self._http = http377        self.messages = Messages(http)378        self.threads = Threads(http)379        self.drafts = Drafts(http)380        self.folders = Folders(http)381        self.files = Files(http)382        self.addresses = Addresses(http)383        self.aliases = Aliases(http)384        self.webhooks = Webhooks(http)385        self.events = Events(http)386        self.templates = Templates(http)387388    @property389    def base_url(self) -> str:390        """Base URL in use, ending with ``/api/v1``."""391        return self._http.base_url392393    def __repr__(self) -> str:394        return f"SPMail(base_url={self.base_url!r})"395396    def me(self) -> t.Me:397        """Who am I: scopes, usable addresses (``read``: full/restricted/none), limits, today's usage."""398        return cast(t.Me, self._http.request("GET", "/me"))399400    def health(self) -> t.Health:401        """Public health probe. Raises a ServerError (503) when the instance is not healthy."""402        return cast(t.Health, self._http.request("GET", "/health", anonymous=True))403404    def wait_for_delivery(self, outbound_id: str, *, timeout: float = 60.0, interval: float = 1.5) -> t.OutboundMessage:405        return self.messages.wait_for_delivery(outbound_id, timeout=timeout, interval=interval)406407    def request(self, method: str, path: str, *, query: Params = None, body: Any = None, idempotent: bool = False,408                idempotency_key: Optional[str] = None) -> Any:409        """Escape hatch for an endpoint the SDK does not wrap yet. ``path`` is relative to ``/api/v1``."""410        return self._http.request(method.upper(), path if path.startswith("/") else f"/{path}", query=query, body=body,411                                  idempotent=idempotent, idempotency_key=idempotency_key)412
Files main
Menu

Theme