eusend 0.1.0__py3-none-any.whl

eusend/__init__.py

@@ -0,0 +1,72 @@
+"""Official Python SDK for the Eusend API — the EU-native transactional email platform.
+
+Configure a module-level API key, then call the resource classes directly
+(mirrors resend-python)::
+
+    import eusend
+
+    eusend.api_key = "eu_live_..."  # or set EUSEND_API_KEY
+
+    email = eusend.Emails.send({
+        "from": "Acme <you@yourdomain.com>",
+        "to": "user@example.com",
+        "subject": "Hello",
+        "html": "<p>Hello world</p>",
+    })
+    print(email["id"])
+"""
+
+import os
+from typing import Optional
+
+# Module-level configuration, read at request time.
+api_key: Optional[str] = os.environ.get("EUSEND_API_KEY")
+api_url: str = os.environ.get("EUSEND_API_URL", "https://api.eusend.dev")
+
+from eusend.version import get_version  # noqa: E402
+
+# Resource classes are imported after the config above so `import eusend`
+# inside the request layer sees an initialized module.
+from eusend.emails import Emails  # noqa: E402
+from eusend.batch import Batch  # noqa: E402
+from eusend.domains import Domains  # noqa: E402
+from eusend.api_keys import ApiKeys  # noqa: E402
+from eusend.audiences import Audiences  # noqa: E402
+from eusend.templates import Templates  # noqa: E402
+from eusend.webhooks import Webhooks  # noqa: E402
+from eusend.broadcasts import Broadcasts  # noqa: E402
+
+from eusend.exceptions import (  # noqa: E402
+    ApplicationError,
+    EusendError,
+    InvalidApiKeyError,
+    MissingApiKeyError,
+    NoContentError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+__version__ = get_version()
+
+__all__ = [
+    "api_key",
+    "api_url",
+    "Emails",
+    "Batch",
+    "Domains",
+    "ApiKeys",
+    "Audiences",
+    "Templates",
+    "Webhooks",
+    "Broadcasts",
+    "EusendError",
+    "ApplicationError",
+    "InvalidApiKeyError",
+    "MissingApiKeyError",
+    "NoContentError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "__version__",
+]

eusend/_compat.py

@@ -0,0 +1,15 @@
+"""Typing-helper compatibility shim.
+
+``NotRequired`` landed in the stdlib ``typing`` in Python 3.11; on 3.8–3.10 it
+lives in ``typing_extensions``. Import these names from here so callers don't
+need to care.
+"""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import Literal, NotRequired, TypedDict
+else:  # pragma: no cover
+    from typing_extensions import Literal, NotRequired, TypedDict
+
+__all__ = ["TypedDict", "NotRequired", "Literal"]

eusend/_response.py

@@ -0,0 +1,19 @@
+from typing import Any, Dict
+
+from eusend._util import normalize
+
+
+class ResponseDict(dict):
+    """A dict response with the HTTP response headers attached at ``.headers``."""
+
+    headers: Dict[str, str]
+
+
+def to_response(data: Any, headers: Dict[str, str]) -> Any:
+    """Normalize response keys to snake_case; wrap dicts so ``resp["id"]`` works."""
+    data = normalize(data)
+    if isinstance(data, dict):
+        resp = ResponseDict(data)
+        resp.headers = headers
+        return resp
+    return data

eusend/_util.py

@@ -0,0 +1,58 @@
+import base64
+import re
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+_CAMEL_BOUNDARY = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def to_snake(key: str) -> str:
+    return _CAMEL_BOUNDARY.sub("_", key).lower()
+
+
+def normalize(obj: Any) -> Any:
+    """Recursively convert response keys from camelCase to snake_case.
+
+    The Eusend API returns camelCase for most resources but snake_case for a
+    few (API keys, pagination cursors); this collapses both into snake_case so
+    callers always use the same key style, e.g. ``email["created_at"]``.
+    """
+    if isinstance(obj, dict):
+        return {to_snake(k): normalize(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [normalize(v) for v in obj]
+    return obj
+
+
+def build_query(params: Optional[Dict[str, Any]]) -> str:
+    if not params:
+        return ""
+    q: Dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        q[key] = value
+    return "?" + urlencode(q) if q else ""
+
+
+def _encode_attachment(att: Dict[str, Any]) -> Dict[str, Any]:
+    out = dict(att)
+    content = out.get("content")
+    if isinstance(content, (bytes, bytearray)):
+        # Raw bytes are base64-encoded; a str is assumed to already be base64.
+        out["content"] = base64.b64encode(bytes(content)).decode("ascii")
+    return out
+
+
+def prepare_email_payload(params: Dict[str, Any], allow_scheduling: bool = True) -> Dict[str, Any]:
+    payload = dict(params)
+    attachments = payload.get("attachments")
+    if attachments:
+        payload["attachments"] = [_encode_attachment(a) for a in attachments]
+    if not allow_scheduling:
+        # The batch endpoint rejects attachments and scheduling.
+        payload.pop("attachments", None)
+        payload.pop("scheduled_at", None)
+    return payload

eusend/api_keys.py

@@ -0,0 +1,47 @@
+from typing import List
+
+from eusend._compat import NotRequired, TypedDict
+
+from eusend.request import Request
+
+
+class ApiKeys:
+    class CreateParams(TypedDict):
+        name: str
+        test_mode: NotRequired[bool]
+
+    class CreateResponse(TypedDict):
+        id: str
+        name: str
+        key: str
+        prefix: str
+        test_mode: bool
+        created_at: str
+
+    class ApiKey(TypedDict):
+        id: str
+        name: str
+        prefix: str
+        test_mode: bool
+        created_at: str
+        last_used_at: str
+
+    @classmethod
+    def create(cls, params: "ApiKeys.CreateParams") -> "ApiKeys.CreateResponse":
+        """Create an API key. The full ``key`` is returned only once.
+
+        Pass ``{"test_mode": True}`` for a sandbox key — its sends are accepted
+        and tracked but never delivered.
+        """
+        body = {"name": params["name"], "test_mode": params.get("test_mode", False)}
+        return Request[ApiKeys.CreateResponse](
+            path="/api-keys", params=body, verb="post"
+        ).perform_with_content()
+
+    @classmethod
+    def list(cls) -> List["ApiKeys.ApiKey"]:
+        return Request[List[ApiKeys.ApiKey]](path="/api-keys", verb="get").perform_with_content()
+
+    @classmethod
+    def remove(cls, api_key_id: str) -> None:
+        Request(path=f"/api-keys/{api_key_id}", verb="delete").perform()

eusend/audiences.py

@@ -0,0 +1,111 @@
+from typing import Any, Dict, List, Optional, cast
+
+from eusend._compat import NotRequired, TypedDict
+
+from eusend._util import build_query
+from eusend.models import Contact
+from eusend.request import Request
+
+
+class Audiences:
+    class Audience(TypedDict):
+        id: str
+        name: str
+        organization_id: str
+        created_at: str
+        updated_at: str
+
+    class AudienceListItem(TypedDict):
+        id: str
+        name: str
+        created_at: str
+        contact_count: int
+
+    class CreateContactParams(TypedDict):
+        email: str
+        first_name: NotRequired[str]
+        last_name: NotRequired[str]
+
+    class UpdateContactParams(TypedDict):
+        first_name: NotRequired[str]
+        last_name: NotRequired[str]
+        unsubscribed: NotRequired[bool]
+
+    class ListContactsParams(TypedDict):
+        limit: NotRequired[int]
+        cursor: NotRequired[str]
+        search: NotRequired[str]
+        subscribed: NotRequired[bool]
+
+    class ListContactsResponse(TypedDict):
+        data: List[Contact]
+        next_cursor: Optional[str]
+
+    class BatchCreateContactsResponse(TypedDict):
+        count: int
+
+    # --- Audiences ---------------------------------------------------------
+
+    @classmethod
+    def create(cls, name: str) -> "Audiences.Audience":
+        return Request[Audiences.Audience](
+            path="/audiences", params={"name": name}, verb="post"
+        ).perform_with_content()
+
+    @classmethod
+    def list(cls) -> List["Audiences.AudienceListItem"]:
+        resp = Request[Dict[str, Any]](path="/audiences", verb="get").perform_with_content()
+        return cast(List["Audiences.AudienceListItem"], resp["data"])
+
+    @classmethod
+    def remove(cls, audience_id: str) -> None:
+        Request(path=f"/audiences/{audience_id}", verb="delete").perform()
+
+    # --- Contacts (nested under an audience) -------------------------------
+
+    @classmethod
+    def create_contact(cls, audience_id: str, params: "Audiences.CreateContactParams") -> Contact:
+        """Add a contact to an audience, upserting on email."""
+        return Request[Contact](
+            path=f"/audiences/{audience_id}/contacts",
+            params=cast(Dict[str, Any], params),
+            verb="post",
+        ).perform_with_content()
+
+    @classmethod
+    def batch_create_contacts(
+        cls, audience_id: str, contacts: List["Audiences.CreateContactParams"]
+    ) -> "Audiences.BatchCreateContactsResponse":
+        """Upsert up to 1,000 contacts; returns the number written."""
+        return Request[Audiences.BatchCreateContactsResponse](
+            path=f"/audiences/{audience_id}/contacts/batch",
+            params={"contacts": cast(List[Any], contacts)},
+            verb="post",
+        ).perform_with_content()
+
+    @classmethod
+    def list_contacts(
+        cls, audience_id: str, params: Optional["Audiences.ListContactsParams"] = None
+    ) -> "Audiences.ListContactsResponse":
+        path = f"/audiences/{audience_id}/contacts" + build_query(cast(Optional[Dict[str, Any]], params))
+        return Request[Audiences.ListContactsResponse](path=path, verb="get").perform_with_content()
+
+    @classmethod
+    def get_contact(cls, audience_id: str, contact_id: str) -> Contact:
+        return Request[Contact](
+            path=f"/audiences/{audience_id}/contacts/{contact_id}", verb="get"
+        ).perform_with_content()
+
+    @classmethod
+    def update_contact(
+        cls, audience_id: str, contact_id: str, params: "Audiences.UpdateContactParams"
+    ) -> Contact:
+        return Request[Contact](
+            path=f"/audiences/{audience_id}/contacts/{contact_id}",
+            params=cast(Dict[str, Any], params),
+            verb="patch",
+        ).perform_with_content()
+
+    @classmethod
+    def remove_contact(cls, audience_id: str, contact_id: str) -> None:
+        Request(path=f"/audiences/{audience_id}/contacts/{contact_id}", verb="delete").perform()

eusend/batch.py

@@ -0,0 +1,35 @@
+from typing import Any, Dict, List, cast
+
+from eusend._compat import NotRequired, TypedDict
+
+from eusend._util import prepare_email_payload
+from eusend.emails import Emails
+from eusend.request import Request
+
+
+class Batch:
+    class BatchItemResult(TypedDict):
+        id: NotRequired[str]
+        error: NotRequired[str]
+        code: NotRequired[str]
+
+    class SendResponse(TypedDict):
+        data: List["Batch.BatchItemResult"]
+
+    @classmethod
+    def send(cls, params: List[Emails.SendParams]) -> "Batch.SendResponse":
+        """Send up to 100 emails in one request.
+
+        Attachments and scheduling are not supported on the batch endpoint and
+        are stripped from each item — send those individually via ``Emails.send``.
+        The result maps positionally to the input: queued items carry ``id``,
+        rejected items carry ``error`` and ``code``.
+        """
+        payload = [
+            prepare_email_payload(cast(Dict[str, Any], p), allow_scheduling=False) for p in params
+        ]
+        return Request[Batch.SendResponse](
+            path="/emails/batch",
+            params=cast(List[Any], payload),
+            verb="post",
+        ).perform_with_content()

eusend/broadcasts.py

@@ -0,0 +1,94 @@
+from typing import Any, Dict, List, Optional, cast
+
+from eusend._compat import NotRequired, TypedDict
+
+from eusend.models import Broadcast
+from eusend.request import Request
+
+# `from` is a reserved keyword, declared via functional TypedDict syntax.
+_BroadcastFrom = TypedDict("_BroadcastFrom", {"from": str})
+_BroadcastFromOpt = TypedDict("_BroadcastFromOpt", {"from": NotRequired[str]})
+
+
+class Broadcasts:
+    class CreateParams(_BroadcastFrom):
+        name: str
+        audience_id: str
+        subject: str
+        html: NotRequired[str]
+        template_id: NotRequired[str]
+        template_variables: NotRequired[Dict[str, str]]
+
+    class UpdateParams(_BroadcastFromOpt):
+        name: NotRequired[str]
+        audience_id: NotRequired[str]
+        subject: NotRequired[str]
+        html: NotRequired[str]
+        template_id: NotRequired[str]
+        template_variables: NotRequired[Dict[str, str]]
+        scheduled_at: NotRequired[str]
+
+    class SendParams(TypedDict):
+        scheduled_at: NotRequired[str]
+
+    class SendResponse(TypedDict):
+        id: str
+        status: str
+        scheduled_at: Optional[str]
+
+    class BroadcastListItem(TypedDict):
+        id: str
+        name: str
+        status: str
+        audience_id: str
+        from_address: str
+        subject: str
+        recipient_count: Optional[int]
+        sent_count: Optional[int]
+        scheduled_at: Optional[str]
+        created_at: str
+        audience_name: Optional[str]
+
+    @classmethod
+    def create(cls, params: "Broadcasts.CreateParams") -> Broadcast:
+        return Request[Broadcast](
+            path="/broadcasts", params=cast(Dict[str, Any], params), verb="post"
+        ).perform_with_content()
+
+    @classmethod
+    def list(cls) -> List["Broadcasts.BroadcastListItem"]:
+        resp = Request[Dict[str, Any]](path="/broadcasts", verb="get").perform_with_content()
+        return cast(List["Broadcasts.BroadcastListItem"], resp["data"])
+
+    @classmethod
+    def get(cls, broadcast_id: str) -> Broadcast:
+        """Get a broadcast including delivery stats."""
+        return Request[Broadcast](path=f"/broadcasts/{broadcast_id}", verb="get").perform_with_content()
+
+    @classmethod
+    def update(cls, broadcast_id: str, params: "Broadcasts.UpdateParams") -> Broadcast:
+        return Request[Broadcast](
+            path=f"/broadcasts/{broadcast_id}", params=cast(Dict[str, Any], params), verb="patch"
+        ).perform_with_content()
+
+    @classmethod
+    def send(
+        cls, broadcast_id: str, params: Optional["Broadcasts.SendParams"] = None
+    ) -> "Broadcasts.SendResponse":
+        """Send a broadcast now, or schedule it with ``{"scheduled_at": ...}``.
+        Calling send on a paused broadcast resumes it from where it stopped."""
+        return Request[Broadcasts.SendResponse](
+            path=f"/broadcasts/{broadcast_id}/send",
+            params=cast(Dict[str, Any], params or {}),
+            verb="post",
+        ).perform_with_content()
+
+    @classmethod
+    def cancel(cls, broadcast_id: str) -> Broadcast:
+        return Request[Broadcast](
+            path=f"/broadcasts/{broadcast_id}/cancel", verb="post"
+        ).perform_with_content()
+
+    @classmethod
+    def remove(cls, broadcast_id: str) -> None:
+        Request(path=f"/broadcasts/{broadcast_id}", verb="delete").perform()

eusend/domains.py

@@ -0,0 +1,45 @@
+from typing import List
+
+from eusend._compat import TypedDict
+
+from eusend.models import Domain, DnsRecord
+from eusend.request import Request
+
+
+class Domains:
+    class CreateResponse(TypedDict):
+        id: str
+        name: str
+        dkim: DnsRecord
+        spf: DnsRecord
+        dmarc: DnsRecord
+
+    class DomainListItem(TypedDict):
+        id: str
+        name: str
+        status: str
+        created_at: str
+
+    @classmethod
+    def create(cls, name: str) -> "Domains.CreateResponse":
+        """Add a domain and return the DNS records to publish."""
+        return Request[Domains.CreateResponse](
+            path="/domains", params={"name": name}, verb="post"
+        ).perform_with_content()
+
+    @classmethod
+    def list(cls) -> List["Domains.DomainListItem"]:
+        return Request[List[Domains.DomainListItem]](path="/domains", verb="get").perform_with_content()
+
+    @classmethod
+    def get(cls, domain_id: str) -> Domain:
+        return Request[Domain](path=f"/domains/{domain_id}", verb="get").perform_with_content()
+
+    @classmethod
+    def verify(cls, domain_id: str) -> None:
+        """Trigger DNS verification after publishing the records."""
+        Request(path=f"/domains/{domain_id}/verify", verb="post").perform()
+
+    @classmethod
+    def remove(cls, domain_id: str) -> None:
+        Request(path=f"/domains/{domain_id}", verb="delete").perform()

eusend/emails.py

@@ -0,0 +1,116 @@
+from typing import Any, Dict, List, Optional, Union, cast
+
+from eusend._compat import NotRequired, TypedDict
+
+from eusend._util import build_query, prepare_email_payload
+from eusend.models import Email, EmailListItem
+from eusend.request import Request
+
+# `from` is a reserved keyword, declared via functional TypedDict syntax.
+_SendParamsFrom = TypedDict("_SendParamsFrom", {"from": str})
+
+
+class Attachment(TypedDict):
+    filename: str
+    content: NotRequired[Union[str, bytes]]
+    path: NotRequired[str]
+    content_type: NotRequired[str]
+    content_id: NotRequired[str]
+
+
+class _SendParamsDefault(_SendParamsFrom):
+    to: Union[str, List[str]]
+    subject: NotRequired[str]
+    cc: NotRequired[Union[str, List[str]]]
+    bcc: NotRequired[Union[str, List[str]]]
+    reply_to: NotRequired[Union[str, List[str]]]
+    html: NotRequired[str]
+    text: NotRequired[str]
+    template_id: NotRequired[str]
+    variables: NotRequired[Dict[str, Any]]
+    headers: NotRequired[Dict[str, str]]
+    track_opens: NotRequired[bool]
+    track_clicks: NotRequired[bool]
+    attachments: NotRequired[List[Attachment]]
+    scheduled_at: NotRequired[str]
+
+
+# `from` again for the list filter.
+_ListParamsFrom = TypedDict("_ListParamsFrom", {"from": NotRequired[str]})
+
+
+class _ListParamsDefault(_ListParamsFrom):
+    limit: NotRequired[int]
+    cursor: NotRequired[str]
+    status: NotRequired[str]
+    to: NotRequired[str]
+
+
+class Emails:
+    class SendParams(_SendParamsDefault):
+        pass
+
+    class SendResponse(TypedDict):
+        id: str
+
+    class SendOptions(TypedDict):
+        idempotency_key: NotRequired[str]
+
+    class ListParams(_ListParamsDefault):
+        pass
+
+    class ListResponse(TypedDict):
+        data: List[EmailListItem]
+        next_cursor: Optional[str]
+
+    class UpdateParams(TypedDict):
+        id: str
+        scheduled_at: str
+
+    class UpdateResponse(TypedDict):
+        id: str
+        status: str
+        scheduled_at: str
+
+    class CancelResponse(TypedDict):
+        id: str
+        status: str
+
+    @classmethod
+    def send(cls, params: "Emails.SendParams", options: Optional["Emails.SendOptions"] = None) -> "Emails.SendResponse":
+        """Send a single email. Pass ``options={"idempotency_key": ...}`` to make
+        the send safe to retry without duplicating."""
+        payload = prepare_email_payload(cast(Dict[str, Any], params))
+        return Request[Emails.SendResponse](
+            path="/emails",
+            params=payload,
+            verb="post",
+            options=cast(Optional[Dict[str, Any]], options),
+        ).perform_with_content()
+
+    @classmethod
+    def get(cls, email_id: str) -> Email:
+        """Retrieve an email by ID, including its delivery events."""
+        return Request[Email](path=f"/emails/{email_id}", verb="get").perform_with_content()
+
+    @classmethod
+    def list(cls, params: Optional["Emails.ListParams"] = None) -> "Emails.ListResponse":
+        """List emails, most recent first. Filter by ``status``, ``from``, ``to``."""
+        path = "/emails" + build_query(cast(Optional[Dict[str, Any]], params))
+        return Request[Emails.ListResponse](path=path, verb="get").perform_with_content()
+
+    @classmethod
+    def update(cls, params: "Emails.UpdateParams") -> "Emails.UpdateResponse":
+        """Reschedule a scheduled email. Fails once it has started sending."""
+        return Request[Emails.UpdateResponse](
+            path=f"/emails/{params['id']}",
+            params={"scheduled_at": params["scheduled_at"]},
+            verb="patch",
+        ).perform_with_content()
+
+    @classmethod
+    def cancel(cls, email_id: str) -> "Emails.CancelResponse":
+        """Cancel a scheduled email. Fails once it has started sending."""
+        return Request[Emails.CancelResponse](
+            path=f"/emails/{email_id}/cancel", verb="post"
+        ).perform_with_content()