vaemail 1.0.0__tar.gz

vaemail-1.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: vaemail
+Version: 1.0.0
+Summary: Email infrastructure for AI agents and applications: send transactional email, authenticate sending domains, track delivery, diagnose deliverability.
+Author: VaEmail (Agence SW)
+License: MIT
+Project-URL: Homepage, https://vaemail.fr/agents
+Project-URL: Documentation, https://vaemail.fr/docs/api
+Project-URL: Source, https://github.com/vaemail/vaemail-python
+Keywords: email,email-api,transactional-email,ai-agent,agent,deliverability,sdk,vaemail,eu
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# vaemail — Python SDK
+
+Email infrastructure for AI agents and applications. Send transactional email,
+authenticate sending domains, track delivery, and diagnose deliverability.
+
+No dependencies: the SDK uses only the standard library, so it installs without
+pulling anything behind it.
+
+```bash
+pip install vaemail
+```
+
+## Send an email
+
+```python
+from vaemail import VaEmail
+
+client = VaEmail(api_key="your-api-key")
+
+client.send({
+    "to": "customer@example.com",
+    "subject": "Your order is on its way",
+    "html": "<p>Tracking number: 1Z999</p>",
+}, idempotency_key="order-4711")
+```
+
+The idempotency key makes the call safe to replay for 24 hours: retrying after a
+timeout will not send a second email.
+
+## Try before sending
+
+```python
+client.validate({"to": "customer@example.com", "subject": "Hi", "html": "<p>Hi</p>"})
+```
+
+Same checks as a real send — key scope, quotas, sending domain, suppression
+list — but nothing leaves. Useful when an agent builds a message on its own.
+
+## Authenticate a sending domain
+
+```python
+result = client.add_domain("news.example.com", dkim_tokens=["aaa111", "bbb222", "ccc333"])
+
+for record in result["data"]["dns_records"]:
+    if record["publishable"]:
+        print(record["type"], record["host"], "->", record["value"])
+```
+
+The three DKIM tokens come from Amazon SES when the domain identity is created.
+Every record says whether it is `publishable` as-is: a value that still depends
+on something unknown is flagged instead of being handed over, so an agent never
+publishes a record that would break the domain's authentication.
+
+## Errors say what to do next
+
+```python
+from vaemail import VaEmailError
+
+try:
+    client.send({"to": "customer@example.com"})
+except VaEmailError as error:
+    print(error.code)        # DOMAIN_NOT_VERIFIED
+    print(error.retryable)   # False
+    print(error.for_agent()) # reason, corrective action, whether to retry
+```
+
+## Everything else
+
+`capabilities()`, `health()`, `get_message()`, `list_messages()`,
+`list_domains()`, `verify_domain()`, `dns_records()`,
+`diagnose_deliverability()`, `list_suppressions()`, `usage()`, `audit_logs()`.
+
+Full API reference: <https://vaemail.fr/docs/api>
+
+## Tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+MIT licensed.

vaemail-1.0.0/README.md

