mailtea 0.1.2__py3-none-any.whl

mailtea/__init__.py

@@ -0,0 +1,7 @@
+"""Mailtea Python SDK — send, schedule, and manage email from your app or AI agent."""
+
+from .client import Mailtea
+from .errors import MailteaError
+
+__all__ = ["Mailtea", "MailteaError"]
+__version__ = "0.1.2"

mailtea/_resource.py

@@ -0,0 +1,54 @@
+"""Shared helpers for resource classes: payload merging, query strings, and
+attribute-access response wrapping."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+
+def body(params: Optional[Dict[str, Any]], kwargs: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge a positional wire-format dict with keyword arguments.
+
+    Every method accepts either style (or both — kwargs win on conflict)::
+
+        mailtea.emails.send({"from": "a@b.c", "subject": "Hi"})
+        mailtea.emails.send(from_="a@b.c", subject="Hi")
+
+    A single trailing underscore is stripped from kwarg names so Python
+    reserved words can be used (``from_`` becomes ``"from"`` on the wire).
+    """
+    merged = dict(params or {})
+    for key, value in kwargs.items():
+        merged[key[:-1] if key.endswith("_") else key] = value
+    return merged
+
+
+def query(params: Optional[Dict[str, Any]]) -> str:
+    """Render a query string from a dict, dropping ``None`` values."""
+    if not params:
+        return ""
+    clean = {key: value for key, value in params.items() if value is not None}
+    return ("?" + urlencode(clean)) if clean else ""
+
+
+class Resource(dict):
+    """An API response: a plain dict that also allows attribute access, so
+    both ``email["id"]`` and ``email.id`` work. Nested dicts/lists are wrapped
+    on access. Keys that collide with dict methods (``get``, ``items``, …)
+    are only reachable via ``[...]`` indexing.
+    """
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return wrap(self[name])
+        except KeyError:
+            raise AttributeError(name) from None
+
+
+def wrap(value: Any) -> Any:
+    if isinstance(value, dict):
+        return Resource(value)
+    if isinstance(value, list):
+        return [wrap(item) for item in value]
+    return value

mailtea/_transport.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from typing import Callable, Dict, Iterable, NamedTuple, Optional, Tuple
+
+
+class HttpResponse(NamedTuple):
+    status: int
+    headers: Dict[str, str]
+    text: str
+
+
+# (method, url, headers, body) -> HttpResponse. Injectable so tests need no network.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes]], HttpResponse]
+
+
+def _lower_headers(items: Iterable[Tuple[str, str]]) -> Dict[str, str]:
+    return {key.lower(): value for key, value in items}
+
+
+def urllib_transport(
+    method: str, url: str, headers: Dict[str, str], body: Optional[bytes]
+) -> HttpResponse:
+    """Default transport built on the standard library — no third-party deps."""
+    request = urllib.request.Request(url=url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request) as response:  # noqa: S310 (trusted base URL)
+            return HttpResponse(
+                response.status,
+                _lower_headers(response.headers.items()),
+                response.read().decode("utf-8"),
+            )
+    except urllib.error.HTTPError as error:
+        text = error.read().decode("utf-8") if error.fp is not None else ""
+        return HttpResponse(error.code, _lower_headers(error.headers.items()), text)

mailtea/api_keys.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body
+
+RequestFn = Callable[..., Any]
+
+
+class ApiKeys:
+    """The ``api_keys`` resource. Access via ``mailtea.api_keys``.
+
+    Requires a token with ``settings:write``. A key can never be granted scopes
+    the calling token does not already hold.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Create an API key. The ``token`` is returned ONCE — store it securely.
+
+        Takes ``name``, optional ``permission`` (``"full_access"`` or
+        ``"sending_access"``), and optional ``domain_id``. Accepts a
+        wire-format dict, keyword arguments, or both.
+        """
+        return self._request("POST", "/v1/api-keys", _body(params, kwargs))
+
+    def list(self) -> Dict[str, Any]:
+        """List API keys (token values are never returned)."""
+        return self._request("GET", "/v1/api-keys")
+
+    def revoke(self, id: str) -> Any:
+        """Revoke (delete) an API key by id."""
+        return self._request("DELETE", "/v1/api-keys/" + quote(str(id), safe=""))

