Repository Public
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