@@ -0,0 +1,81 @@
+# vaemail — Python SDK
+
+Email infrastructure for AI agents and applications. Send transactional email,
+authenticate sending domains, track delivery, and diagnose deliverability.
+
+No dependencies: the SDK uses only the standard library, so it installs without
+pulling anything behind it.
+
+```bash
+pip install vaemail
+```
+
+## Send an email
+
+```python
+from vaemail import VaEmail
+
+client = VaEmail(api_key="your-api-key")
+
+client.send({
+    "to": "customer@example.com",
+    "subject": "Your order is on its way",
+    "html": "<p>Tracking number: 1Z999</p>",
+}, idempotency_key="order-4711")
+```
+
+The idempotency key makes the call safe to replay for 24 hours: retrying after a
+timeout will not send a second email.
+
+## Try before sending
+
+```python
+client.validate({"to": "customer@example.com", "subject": "Hi", "html": "<p>Hi</p>"})
+```
+
+Same checks as a real send — key scope, quotas, sending domain, suppression
+list — but nothing leaves. Useful when an agent builds a message on its own.
+
+## Authenticate a sending domain
+
+```python
+result = client.add_domain("news.example.com", dkim_tokens=["aaa111", "bbb222", "ccc333"])
+
+for record in result["data"]["dns_records"]:
+    if record["publishable"]:
+        print(record["type"], record["host"], "->", record["value"])
+```
+
+The three DKIM tokens come from Amazon SES when the domain identity is created.
+Every record says whether it is `publishable` as-is: a value that still depends
+on something unknown is flagged instead of being handed over, so an agent never
+publishes a record that would break the domain's authentication.
+
+## Errors say what to do next
+
+```python
+from vaemail import VaEmailError
+
+try:
+    client.send({"to": "customer@example.com"})
+except VaEmailError as error:
+    print(error.code)        # DOMAIN_NOT_VERIFIED
+    print(error.retryable)   # False
+    print(error.for_agent()) # reason, corrective action, whether to retry
+```
+
+## Everything else
+
+`capabilities()`, `health()`, `get_message()`, `list_messages()`,
+`list_domains()`, `verify_domain()`, `dns_records()`,
+`diagnose_deliverability()`, `list_suppressions()`, `usage()`, `audit_logs()`.
+
+Full API reference: <https://vaemail.fr/docs/api>
+
+## Tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+MIT licensed.

vaemail-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vaemail"
+version = "1.0.0"
+description = "Email infrastructure for AI agents and applications: send transactional email, authenticate sending domains, track delivery, diagnose deliverability."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "VaEmail (Agence SW)" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["email", "email-api", "transactional-email", "ai-agent", "agent", "deliverability", "sdk", "vaemail", "eu"]
+
+[project.urls]
+Homepage = "https://vaemail.fr/agents"
+Documentation = "https://vaemail.fr/docs/api"
+Source = "https://github.com/vaemail/vaemail-python"
+
+[tool.setuptools]
+packages = ["vaemail"]

vaemail-1.0.0/setup.cfg

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

vaemail-1.0.0/tests/test_sdk.py