mailtea/client.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Optional
+
+from ._resource import wrap as _wrap
+from ._transport import Transport, urllib_transport
+from .api_keys import ApiKeys
+from .contact_properties import ContactProperties
+from .contacts import Contacts
+from .domains import Domains
+from .emails import Emails
+from .errors import MailteaError
+from .posts import Posts
+from .segments import Segments
+from .tags import Tags
+from .webhooks import Webhooks
+
+DEFAULT_BASE_URL = "https://api.mailtea.app"
+
+
+class Mailtea:
+    """The Mailtea client.
+
+    >>> from mailtea import Mailtea
+    >>> mailtea = Mailtea(os.environ["MAILTEA_API_KEY"])
+    >>> sent = mailtea.emails.send(
+    ...     from_="you@yourdomain.com",
+    ...     to="recipient@example.com",
+    ...     subject="Hello",
+    ...     html="<p>Sent with Mailtea.</p>",
+    ... )
+    >>> sent.id  # responses allow attribute and ["..."] access alike
+
+    Payloads may equally be passed as a single wire-format dict
+    (``send({"from": ..., "to": ...})``) — both styles hit the same endpoint.
+
+    The API key may be passed explicitly or read from ``MAILTEA_API_KEY``.
+    Self-hosting/local dev: pass ``base_url`` or set ``MAILTEA_API_BASE_URL``.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        key = api_key or os.environ.get("MAILTEA_API_KEY")
+        if not key:
+            raise MailteaError(
+                "Missing Mailtea API key. Pass it to Mailtea(api_key) or set the "
+                "MAILTEA_API_KEY environment variable.",
+                code="missing_api_key",
+            )
+        self._api_key = key
+        self._base_url = (
+            base_url or os.environ.get("MAILTEA_API_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self._transport: Transport = transport or urllib_transport
+
+        self.emails = Emails(self._request)
+        self.contacts = Contacts(self._request)
+        self.posts = Posts(self._request)
+        self.segments = Segments(self._request)
+        self.tags = Tags(self._request)
+        self.domains = Domains(self._request)
+        self.webhooks = Webhooks(self._request)
+        self.contact_properties = ContactProperties(self._request)
+        self.api_keys = ApiKeys(self._request)
+
+    def _request(self, method: str, path: str, body: Any = None) -> Any:
+        url = self._base_url + path
+        headers = {"Authorization": "Bearer " + self._api_key}
+        data: Optional[bytes] = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+
+        response = self._transport(method, url, headers, data)
+        request_id = response.headers.get("x-request-id")
+
+        if response.status >= 400:
+            message = "HTTP {0}".format(response.status)
+            details = None
+            try:
+                parsed = json.loads(response.text)
+                if isinstance(parsed, dict):
+                    message = parsed.get("error") or message
+                    details = parsed.get("details")
+            except ValueError:
+                pass  # non-JSON body — keep the status-line message
+            raise MailteaError(
+                message, status=response.status, details=details, request_id=request_id
+            )
+
+        if response.status == 204 or not response.text:
+            return None
+        # Responses are dicts that also allow attribute access
+        # (email["id"] and email.id both work).
+        return _wrap(json.loads(response.text))

mailtea/contact_properties.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body, query as _query
+
+RequestFn = Callable[..., Any]
+
+
+class ContactProperties:
+    """The ``contact_properties`` resource (custom contact fields). Access via
+    ``mailtea.contact_properties``.
+
+    Definitions are team-scoped — there is no ``publication_id``. ``create``
+    takes ``key`` and ``type`` (``"string"`` or ``"number"``). Every method
+    accepts the payload as a wire-format dict, as keyword arguments, or both.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("POST", "/v1/contact-properties", _body(params, kwargs))
+
+    def list(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("GET", "/v1/contact-properties" + _query(_body(params, kwargs)))
+
+    def update(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "PATCH", "/v1/contact-properties/" + quote(str(id), safe=""), _body(params, kwargs)
+        )
+
+    def delete(self, id: str) -> Dict[str, Any]:
+        return self._request(
+            "DELETE", "/v1/contact-properties/" + quote(str(id), safe="")
+        )

mailtea/contacts.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body, query as _query
+
+RequestFn = Callable[..., Any]
+
+
+class Contacts:
+    """The ``contacts`` resource. Access via ``mailtea.contacts``.
+
+    Audience resources are scoped to a publication — pass ``publication_id``.
+    Every method accepts the payload as a wire-format dict, as keyword
+    arguments, or both.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Create a contact — or update it if the email already exists in the
+        publication (the endpoint upserts). :meth:`upsert` is the same call."""
+        return self._request("POST", "/v1/contacts", _body(params, kwargs))
+
+    def upsert(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Create the contact or update it in place — alias of :meth:`create`,
+        named for what ``POST /v1/contacts`` actually does."""
+        return self.create(params, **kwargs)
+
+    def list(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("GET", "/v1/contacts" + _query(_body(params, kwargs)))
+
+    def get(self, id_or_email: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "GET",
+            "/v1/contacts/" + quote(str(id_or_email), safe="") + _query(_body(params, kwargs)),
+        )
+
+    def update(self, id_or_email: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        merged = _body(params, kwargs)
+        return self._request(
+            "PATCH",
+            "/v1/contacts/"
+            + quote(str(id_or_email), safe="")
+            + _query({"publication_id": merged.get("publication_id")}),
+            merged,
+        )
+
+    def delete(self, id_or_email: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "DELETE",
+            "/v1/contacts/" + quote(str(id_or_email), safe="") + _query(_body(params, kwargs)),
+        )

mailtea/domains.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body, query as _query
+
+RequestFn = Callable[..., Any]
+
+
+class Domains:
+    """The ``domains`` resource (email/site sending domains). Access via
+    ``mailtea.domains``.
+
+    Scoped to a publication — pass ``publication_id``. Register a domain, add the
+    returned DNS ``records``, then :meth:`verify` it before sending from it.
+    Every method accepts the payload as a wire-format dict, as keyword
+    arguments, or both.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+        #: Tracking sub-domains (CNAME) under a domain.
+        self.tracking = TrackingDomains(request)
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Register a domain. The response ``records`` lists the DNS records to add."""
+        return self._request("POST", "/v1/domains", _body(params, kwargs))
+
+    def list(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("GET", "/v1/domains" + _query(_body(params, kwargs)))
+
+    def get(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "GET", "/v1/domains/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )
+
+    def verify(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Verify a domain via its DNS records; ``status`` becomes ``"verified"``."""
+        return self._request(
+            "POST",
+            "/v1/domains/" + quote(str(id), safe="") + "/verify" + _query(_body(params, kwargs)),
+        )
+
+    def update(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        merged = _body(params, kwargs)
+        return self._request(
+            "PATCH",
+            "/v1/domains/"
+            + quote(str(id), safe="")
+            + _query({"publication_id": merged.get("publication_id")}),
+            merged,
+        )
+
+    def delete(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "DELETE", "/v1/domains/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )
+
+
+class TrackingDomains:
+    """Tracking sub-domains (CNAME) under a domain — used to serve open-pixel
+    and click-tracking links from your own domain. Access via
+    ``mailtea.domains.tracking``.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, domain_id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Add a tracking sub-domain. Takes ``publication_id`` and ``subdomain``.
+        The response ``records`` lists the CNAME to add."""
+        merged = _body(params, kwargs)
+        return self._request(
+            "POST",
+            "/v1/domains/"
+            + quote(str(domain_id), safe="")
+            + "/tracking-domains"
+            + _query({"publication_id": merged.get("publication_id")}),
+            {"subdomain": merged.get("subdomain")},
+        )
+
+    def list(self, domain_id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "GET",
+            "/v1/domains/"
+            + quote(str(domain_id), safe="")
+            + "/tracking-domains"
+            + _query(_body(params, kwargs)),
+        )
+
+    def verify(
+        self,
+        domain_id: str,
+        tracking_domain_id: str,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        return self._request(
+            "POST",
+            "/v1/domains/"
+            + quote(str(domain_id), safe="")
+            + "/tracking-domains/"
+            + quote(str(tracking_domain_id), safe="")
+            + "/verify"
+            + _query(_body(params, kwargs)),
+        )
+
+    def delete(
+        self,
+        domain_id: str,
+        tracking_domain_id: str,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        return self._request(
+            "DELETE",
+            "/v1/domains/"
+            + quote(str(domain_id), safe="")
+            + "/tracking-domains/"
+            + quote(str(tracking_domain_id), safe="")
+            + _query(_body(params, kwargs)),
+        )

mailtea/emails.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Union
+from urllib.parse import quote
+
+from ._resource import body as _body, query as _query
+
+RequestFn = Callable[..., Any]
+Recipients = Union[str, List[str]]
+
+
+class Emails:
+    """The ``emails`` resource. Access via ``mailtea.emails``.
+
+    Every method accepts the payload as a wire-format dict, as keyword
+    arguments, or both (snake_case keys like ``reply_to``; use ``from_=`` as
+    the keyword form of ``"from"``).
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def send(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Send a transactional email. Provide ``html``/``text`` OR a ``template``.
+
+        >>> mailtea.emails.send(from_="a@b.co", to="c@d.co", subject="Hi", html="<p>Hi</p>")
+
+        Returns ``{"id": ...}``.
+        """
+        return self._request("POST", "/v1/emails", _body(params, kwargs))
+
+    def batch(self, emails: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Send up to 100 emails in one request. Returns ``{"data": [{"id": ...}]}``."""
+        return self._request("POST", "/v1/emails/batch", emails)
+
+    def get(self, id: str) -> Dict[str, Any]:
+        """Retrieve an email with its delivery status and tracking counters.
+
+        Adds a friendly ``status`` alias of the raw ``last_event`` wire field.
+        """
+        email = self._request("GET", "/v1/emails/" + quote(str(id), safe=""))
+        if isinstance(email, dict) and email.get("status") is None:
+            email["status"] = email.get("last_event")
+        return email
+
+    def list(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """List emails (most recent first). Optional filters: ``status``, ``tag_name``,
+        ``tag_value``, ``from_date``, ``to_date``, ``limit``, ``offset``."""
+        return self._request("GET", "/v1/emails" + _query(_body(params, kwargs)))
+
+    def update(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Update a scheduled email (currently only ``scheduled_at``)."""
+        return self._request(
+            "PATCH", "/v1/emails/" + quote(str(id), safe=""), _body(params, kwargs)
+        )
+
+    def reschedule(self, id: str, scheduled_at: str) -> Dict[str, Any]:
+        """Convenience wrapper over :meth:`update` for the reschedule case."""
+        return self.update(id, {"scheduled_at": scheduled_at})
+
+    def cancel(self, id: str) -> Dict[str, Any]:
+        """Cancel a scheduled email before it sends."""
+        return self._request("POST", "/v1/emails/" + quote(str(id), safe="") + "/cancel")

mailtea/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MailteaError(Exception):
+    """Raised when the Mailtea API returns an error or the client is misconfigured.
+
+    Attributes:
+        status: HTTP status code (0 for client-side errors).
+        code: machine-readable code for client-side errors (e.g. ``missing_api_key``).
+        details: validation issue list returned by the API, if any.
+        request_id: the API's ``x-request-id`` for support/debugging.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: Optional[str] = None,
+        details: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.details = details
+        self.request_id = request_id

mailtea/posts.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body
+
+RequestFn = Callable[..., Any]
+
+
+class Posts:
+    """The ``posts`` resource (newsletter posts/issues). Access via ``mailtea.posts``.
+
+    Every method accepts the payload as a wire-format dict, as keyword
+    arguments, or both (snake_case keys like ``reply_to``; use ``from_=`` as
+    the keyword form of ``"from"``).
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Create a newsletter post (draft by default). Seed it from a published
+        server template with ``template_id`` + ``variables``, or pass inline
+        ``html``. Set ``send=True`` to deliver right after creating (or with
+        ``scheduled_at`` to schedule) — that requires the ``issues:send`` scope.
+
+        Returns ``{"id": ...}``.
+        """
+        return self._request("POST", "/v1/posts", _body(params, kwargs))
+
+    def send(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Send a draft post to the publication's audience — immediately, or at
+        ``scheduled_at`` (ISO 8601) if given. Requires the ``issues:send`` scope.
+        """
+        merged = _body(params, kwargs)
+        return self._request(
+            "POST", "/v1/posts/" + quote(str(id), safe="") + "/send", merged or None
+        )
+
+    def send_test(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        """Send a TEST copy of a post to specific recipients to check it before
+        subscribers see it. Renders the post exactly as a subscriber would receive
+        it and delivers a one-shot ``[TEST]`` email — it does NOT send to the
+        audience.
+
+        Takes ``recipients`` (up to 10), ``from`` (must use a verified domain),
+        and optional ``reply_to``. Returns ``{"sent_to": [...], "failed_to": [...]}``.
+        """
+        return self._request(
+            "POST", "/v1/posts/" + quote(str(id), safe="") + "/test", _body(params, kwargs)
+        )

mailtea/segments.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body, query as _query
+
+RequestFn = Callable[..., Any]
+
+
+class Segments:
+    """The ``segments`` resource. Access via ``mailtea.segments``.
+
+    Audience segments are scoped to a publication — pass ``publication_id``.
+    Every method accepts the payload as a wire-format dict, as keyword
+    arguments, or both. To clear a nullable filter on update, pass ``None``
+    (e.g. ``status_filter=None``); omit the key to leave it unchanged.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("POST", "/v1/segments", _body(params, kwargs))
+
+    def list(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("GET", "/v1/segments" + _query(_body(params, kwargs)))
+
+    def get(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "GET", "/v1/segments/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )
+
+    def update(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        merged = _body(params, kwargs)
+        return self._request(
+            "PATCH",
+            "/v1/segments/"
+            + quote(str(id), safe="")
+            + _query({"publication_id": merged.get("publication_id")}),
+            merged,
+        )
+
+    def delete(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "DELETE", "/v1/segments/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )

mailtea/tags.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body, query as _query
+
+RequestFn = Callable[..., Any]
+
+
+class Tags:
+    """The ``tags`` resource (tag definitions). Access via ``mailtea.tags``.
+
+    Tags are scoped to a publication — pass ``publication_id``. ``create``
+    requires ``default_subscription`` (``"opt_in"`` or ``"opt_out"``). This
+    manages tag definitions only; assigning tags to contacts is not yet exposed.
+    Every method accepts the payload as a wire-format dict, as keyword
+    arguments, or both.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("POST", "/v1/tags", _body(params, kwargs))
+
+    def list(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("GET", "/v1/tags" + _query(_body(params, kwargs)))
+
+    def get(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "GET", "/v1/tags/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )
+
+    def update(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        merged = _body(params, kwargs)
+        return self._request(
+            "PATCH",
+            "/v1/tags/"
+            + quote(str(id), safe="")
+            + _query({"publication_id": merged.get("publication_id")}),
+            merged,
+        )
+
+    def delete(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "DELETE", "/v1/tags/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )

mailtea/webhooks.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote
+
+from ._resource import body as _body, query as _query
+
+RequestFn = Callable[..., Any]
+
+_BASE = "/v1/webhooks/endpoints"
+
+
+class Webhooks:
+    """The ``webhooks`` resource (outbound event subscriptions). Access via
+    ``mailtea.webhooks``.
+
+    Scoped to a publication — pass ``publication_id``. ``create`` returns the
+    ``signing_secret`` once; store it to verify payload signatures.
+    Every method accepts the payload as a wire-format dict, as keyword
+    arguments, or both.
+    """
+
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("POST", _BASE, _body(params, kwargs))
+
+    def list(self, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("GET", _BASE + _query(_body(params, kwargs)))
+
+    def get(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "GET", _BASE + "/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )
+
+    def update(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        merged = _body(params, kwargs)
+        return self._request(
+            "PATCH",
+            _BASE
+            + "/"
+            + quote(str(id), safe="")
+            + _query({"publication_id": merged.get("publication_id")}),
+            merged,
+        )
+
+    def delete(self, id: str, params: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        return self._request(
+            "DELETE", _BASE + "/" + quote(str(id), safe="") + _query(_body(params, kwargs))
+        )

mailtea-0.1.2.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: mailtea
+Version: 0.1.2
+Summary: Mailtea Python SDK — send, schedule, and manage email from your app or AI agent.
+Project-URL: Homepage, https://mailtea.app
+Project-URL: Documentation, https://docs.mailtea.app
+Project-URL: Repository, https://github.com/mailtea-app/mailtea-python
+Author: Mailtea
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,email,mailtea,sdk,transactional-email
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# mailtea (Python)
+
+The official Python SDK for [Mailtea](https://mailtea.app) — a thin, zero-dependency
+wrapper over the [REST API](https://api.mailtea.app). Python 3.9+.
+
+## Install
+
+```bash
+pip install mailtea
+```
+
+## Usage
+
+```python
+import os
+from mailtea import Mailtea
+
+mailtea = Mailtea(os.environ["MAILTEA_API_KEY"])
+
+sent = mailtea.emails.send(
+    from_="you@yourdomain.com",
+    to="recipient@example.com",
+    subject="Hello from Mailtea",
+    html="<p>Your first email, sent with <strong>Mailtea</strong>.</p>",
+)
+print(sent.id)
+
+email = mailtea.emails.get(sent.id)
+print(email.status)
+```
+
+The API key can be passed to `Mailtea(api_key)` or read from `MAILTEA_API_KEY`.
+Self-hosting or local dev? pass `base_url=` or set `MAILTEA_API_BASE_URL`.
+
+Every method equally accepts a single wire-format dict — handy when you already
+hold the JSON payload:
+
+```python
+sent = mailtea.emails.send({
+    "from": "you@yourdomain.com",
+    "to": "recipient@example.com",
+    "subject": "Hello from Mailtea",
+    "html": "<p>Your first email, sent with <strong>Mailtea</strong>.</p>",
+})
+print(sent["id"])  # responses support ["..."] and attribute access alike
+```
+
+Keyword arguments use snake_case wire names; a trailing underscore escapes
+Python reserved words (`from_=` → `"from"`).
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `emails.send(params)` | Send a transactional email → `{"id": ...}` |
+| `emails.batch(emails)` | Send up to 100 emails → `{"data": [{"id": ...}]}` |
+| `emails.get(id)` | Retrieve an email and its delivery status |
+| `emails.list(params=None)` | List emails → `{"data", "total", "limit", "offset", "has_more"}` |
+| `emails.update(id, params)` | Reschedule a scheduled email |
+| `emails.reschedule(id, scheduled_at)` | Convenience wrapper over `update` |
+| `emails.cancel(id)` | Cancel a scheduled email |
+| `contacts.create / upsert / list / get / update / delete` | Manage audience contacts (`upsert` = `create`; the endpoint upserts) |
+| `posts.create(...)` | Create a newsletter post (draft, or `send=True`) → `{"id": ...}` |
+| `posts.send(id, scheduled_at=None)` | Send a draft post to the audience, now or scheduled |
+| `posts.send_test(id, params)` | Send a `[TEST]` copy of a post → `{"sent_to", "failed_to"}` |
+| `segments.create / list / get / update / delete` | Manage audience segments |
+| `tags.create / list / get / update / delete` | Manage tag definitions |
+| `domains.create / list / get / verify / update / delete` | Manage sending domains (add, read DNS records, verify) |
+| `domains.tracking.create / list / verify / delete` | Manage CNAME tracking sub-domains under a domain |
+| `webhooks.create / list / get / update / delete` | Manage outbound event subscriptions |
+| `contact_properties.create / list / update / delete` | Manage custom contact fields (team-scoped) |
+| `api_keys.create / list / revoke` | Manage API keys (`settings:write`) |
+
+Payloads follow the REST wire format (`reply_to`, `scheduled_at`, …), passed as
+keyword arguments or a plain dict. Errors raise `MailteaError` with `status`,
+`details`, and `request_id`.
+
+## Develop
+
+```bash
+cd sdks/python
+python3 -m unittest discover -s tests -t .
+```

mailtea-0.1.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+mailtea/__init__.py,sha256=cS4H6DPaM6sBvoEy3zYedMgxMXBhc7gGfQq-Z5w8bc8,212
+mailtea/_resource.py,sha256=_QVaREujr5w1HtTvFaMlQAyqJUreZ6sHRiLE26nC4d4,1850
+mailtea/_transport.py,sha256=FHXx6bsdNcgbPs1LRIaBfWRfTmzoyWBFfQQqSdcFOiM,1321
+mailtea/api_keys.py,sha256=VTXPKFB8r4iAgcOUuxzIJAlUMJ11jrBRqp66pQIwpCk,1275
+mailtea/client.py,sha256=L_PuxEwSbqAQhCzJ6nXKoyXoU2eCqYKBgthra6XXq98,3694
+mailtea/contact_properties.py,sha256=WX1xJ7ylZMkgc1d1DKQ-Vhkzk5dANNG_awWDWcMDwsc,1450
+mailtea/contacts.py,sha256=JFLk8DQ85T7PSaBfn_AORrR6AWaH4y_NYdQQ2XpfBek,2277
+mailtea/domains.py,sha256=wM4X7Ve3kVw31wR7GvJsXjKydHHOGWiD7xvA7dpBGlI,4527
+mailtea/emails.py,sha256=6trMltSTmPiI_o7VvRV-Kwbxv-n5fBleskI07vD7AC4,2720
+mailtea/errors.py,sha256=DRvwEFoSuuRdP_Cb28GZYBpBKTYFWwUqbVLUh6Tb0fA,897
+mailtea/posts.py,sha256=MMI-jk_05lRgpUbJZpMRrHkghYbXuHBQ5BNCZAmhASg,2227
+mailtea/segments.py,sha256=EyMp6hlOaCfT_WmugLy91YiZ2SmNbUa53RBIbClMdWA,1873
+mailtea/tags.py,sha256=zhG7w78scWVPgFSyKnIXzMeOXjxpBWBhG7hsnJ9qwIU,1891
+mailtea/webhooks.py,sha256=rO6IM0ywZuQ0spKOw0ccy_lMsMtrDH4GhbJNJLz6wl0,1870
+mailtea-0.1.2.dist-info/METADATA,sha256=carXUrSEQ6a-jmkFG7jxkuSX5LdvLNSkhZlcZdadjq4,3827
+mailtea-0.1.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mailtea-0.1.2.dist-info/licenses/LICENSE,sha256=mPPPljFBnTeFwc4OnW9TdnHIIjrqgDTtBsSVxC4McE4,1064
+mailtea-0.1.2.dist-info/RECORD,,

mailtea-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mailtea-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailtea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.