mailkite-dev 0.3.0__tar.gz

mailkite_dev-0.3.0/PKG-INFO

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

@@ -0,0 +1,53 @@
+# 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/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/mailkite_dev.egg-info/PKG-INFO

@@ -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/mailkite_dev.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+mailkite/__init__.py
+mailkite_dev.egg-info/PKG-INFO
+mailkite_dev.egg-info/SOURCES.txt
+mailkite_dev.egg-info/dependency_links.txt
+mailkite_dev.egg-info/top_level.txt
+tests/test_sdk.py

mailkite_dev-0.3.0/mailkite_dev.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mailkite_dev-0.3.0/mailkite_dev.egg-info/top_level.txt

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

mailkite_dev-0.3.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Temporary distribution name while the `mailkite` project on PyPI is reclaimed on the
+# old account. Installs as `pip install mailkite-dev`; still imports as `import mailkite`
+# (the package dir below is unchanged). Rename back to `mailkite` once reclaimed.
+name = "mailkite-dev"
+version = "0.3.0"
+description = "Official MailKite SDK for Python — send and manage email over your own authenticated domain."
+readme = "README.md"
+requires-python = ">=3.7"
+license = { text = "MIT" }
+keywords = ["mailkite", "email", "transactional", "api"]
+
+[project.urls]
+Homepage = "https://mailkite.dev/docs/libraries"
+Repository = "https://github.com/mailkite/mailkite"
+
+[tool.setuptools.packages.find]
+include = ["mailkite*"]

mailkite_dev-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mailkite_dev-0.3.0/tests/test_sdk.py