@@ -0,0 +1,107 @@
+"""Ce qui compte est ce qui part sur le réseau : on l'observe avec un faux opener.
+
+Pas de dépendance de test non plus (unittest de la bibliothèque standard), pour
+que `python -m unittest` suffise partout.
+"""
+
+import io
+import json
+import sys
+import unittest
+import urllib.error
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from vaemail import DEFAULT_BASE_URL, VaEmail, VaEmailError  # noqa: E402
+
+
+class FausseReponse(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+        return False
+
+
+def espion(charge=None, statut=200):
+    appels = []
+
+    def opener(requete, timeout=None):
+        appels.append(requete)
+        corps = json.dumps(charge if charge is not None else {"success": True, "data": {}})
+        if statut >= 400:
+            raise urllib.error.HTTPError(
+                requete.full_url, statut, "erreur", {}, io.BytesIO(corps.encode())
+            )
+        return FausseReponse(corps.encode())
+
+    return appels, opener
+
+
+class TestSdk(unittest.TestCase):
+    def test_la_cle_part_en_entete_et_la_base_est_la_production(self):
+        appels, opener = espion()
+        VaEmail(api_key="cle-test", opener=opener).capabilities()
+
+        self.assertEqual(appels[0].full_url, f"{DEFAULT_BASE_URL}/api/v1/capabilities")
+        self.assertEqual(appels[0].get_header("Api-key"), "cle-test")
+
+    def test_les_jetons_dkim_sont_transmis(self):
+        appels, opener = espion()
+        VaEmail(api_key="k", opener=opener).add_domain(
+            "news.exemple.fr", dkim_tokens=["aaa111", "bbb222", "ccc333"]
+        )
+
+        corps = json.loads(appels[0].data)
+        self.assertEqual(corps["dkim_tokens"], ["aaa111", "bbb222", "ccc333"])
+        self.assertNotIn("dkim_selector", corps)
+
+    def test_la_cle_d_idempotence_part_en_entete(self):
+        appels, opener = espion()
+        VaEmail(api_key="k", opener=opener).send({"to": "x@exemple.fr"}, "commande-42")
+
+        self.assertEqual(appels[0].get_header("Idempotency-key"), "commande-42")
+
+    def test_les_filtres_vides_ne_polluent_pas_l_url(self):
+        appels, opener = espion()
+        VaEmail(api_key="k", opener=opener).list_messages(status="sent", limit=None)
+
+        self.assertIn("status=sent", appels[0].full_url)
+        self.assertNotIn("limit", appels[0].full_url)
+
+    def test_une_erreur_dit_quoi_faire_et_si_l_appel_peut_etre_rejoue(self):
+        _, opener = espion(
+            {
+                "error": {
+                    "code": "DOMAIN_NOT_VERIFIED",
+                    "message": "Domaine non authentifié.",
+                    "resolution": {"action": "verify_domain", "endpoint": "/api/v1/domains/verify"},
+                    "retryable": False,
+                }
+            },
+            422,
+        )
+
+        with self.assertRaises(VaEmailError) as capture:
+            VaEmail(api_key="k", opener=opener).send({"to": "x@exemple.fr"})
+
+        erreur = capture.exception
+        self.assertEqual(erreur.code, "DOMAIN_NOT_VERIFIED")
+        self.assertEqual(erreur.status, 422)
+        self.assertFalse(erreur.retryable)
+        self.assertIn("verify_domain", erreur.for_agent())
+
+    def test_une_erreur_applicative_renvoyee_en_200_est_levee_quand_meme(self):
+        _, opener = espion({"error": {"code": "QUOTA_EXCEEDED", "retryable": True}}, 200)
+
+        with self.assertRaises(VaEmailError) as capture:
+            VaEmail(api_key="k", opener=opener).usage()
+
+        self.assertEqual(capture.exception.code, "QUOTA_EXCEEDED")
+        self.assertTrue(capture.exception.retryable)
+
+
+if __name__ == "__main__":
+    unittest.main()

vaemail-1.0.0/vaemail/__init__.py

@@ -0,0 +1,220 @@
+"""SDK Python de VaEmail.
+
+Aucune dépendance : `urllib` suffit, et un paquet destiné à être installé par un
+agent doit pouvoir s'installer sans rien tirer derrière lui. C'est le même parti
+pris que le paquet npm.
+
+    from vaemail import VaEmail
+
+    client = VaEmail(api_key="...")
+    client.send({"to": "x@exemple.fr", "subject": "Bonjour", "html": "<p>Bonjour</p>"})
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+__all__ = ["VaEmail", "VaEmailError", "DEFAULT_BASE_URL"]
+__version__ = "1.0.0"
+
+DEFAULT_BASE_URL = "https://app.vaemail.fr"
+
+
+class VaEmailError(Exception):
+    """Erreur rendue par l'API.
+
+    Porte ce qu'un appelant doit savoir pour décider : le code, l'action
+    corrective proposée, et si le même appel peut aboutir plus tard. Une
+    exception qui ne dit que « erreur 422 » oblige à lire la documentation ;
+    celle-ci porte la suite.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "UNKNOWN",
+        status: int | None = None,
+        resolution: dict[str, Any] | None = None,
+        retryable: bool = False,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.resolution = resolution or {}
+        self.retryable = retryable
+        self.body = body
+
+    def for_agent(self) -> str:
+        """Le motif, l'action corrective et s'il faut réessayer, en clair."""
+        lignes = [f"{self.code}: {self}"]
+
+        action = self.resolution.get("action")
+        if action:
+            endpoint = self.resolution.get("endpoint")
+            lignes.append(
+                f"Action corrective : {action}" + (f" ({endpoint})" if endpoint else "")
+            )
+
+        lignes.append(
+            "Le même appel peut aboutir plus tard."
+            if self.retryable
+            else "Réessayer à l'identique ne changera rien."
+        )
+
+        return "\n".join(lignes)
+
+
+class VaEmail:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 30.0,
+        opener: Any = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        # Injectable pour les tests : on ne veut pas d'appel réseau dans une
+        # suite de tests, et on ne veut pas non plus d'une dépendance de test.
+        self._opener = opener or urllib.request.urlopen
+
+    # -- transport ---------------------------------------------------------
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        url = self.base_url + path
+
+        propres = {k: v for k, v in (query or {}).items() if v not in (None, "")}
+        if propres:
+            url += "?" + urllib.parse.urlencode(propres)
+
+        entetes = {"Accept": "application/json"}
+        if self.api_key:
+            entetes["api-key"] = self.api_key
+        if idempotency_key:
+            entetes["Idempotency-Key"] = idempotency_key
+
+        donnees = None
+        if body is not None:
+            donnees = json.dumps(body).encode("utf-8")
+            entetes["Content-Type"] = "application/json"
+
+        requete = urllib.request.Request(url, data=donnees, headers=entetes, method=method)
+
+        try:
+            with self._opener(requete, timeout=self.timeout) as reponse:
+                brut = reponse.read().decode("utf-8") or "{}"
+                charge = json.loads(brut)
+        except urllib.error.HTTPError as erreur:
+            brut = erreur.read().decode("utf-8") or "{}"
+            try:
+                charge = json.loads(brut)
+            except json.JSONDecodeError:
+                charge = {}
+            raise self._erreur(charge, erreur.code) from None
+
+        # Une réponse 200 peut porter une erreur applicative : on la lève aussi,
+        # sinon l'appelant croit avoir réussi.
+        if isinstance(charge, dict) and charge.get("error"):
+            raise self._erreur(charge, 200)
+
+        return charge
+
+    @staticmethod
+    def _erreur(charge: Any, status: int) -> VaEmailError:
+        details = charge.get("error", {}) if isinstance(charge, dict) else {}
+
+        return VaEmailError(
+            details.get("message") or f"Erreur HTTP {status}.",
+            code=details.get("code", "UNKNOWN"),
+            status=status,
+            resolution=details.get("resolution"),
+            retryable=bool(details.get("retryable")),
+            body=charge,
+        )
+
+    # -- API ---------------------------------------------------------------
+
+    def capabilities(self) -> Any:
+        return self._call("GET", "/api/v1/capabilities")
+
+    def health(self) -> Any:
+        return self._call("GET", "/api/v1/health")
+
+    def send(self, message: dict[str, Any], idempotency_key: str | None = None) -> Any:
+        """Envoie un message. `idempotency_key` rend l'appel rejouable sans doublon 24 h."""
+        return self._call(
+            "POST", "/api/v1/transactional/send", body=message, idempotency_key=idempotency_key
+        )
+
+    def validate(self, message: dict[str, Any]) -> Any:
+        """Essai à blanc : mêmes contrôles que l'envoi, rien ne part."""
+        return self._call("POST", "/api/v1/messages/validate", body=message)
+
+    def get_message(self, message_id: str | int) -> Any:
+        return self._call("GET", f"/api/v1/messages/{urllib.parse.quote(str(message_id))}")
+
+    def list_messages(self, **filters: Any) -> Any:
+        return self._call("GET", "/api/v1/messages", query=filters)
+
+    def list_domains(self) -> Any:
+        return self._call("GET", "/api/v1/domains")
+
+    def add_domain(
+        self,
+        domain: str,
+        *,
+        selector: str | None = None,
+        dkim_tokens: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        """Déclare un domaine d'envoi.
+
+        `dkim_tokens` sont les trois valeurs données par SES à la création de
+        l'identité de domaine. Sans elles, la partie DKIM du guide DNS rendu est
+        un marqueur et le domaine ne peut pas être terminé sans intervention.
+        """
+        corps: dict[str, Any] = {"domain": domain}
+        if selector:
+            corps["dkim_selector"] = selector
+        if dkim_tokens:
+            corps["dkim_tokens"] = list(dkim_tokens)
+
+        return self._call("POST", "/api/v1/domains", body=corps, idempotency_key=idempotency_key)
+
+    def verify_domain(self, domain: str, selector: str | None = None) -> Any:
+        corps: dict[str, Any] = {"domain": domain}
+        if selector:
+            corps["dkim_selector"] = selector
+
+        return self._call("POST", "/api/v1/domains/verify", body=corps)
+
+    def dns_records(self, domain: str) -> Any:
+        return self._call("GET", f"/api/v1/domains/{urllib.parse.quote(domain)}/dns")
+
+    def diagnose_deliverability(self, domain: str) -> Any:
+        return self._call("GET", "/api/v1/deliverability/diagnose", query={"domain": domain})
+
+    def list_suppressions(self, **filters: Any) -> Any:
+        return self._call("GET", "/api/v1/suppressions", query=filters)
+
+    def usage(self) -> Any:
+        return self._call("GET", "/api/v1/usage")
+
+    def audit_logs(self, **filters: Any) -> Any:
+        return self._call("GET", "/api/v1/audit-logs", query=filters)

vaemail-1.0.0/vaemail.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: vaemail
+Version: 1.0.0
+Summary: Email infrastructure for AI agents and applications: send transactional email, authenticate sending domains, track delivery, diagnose deliverability.
+Author: VaEmail (Agence SW)
+License: MIT
+Project-URL: Homepage, https://vaemail.fr/agents
+Project-URL: Documentation, https://vaemail.fr/docs/api
+Project-URL: Source, https://github.com/vaemail/vaemail-python
+Keywords: email,email-api,transactional-email,ai-agent,agent,deliverability,sdk,vaemail,eu
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# vaemail — Python SDK
+
+Email infrastructure for AI agents and applications. Send transactional email,
+authenticate sending domains, track delivery, and diagnose deliverability.
+
+No dependencies: the SDK uses only the standard library, so it installs without
+pulling anything behind it.
+
+```bash
+pip install vaemail
+```
+
+## Send an email
+
+```python
+from vaemail import VaEmail
+
+client = VaEmail(api_key="your-api-key")
+
+client.send({
+    "to": "customer@example.com",
+    "subject": "Your order is on its way",
+    "html": "<p>Tracking number: 1Z999</p>",
+}, idempotency_key="order-4711")
+```
+
+The idempotency key makes the call safe to replay for 24 hours: retrying after a
+timeout will not send a second email.
+
+## Try before sending
+
+```python
+client.validate({"to": "customer@example.com", "subject": "Hi", "html": "<p>Hi</p>"})
+```
+
+Same checks as a real send — key scope, quotas, sending domain, suppression
+list — but nothing leaves. Useful when an agent builds a message on its own.
+
+## Authenticate a sending domain
+
+```python
+result = client.add_domain("news.example.com", dkim_tokens=["aaa111", "bbb222", "ccc333"])
+
+for record in result["data"]["dns_records"]:
+    if record["publishable"]:
+        print(record["type"], record["host"], "->", record["value"])
+```
+
+The three DKIM tokens come from Amazon SES when the domain identity is created.
+Every record says whether it is `publishable` as-is: a value that still depends
+on something unknown is flagged instead of being handed over, so an agent never
+publishes a record that would break the domain's authentication.
+
+## Errors say what to do next
+
+```python
+from vaemail import VaEmailError
+
+try:
+    client.send({"to": "customer@example.com"})
+except VaEmailError as error:
+    print(error.code)        # DOMAIN_NOT_VERIFIED
+    print(error.retryable)   # False
+    print(error.for_agent()) # reason, corrective action, whether to retry
+```
+
+## Everything else
+
+`capabilities()`, `health()`, `get_message()`, `list_messages()`,
+`list_domains()`, `verify_domain()`, `dns_records()`,
+`diagnose_deliverability()`, `list_suppressions()`, `usage()`, `audit_logs()`.
+
+Full API reference: <https://vaemail.fr/docs/api>
+
+## Tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+MIT licensed.

vaemail-1.0.0/vaemail.egg-info/SOURCES.txt

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

vaemail-1.0.0/vaemail.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vaemail-1.0.0/vaemail.egg-info/top_level.txt

@@ -0,0 +1 @@
+vaemail