mailkite-dev 0.3.0__py3-none-any.whl

mailkite/__init__.py

@@ -0,0 +1,170 @@
+"""MailKite SDK for Python.
+
+Shape shared by every MailKite SDK: one low-level ``request()`` plus one thin
+method per API endpoint. Zero dependencies — uses the standard library.
+
+    from mailkite import MailKite
+    mk = MailKite(os.environ["MAILKITE_API_KEY"])
+    res = mk.send({"from": ..., "to": ..., "subject": ..., "text": ...})
+"""
+
+import hashlib
+import hmac
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_BASE_URL = "https://api.mailkite.dev"
+# Reject webhook events older than this (ms) to block replays. Pass 0 to disable.
+DEFAULT_TOLERANCE_MS = 5 * 60 * 1000
+
+__all__ = ["MailKite", "MailKiteError", "verify_webhook"]
+
+
+def verify_webhook(signature, payload, secret, toleranceMs=DEFAULT_TOLERANCE_MS):
+    """Verify an ``x-mailkite-signature`` header on an inbound webhook delivery.
+
+    Local HMAC-SHA256 check — no network call. Pass the raw, unparsed body
+    (``str`` or ``bytes``); the signature is over the exact bytes received.
+    Returns ``True`` only when the signature matches and the event is fresh.
+    """
+    if not isinstance(signature, str) or not signature:
+        return False
+    parts = {}
+    for seg in signature.split(","):
+        if "=" in seg:
+            k, v = seg.split("=", 1)
+            parts[k.strip()] = v.strip()
+    t = parts.get("t")
+    v1 = parts.get("v1")
+    if not t or not v1 or not t.lstrip("-").isdigit():
+        return False
+    # The t in the header is milliseconds since the epoch.
+    if toleranceMs and toleranceMs > 0:
+        if abs(time.time() * 1000 - int(t)) > toleranceMs:
+            return False
+    body = payload.encode("utf-8") if isinstance(payload, str) else payload
+    signed = (t + ".").encode("utf-8") + body
+    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, v1)
+
+
+class MailKiteError(Exception):
+    def __init__(self, status, message, body=None):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+class MailKite:
+    def __init__(self, apiKey, baseUrl=DEFAULT_BASE_URL):
+        self.apiKey = apiKey
+        self.baseUrl = baseUrl.rstrip("/")
+
+    # Low-level request. Every method below is a one-liner on top of this.
+    def request(self, method, path, body=None):
+        headers = {"Authorization": "Bearer " + self.apiKey}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(self.baseUrl + path, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req) as resp:
+                text = resp.read().decode("utf-8")
+                return json.loads(text) if text else None
+        except urllib.error.HTTPError as e:
+            text = e.read().decode("utf-8")
+            parsed = json.loads(text) if text else None
+            message = parsed.get("error") if isinstance(parsed, dict) else None
+            raise MailKiteError(e.code, message or e.reason or "HTTP %d" % e.code, parsed)
+
+    # --- Sending ----------------------------------------------------------
+    def send(self, message):
+        """Send an email. ``message`` is a dict with ``from``, ``to`` and a
+        body (``text`` and/or ``html``). ``subject`` is optional — it may come
+        from a template. Pass ``templateId`` (str) to render a stored template
+        and ``templateData`` (dict) to supply its variables."""
+        return self.request("POST", "/v1/send", message)
+
+    def agent(self, message):
+        """Send a message to an AI agent inbox. ``message`` is a dict with
+        ``text`` (required) and optional ``subject``, ``from``, ``html``,
+        ``routeId``, ``address`` and ``model``."""
+        return self.request("POST", "/v1/agent", message)
+
+    def route(self, message):
+        """Route a message. ``message`` is a dict with ``from`` (required) and
+        optional ``routeId``, ``address``, ``subject``, ``text`` and ``html``."""
+        return self.request("POST", "/v1/route", message)
+
+    # --- Templates --------------------------------------------------------
+    def listTemplates(self):
+        return self.request("GET", "/api/templates")
+
+    def listBaseTemplates(self):
+        return self.request("GET", "/api/templates/base")
+
+    def getTemplate(self, id):
+        return self.request("GET", "/api/templates/%s" % id)
+
+    def createTemplate(self, body):
+        return self.request("POST", "/api/templates", body)
+
+    # --- Domains ----------------------------------------------------------
+    def listDomains(self):
+        return self.request("GET", "/api/domains")
+
+    def createDomain(self, body):
+        return self.request("POST", "/api/domains", body)
+
+    def getDomain(self, id):
+        return self.request("GET", "/api/domains/%s" % id)
+
+    def deleteDomain(self, id):
+        return self.request("DELETE", "/api/domains/%s" % id)
+
+    def verifyDomain(self, id):
+        return self.request("POST", "/api/domains/%s/verify" % id)
+
+    def setWebhook(self, id, body):
+        return self.request("PUT", "/api/domains/%s/webhook" % id, body)
+
+    def deleteWebhook(self, id):
+        return self.request("DELETE", "/api/domains/%s/webhook" % id)
+
+    def testWebhook(self, id):
+        return self.request("POST", "/api/domains/%s/webhook/test" % id)
+
+    def checkDomainAvailability(self, domain):
+        return self.request("GET", "/api/domains/register/check?domain=%s" % urllib.parse.quote(domain))
+
+    def registerDomain(self, body):
+        return self.request("POST", "/api/domains/register", body)
+
+    # --- Routes -----------------------------------------------------------
+    def listRoutes(self):
+        return self.request("GET", "/api/routes")
+
+    def createRoute(self, body):
+        return self.request("POST", "/api/routes", body)
+
+    # --- Messages & deliveries -------------------------------------------
+    def listMessages(self):
+        return self.request("GET", "/api/messages")
+
+    def getMessage(self, id):
+        return self.request("GET", "/api/messages/%s" % id)
+
+    def retryDelivery(self, id):
+        return self.request("POST", "/api/deliveries/%s/retry" % id)
+
+    # --- Webhooks ---------------------------------------------------------
+    def verifyWebhook(self, signature, payload, secret, toleranceMs=DEFAULT_TOLERANCE_MS):
+        """Verify an ``x-mailkite-signature`` header. See module-level
+        :func:`verify_webhook` — this is a thin instance wrapper, so you can
+        call it on an existing client without re-importing."""
+        return verify_webhook(signature, payload, secret, toleranceMs)