@@ -0,0 +1,178 @@
+"""Unit tests for the MailKite Python SDK. Covers every public function:
+
+  - request() (auth, content-type, JSON body, errors, base-url trim, empty body)
+  - one thin method per endpoint (correct verb + path + body)
+  - verify_webhook / verifyWebhook (valid / tampered / wrong-secret / malformed /
+    replay window)
+
+Run with:  python3 -m unittest discover -s tests
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import sys
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from mailkite import MailKite, MailKiteError, verify_webhook  # noqa: E402
+
+# ---- in-process mock server -------------------------------------------------
+STATE = {"status": 200, "body": {"ok": True}, "last": None}
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_):  # silence
+        pass
+
+    def _handle(self):
+        length = int(self.headers.get("content-length") or 0)
+        raw = self.rfile.read(length).decode("utf-8") if length else ""
+        STATE["last"] = {
+            "method": self.command,
+            "path": self.path,
+            "headers": {k.lower(): v for k, v in self.headers.items()},
+            "raw": raw,
+        }
+        body = STATE["body"]
+        payload = b"" if body is None else json.dumps(body).encode("utf-8")
+        self.send_response(STATE["status"])
+        self.send_header("content-type", "application/json")
+        self.end_headers()
+        self.wfile.write(payload)
+
+    do_GET = do_POST = do_PUT = do_DELETE = _handle
+
+
+def reply(status, body):
+    STATE["status"], STATE["body"] = status, body
+
+
+SECRET = "whsec_mailkite_test"
+PAYLOAD = '{"type":"email.received","id":"evt_123","message":"It works."}'
+V1 = "3d790f831e170ddba4d001f27532bf2c1fc68ebed52eef72fe453dfa1196b03c"
+HEADER = "t=1750000000000,v1=" + V1
+
+
+def fresh_header(secret, body):
+    t = int(time.time() * 1000)
+    sig = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+    return f"t={t},v1={sig}"
+
+
+class SDKTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        port = cls.server.server_address[1]
+        cls.base = f"http://127.0.0.1:{port}"
+        cls.key = "mk_live_test"
+        cls.mk = MailKite(cls.key, cls.base)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    # ---- constructor --------------------------------------------------------
+    def test_base_url_trim(self):
+        self.assertEqual(MailKite("k", "https://api.x.dev///").baseUrl, "https://api.x.dev")
+        self.assertEqual(MailKite("k").baseUrl, "https://api.mailkite.dev")
+
+    # ---- request() ----------------------------------------------------------
+    def test_request_auth_and_json(self):
+        reply(200, {"id": "x", "status": "queued"})
+        out = self.mk.request("POST", "/v1/send", {"a": 1})
+        last = STATE["last"]
+        self.assertEqual(last["headers"]["authorization"], "Bearer " + self.key)
+        self.assertIn("application/json", last["headers"]["content-type"])
+        self.assertEqual(json.loads(last["raw"]), {"a": 1})
+        self.assertEqual(out, {"id": "x", "status": "queued"})
+
+    def test_request_no_body(self):
+        reply(200, [])
+        self.mk.request("GET", "/api/domains")
+        self.assertEqual(STATE["last"]["raw"], "")
+        self.assertNotIn("content-type", {k: v for k, v in STATE["last"]["headers"].items() if k == "content-type"})
+
+    def test_request_empty_body_returns_none(self):
+        reply(204, None)
+        self.assertIsNone(self.mk.request("DELETE", "/api/x"))
+
+    def test_request_error_maps_to_exception(self):
+        reply(404, {"error": "not found"})
+        with self.assertRaises(MailKiteError) as ctx:
+            self.mk.request("GET", "/api/messages/nope")
+        self.assertEqual(ctx.exception.status, 404)
+        self.assertEqual(ctx.exception.message, "not found")
+        self.assertEqual(ctx.exception.body, {"error": "not found"})
+
+    def test_request_error_without_error_field(self):
+        reply(500, {"nope": True})
+        with self.assertRaises(MailKiteError) as ctx:
+            self.mk.request("GET", "/x")
+        self.assertEqual(ctx.exception.status, 500)
+
+    # ---- endpoint methods ---------------------------------------------------
+    def test_endpoint_methods(self):
+        mk = self.mk
+        cases = [
+            (lambda: mk.send({"from": "a", "to": "b", "subject": "s", "text": "t"}), "POST", "/v1/send", {"from": "a", "to": "b", "subject": "s", "text": "t"}),
+            (lambda: mk.listDomains(), "GET", "/api/domains", None),
+            (lambda: mk.createDomain({"domain": "x.dev"}), "POST", "/api/domains", {"domain": "x.dev"}),
+            (lambda: mk.getDomain("dom_1"), "GET", "/api/domains/dom_1", None),
+            (lambda: mk.deleteDomain("dom_1"), "DELETE", "/api/domains/dom_1", None),
+            (lambda: mk.verifyDomain("dom_1"), "POST", "/api/domains/dom_1/verify", None),
+            (lambda: mk.setWebhook("dom_1", {"url": "https://h.dev"}), "PUT", "/api/domains/dom_1/webhook", {"url": "https://h.dev"}),
+            (lambda: mk.deleteWebhook("dom_1"), "DELETE", "/api/domains/dom_1/webhook", None),
+            (lambda: mk.testWebhook("dom_1"), "POST", "/api/domains/dom_1/webhook/test", None),
+            (lambda: mk.listRoutes(), "GET", "/api/routes", None),
+            (lambda: mk.createRoute({"match": "*@x", "action": "webhook", "destination": "u"}), "POST", "/api/routes", {"match": "*@x", "action": "webhook", "destination": "u"}),
+            (lambda: mk.listMessages(), "GET", "/api/messages", None),
+            (lambda: mk.getMessage("msg_1"), "GET", "/api/messages/msg_1", None),
+            (lambda: mk.retryDelivery("dlv_1"), "POST", "/api/deliveries/dlv_1/retry", None),
+        ]
+        for call, method, path, body in cases:
+            reply(200, {"ok": True})
+            call()
+            last = STATE["last"]
+            self.assertEqual(last["method"], method, path)
+            self.assertEqual(last["path"], path)
+            if body is None:
+                self.assertEqual(last["raw"], "")
+            else:
+                self.assertEqual(json.loads(last["raw"]), body)
+
+    # ---- verify_webhook -----------------------------------------------------
+    def test_verify_valid(self):
+        self.assertTrue(verify_webhook(HEADER, PAYLOAD, SECRET, 0))
+        self.assertTrue(self.mk.verifyWebhook(HEADER, PAYLOAD, SECRET, 0))
+
+    def test_verify_bytes_payload(self):
+        self.assertTrue(verify_webhook(HEADER, PAYLOAD.encode("utf-8"), SECRET, 0))
+
+    def test_verify_tampered_body(self):
+        self.assertFalse(verify_webhook(HEADER, PAYLOAD + " ", SECRET, 0))
+
+    def test_verify_wrong_secret(self):
+        self.assertFalse(verify_webhook(HEADER, PAYLOAD, "whsec_wrong", 0))
+
+    def test_verify_malformed(self):
+        for h in ["", "garbage", "t=1750000000000", "v1=" + V1, "t=nan,v1=" + V1, None]:
+            self.assertFalse(verify_webhook(h, PAYLOAD, SECRET, 0))
+
+    def test_verify_replay_window(self):
+        # Fixed vector is far in the past → default 5-min window rejects it.
+        self.assertFalse(verify_webhook(HEADER, PAYLOAD, SECRET))
+        # Freshly signed event → passes the default window.
+        self.assertTrue(verify_webhook(fresh_header(SECRET, PAYLOAD), PAYLOAD, SECRET))
+
+
+if __name__ == "__main__":
+    unittest.main()