mailkite-dev 0.3.0__tar.gz → 0.5.0__tar.gz

{mailkite_dev-0.3.0 → mailkite_dev-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailkite-dev
-Version: 0.3.0
+Version: 0.5.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
@@ -8,6 +8,7 @@ Project-URL: Repository, https://github.com/mailkite/mailkite
 Keywords: mailkite,email,transactional,api
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41
 
 # MailKite for Python
 

{mailkite_dev-0.3.0 → mailkite_dev-0.5.0}/mailkite/__init__.py

@@ -8,9 +8,11 @@ method per API endpoint. Zero dependencies — uses the standard library.
     res = mk.send({"from": ..., "to": ..., "subject": ..., "text": ...})
 """
 
+import base64
 import hashlib
 import hmac
 import json
+import os
 import time
 import urllib.error
 import urllib.parse
@@ -20,7 +22,7 @@ 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"]
+__all__ = ["MailKite", "MailKiteError", "verify_webhook", "reply_ok", "reply_spam", "reply_drop", "reply_block_sender", "encrypt", "decrypt"]
 
 
 def verify_webhook(signature, payload, secret, toleranceMs=DEFAULT_TOLERANCE_MS):
@@ -51,6 +53,103 @@ def verify_webhook(signature, payload, secret, toleranceMs=DEFAULT_TOLERANCE_MS)
     return hmac.compare_digest(expected, v1)
 
 
+def reply_ok():
+    """Return the canonical ``200 OK`` webhook acknowledgement body.
+
+    Inbound webhook handlers should reply with this exact string so MailKite
+    marks the delivery as accepted. No network call."""
+    return '{"status":"ok"}'
+
+
+def reply_spam():
+    """Control-mode reply telling MailKite to mark the message as spam.
+
+    Returns the exact string ``{"status":"spam"}``. No network call."""
+    return '{"status":"spam"}'
+
+
+def reply_drop():
+    """Control-mode reply telling MailKite to drop (discard) the message.
+
+    Returns the exact string ``{"status":"drop"}``. No network call."""
+    return '{"status":"drop"}'
+
+
+def reply_block_sender():
+    """Control-mode reply telling MailKite to block the sender.
+
+    Returns the exact string ``{"status":"ok","actions":[{"type":"block-sender"}]}``.
+    No network call."""
+    return '{"status":"ok","actions":[{"type":"block-sender"}]}'
+
+
+def encrypt(plaintext, public_key):
+    """Encrypt a UTF-8 string to a MailKite at-rest envelope (JSON string).
+
+    Hybrid encryption matching MailKite's at-rest scheme: a fresh AES-256-GCM
+    content key encrypts the plaintext, then that key is wrapped with the
+    customer's RSA-OAEP (SHA-256) ``public_key`` (SPKI/PEM). Only the holder of
+    the matching private key can :func:`decrypt`. No network call. Requires the
+    ``cryptography`` package."""
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import padding
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+    pem = public_key.encode("utf-8") if isinstance(public_key, str) else public_key
+    pub = serialization.load_pem_public_key(pem)
+    spki_der = pub.public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    fp = hashlib.sha256(spki_der).hexdigest()
+
+    content_key = AESGCM.generate_key(bit_length=256)
+    iv = os.urandom(12)
+    # AESGCM.encrypt returns ciphertext || 16-byte tag (matches WebCrypto).
+    ciphertext = AESGCM(content_key).encrypt(iv, plaintext.encode("utf-8"), None)
+    wrapped = pub.encrypt(
+        content_key,
+        padding.OAEP(mgf=padding.MGF1(hashes.SHA256()), algorithm=hashes.SHA256(), label=None),
+    )
+
+    def b64(b):
+        return base64.b64encode(b).decode("ascii")
+
+    return json.dumps({
+        "v": 1,
+        "keyAlg": "RSA-OAEP-256",
+        "fp": fp,
+        "enc": "A256GCM",
+        "iv": b64(iv),
+        "wrappedKey": b64(wrapped),
+        "ciphertext": b64(ciphertext),
+    })
+
+
+def decrypt(envelope, private_key):
+    """Decrypt a MailKite at-rest ``envelope`` (JSON string) back to plaintext.
+
+    Inverse of :func:`encrypt`: unwraps the AES-256-GCM content key with the
+    RSA-OAEP (SHA-256) ``private_key`` (PKCS8/PEM), then decrypts the ciphertext
+    (which carries its 16-byte GCM tag) and returns the UTF-8 string. No network
+    call. Requires the ``cryptography`` package."""
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import padding
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+    env = json.loads(envelope)
+    pem = private_key.encode("utf-8") if isinstance(private_key, str) else private_key
+    priv = serialization.load_pem_private_key(pem, password=None)
+    content_key = priv.decrypt(
+        base64.b64decode(env["wrappedKey"]),
+        padding.OAEP(mgf=padding.MGF1(hashes.SHA256()), algorithm=hashes.SHA256(), label=None),
+    )
+    plaintext = AESGCM(content_key).decrypt(
+        base64.b64decode(env["iv"]), base64.b64decode(env["ciphertext"]), None
+    )
+    return plaintext.decode("utf-8")
+
+
 class MailKiteError(Exception):
     def __init__(self, status, message, body=None):
         super().__init__(message)
@@ -90,6 +189,15 @@ class MailKite:
         and ``templateData`` (dict) to supply its variables."""
         return self.request("POST", "/v1/send", message)
 
+    def uploadAttachment(self, file):
+        """Upload a file (base64 ``content``) and get back a secure,
+        time-limited URL to reference as a send() attachment
+        (``{ filename, url }``) or link inline — instead of base64-inlining
+        large files on every send. ``file`` is a dict with ``filename`` and
+        ``content`` (base64 str), plus optional ``contentType`` and
+        ``retentionDays`` (7 | 30 | 90 | 365, default 7)."""
+        return self.request("POST", "/v1/attachments", file)
+
     def agent(self, message):
         """Send a message to an AI agent inbox. ``message`` is a dict with
         ``text`` (required) and optional ``subject``, ``from``, ``html``,
@@ -168,3 +276,33 @@ class MailKite:
         :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)
+
+    def reply_ok(self):
+        """Canonical webhook acknowledgement body. See module-level
+        :func:`reply_ok`."""
+        return reply_ok()
+
+    def reply_spam(self):
+        """Control-mode reply marking the message as spam. See module-level
+        :func:`reply_spam`."""
+        return reply_spam()
+
+    def reply_drop(self):
+        """Control-mode reply dropping the message. See module-level
+        :func:`reply_drop`."""
+        return reply_drop()
+
+    def reply_block_sender(self):
+        """Control-mode reply blocking the sender. See module-level
+        :func:`reply_block_sender`."""
+        return reply_block_sender()
+
+    def encrypt(self, plaintext, public_key):
+        """Encrypt to a MailKite at-rest envelope. See module-level
+        :func:`encrypt`."""
+        return encrypt(plaintext, public_key)
+
+    def decrypt(self, envelope, private_key):
+        """Decrypt a MailKite at-rest envelope. See module-level
+        :func:`decrypt`."""
+        return decrypt(envelope, private_key)

{mailkite_dev-0.3.0 → mailkite_dev-0.5.0}/mailkite_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailkite-dev
-Version: 0.3.0
+Version: 0.5.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
@@ -8,6 +8,7 @@ Project-URL: Repository, https://github.com/mailkite/mailkite
 Keywords: mailkite,email,transactional,api
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41
 
 # MailKite for Python
 

{mailkite_dev-0.3.0 → mailkite_dev-0.5.0}/mailkite_dev.egg-info/SOURCES.txt

@@ -4,5 +4,6 @@ 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/requires.txt
 mailkite_dev.egg-info/top_level.txt
 tests/test_sdk.py

mailkite_dev-0.5.0/mailkite_dev.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=41

{mailkite_dev-0.3.0 → mailkite_dev-0.5.0}/pyproject.toml

@@ -7,12 +7,15 @@ build-backend = "setuptools.build_meta"
 # 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"
+version = "0.5.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"]
+# `cryptography` powers the local at-rest encrypt()/decrypt() helpers; everything
+# else in the SDK is standard-library only.
+dependencies = ["cryptography>=41"]
 
 [project.urls]
 Homepage = "https://mailkite.dev/docs/libraries"