mailkite_dev-0.3.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: mailkite-dev
+Version: 0.3.0
+Summary: Official MailKite SDK for Python — send and manage email over your own authenticated domain.
+License: MIT
+Project-URL: Homepage, https://mailkite.dev/docs/libraries
+Project-URL: Repository, https://github.com/mailkite/mailkite
+Keywords: mailkite,email,transactional,api
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# MailKite for Python
+
+Official [MailKite](https://mailkite.dev) SDK. One low-level `request()` plus one
+method per endpoint. Zero dependencies — standard library only. Python 3.7+.
+
+## Install
+
+```bash
+pip install mailkite-dev
+```
+
+> Published as `mailkite-dev` for now (the `mailkite` name is being reclaimed). The
+> import is unchanged — `from mailkite import MailKite`.
+
+## Usage
+
+```python
+import os
+from mailkite import MailKite
+
+mk = MailKite(os.environ["MAILKITE_API_KEY"])
+
+res = mk.send({
+    "from": "hello@myapp.ai",
+    "to": "ada@example.com",
+    "subject": "Your invoice #1042",
+    "html": "<p>Thanks! Receipt attached.</p>",
+})
+```
+
+Point at a different base URL with `MailKite(key, "https://api.mailkite.dev")`.
+
+## Methods
+
+`send(message)`, `agent(message)`, `route(message)`, `listDomains()`, `createDomain({"domain": ...})`,
+`getDomain(id)`, `deleteDomain(id)`, `verifyDomain(id)`,
+`setWebhook(id, {"url": ...})`, `deleteWebhook(id)`, `testWebhook(id)`,
+`checkDomainAvailability(domain)`, `registerDomain({"domain": ..., "contact": {...}})`,
+`listRoutes()`, `createRoute({...})`, `listMessages()`, `getMessage(id)`,
+`retryDelivery(id)`.
+
+## Errors
+
+```python
+from mailkite import MailKiteError
+
+try:
+    mk.send(msg)
+except MailKiteError as e:
+    print(e.status, e.message)
+```
+
+See the [full docs](https://mailkite.dev/docs/libraries).

mailkite_dev-0.3.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+mailkite/__init__.py,sha256=nQMshndS88_H0rgQFlvjhkiVAHm0qjLxmIVB72XNmcg,6765
+mailkite_dev-0.3.0.dist-info/METADATA,sha256=Gq-_oVxgxpRLgoyQg7KU8nWG-9_3JLejXNb_dopk0Cs,1765
+mailkite_dev-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mailkite_dev-0.3.0.dist-info/top_level.txt,sha256=bc29TJ7KmxbFePYiquHfd7teobuAkjxFvtEJjk28QGk,9
+mailkite_dev-0.3.0.dist-info/RECORD,,

mailkite_dev-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mailkite_dev-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mailkite