anypost 1.0.0__py3-none-any.whl

anypost/__init__.py

@@ -0,0 +1,75 @@
+"""Official Python SDK for the Anypost email API."""
+
+from __future__ import annotations
+
+from ._async import AsyncAnypost
+from ._client import Anypost
+from ._exceptions import (
+    AnypostError,
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    IdempotencyMismatchError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionError,
+    RateLimitError,
+    ValidationError,
+)
+from ._pagination import AsyncPage, Page
+from ._version import __version__
+from ._webhook_signature import (
+    WebhookDelivery,
+    WebhookDeliveryEvent,
+    WebhookVerificationError,
+    WebhookVerificationFailure,
+    unwrap_webhook_event,
+    verify_webhook_signature,
+)
+from .resources import (
+    ApiKeys,
+    Domains,
+    Email,
+    Events,
+    Identity,
+    Suppressions,
+    Templates,
+    Webhooks,
+)
+
+__all__ = [
+    "Anypost",
+    "AsyncAnypost",
+    "Page",
+    "AsyncPage",
+    "__version__",
+    # Resources
+    "ApiKeys",
+    "Domains",
+    "Email",
+    "Events",
+    "Identity",
+    "Suppressions",
+    "Templates",
+    "Webhooks",
+    # Errors
+    "AnypostError",
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "ConflictError",
+    "IdempotencyMismatchError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "PermissionError",
+    "RateLimitError",
+    "ValidationError",
+    # Webhooks
+    "WebhookDelivery",
+    "WebhookDeliveryEvent",
+    "WebhookVerificationError",
+    "WebhookVerificationFailure",
+    "unwrap_webhook_event",
+    "verify_webhook_signature",
+]

anypost/_async/__init__.py

@@ -0,0 +1,7 @@
+"""Asynchronous client surface."""
+
+from __future__ import annotations
+
+from .client import AsyncAnypost
+
+__all__ = ["AsyncAnypost"]

anypost/_async/client.py

@@ -0,0 +1,109 @@
+"""The asynchronous :class:`AsyncAnypost` client."""
+
+from __future__ import annotations
+
+import os
+from types import TracebackType
+from typing import Mapping, Optional, Type
+
+import httpx
+
+from .._async_http import AsyncHttpClient
+from ..types.identity import WhoamiResponse
+from .resources import (
+    AsyncApiKeys,
+    AsyncDomains,
+    AsyncEmail,
+    AsyncEvents,
+    AsyncIdentity,
+    AsyncSuppressions,
+    AsyncTemplates,
+    AsyncWebhooks,
+)
+
+DEFAULT_BASE_URL = "https://api.anypost.com/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+
+class AsyncAnypost:
+    """Async client for the Anypost email API.
+
+    ::
+
+        import asyncio
+        from anypost import AsyncAnypost
+
+        async def main():
+            async with AsyncAnypost("ap_your_api_key") as client:
+                result = await client.email.send({
+                    "from": "Acme <you@yourdomain.com>",
+                    "to": ["someone@example.com"],
+                    "subject": "Hello",
+                    "html": "<p>It worked.</p>",
+                })
+
+        asyncio.run(main())
+    """
+
+    email: AsyncEmail
+    domains: AsyncDomains
+    api_keys: AsyncApiKeys
+    templates: AsyncTemplates
+    suppressions: AsyncSuppressions
+    webhooks: AsyncWebhooks
+    events: AsyncEvents
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        key = api_key or os.environ.get("ANYPOST_API_KEY")
+        if not key:
+            raise ValueError(
+                "An Anypost API key is required. Pass it to the constructor "
+                "or set ANYPOST_API_KEY."
+            )
+
+        self._http = AsyncHttpClient(
+            api_key=key,
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers or {},
+            client=http_client,
+        )
+        self._identity = AsyncIdentity(self._http)
+
+        self.email = AsyncEmail(self._http)
+        self.domains = AsyncDomains(self._http)
+        self.api_keys = AsyncApiKeys(self._http)
+        self.templates = AsyncTemplates(self._http)
+        self.suppressions = AsyncSuppressions(self._http)
+        self.webhooks = AsyncWebhooks(self._http)
+        self.events = AsyncEvents(self._http)
+
+    async def whoami(self) -> WhoamiResponse:
+        """Identify the team and permission level behind the current API key."""
+        return await self._identity.whoami()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncAnypost":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()

anypost/_async/resources.py

@@ -0,0 +1,346 @@
+"""Async resource clients. Mirror the sync resources in :mod:`anypost.resources`."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+from urllib.parse import quote
+
+from .._async_http import AsyncHttpClient
+from .._pagination import AsyncPage
+from ..resources.email import _encode_attachments
+from ..types.api_key import (
+    ApiKey,
+    ApiKeyCreateParams,
+    ApiKeyUpdateParams,
+    ApiKeyWithSecret,
+)
+from ..types.common import ListParams
+from ..types.domain import Domain, DomainCreateParams, DomainUpdateParams
+from ..types.email import BatchResponse, EmailBatchParams, EmailSendParams, SendResponse
+from ..types.event import Event, EventListParams
+from ..types.identity import WhoamiResponse
+from ..types.suppression import (
+    Suppression,
+    SuppressionCreateParams,
+    SuppressionListParams,
+)
+from ..types.template import (
+    Template,
+    TemplateCreateParams,
+    TemplateDraft,
+    TemplateDraftParams,
+    TemplateDuplicateParams,
+    TemplateUpdateParams,
+)
+from ..types.webhook import (
+    Webhook,
+    WebhookCreateParams,
+    WebhookTestResult,
+    WebhookUpdateParams,
+    WebhookWithSecret,
+)
+
+
+class AsyncEmail:
+    """Operations on the ``/email`` endpoints."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def send(
+        self, email: EmailSendParams, *, idempotency_key: Optional[str] = None
+    ) -> SendResponse:
+        """Send a single message. See :meth:`anypost.resources.email.Email.send`."""
+        return await self._http.request(
+            "POST",
+            "/email",
+            body=_encode_attachments(email),
+            idempotent=True,
+            idempotency_key=idempotency_key,
+        )
+
+    async def send_batch(
+        self, batch: EmailBatchParams, *, idempotency_key: Optional[str] = None
+    ) -> BatchResponse:
+        """Send 1-100 messages. A ``207`` returns normally; it does not raise."""
+        body: dict[str, Any] = dict(batch)
+        if batch.get("defaults"):
+            body["defaults"] = _encode_attachments(batch["defaults"])
+        body["emails"] = [_encode_attachments(e) for e in batch["emails"]]
+        return await self._http.request(
+            "POST",
+            "/email/batch",
+            body=body,
+            idempotent=True,
+            idempotency_key=idempotency_key,
+        )
+
+
+class AsyncDomains:
+    """Operations on the ``/domains`` endpoints."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: Optional[ListParams] = None) -> AsyncPage[Domain]:
+        return await self._fetch_page(params)
+
+    async def create(self, params: DomainCreateParams) -> Domain:
+        return await self._http.request("POST", "/domains", body=params)
+
+    async def get(self, id: str) -> Domain:
+        return await self._http.request("GET", f"/domains/{quote(id, safe='')}")
+
+    async def update(self, id: str, params: DomainUpdateParams) -> Domain:
+        return await self._http.request(
+            "PATCH", f"/domains/{quote(id, safe='')}", body=params
+        )
+
+    async def delete(self, id: str) -> None:
+        await self._http.request("DELETE", f"/domains/{quote(id, safe='')}")
+
+    async def verify(self, id: str) -> Domain:
+        return await self._http.request("POST", f"/domains/{quote(id, safe='')}/verify")
+
+    async def _fetch_page(self, params: Optional[ListParams]) -> AsyncPage[Domain]:
+        params = params or {}
+        response = await self._http.request(
+            "GET",
+            "/domains",
+            query={"limit": params.get("limit"), "after": params.get("after")},
+        )
+        return AsyncPage(
+            response, lambda after: self._fetch_page({**params, "after": after})
+        )
+
+
+class AsyncApiKeys:
+    """Operations on the ``/api-keys`` endpoints."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: Optional[ListParams] = None) -> AsyncPage[ApiKey]:
+        return await self._fetch_page(params)
+
+    async def create(self, params: ApiKeyCreateParams) -> ApiKeyWithSecret:
+        return await self._http.request("POST", "/api-keys", body=params)
+
+    async def get(self, id: str) -> ApiKey:
+        return await self._http.request("GET", f"/api-keys/{quote(id, safe='')}")
+
+    async def update(self, id: str, params: ApiKeyUpdateParams) -> ApiKey:
+        return await self._http.request(
+            "PATCH", f"/api-keys/{quote(id, safe='')}", body=params
+        )
+
+    async def delete(self, id: str) -> None:
+        await self._http.request("DELETE", f"/api-keys/{quote(id, safe='')}")
+
+    async def _fetch_page(self, params: Optional[ListParams]) -> AsyncPage[ApiKey]:
+        params = params or {}
+        response = await self._http.request(
+            "GET",
+            "/api-keys",
+            query={"limit": params.get("limit"), "after": params.get("after")},
+        )
+        return AsyncPage(
+            response, lambda after: self._fetch_page({**params, "after": after})
+        )
+
+
+class AsyncTemplates:
+    """Operations on the ``/templates`` endpoints."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: Optional[ListParams] = None) -> AsyncPage[Template]:
+        return await self._fetch_page(params)
+
+    async def create(self, params: TemplateCreateParams) -> Template:
+        return await self._http.request("POST", "/templates", body=params)
+
+    async def get(self, id: str) -> Template:
+        return await self._http.request("GET", f"/templates/{quote(id, safe='')}")
+
+    async def update(self, id: str, params: TemplateUpdateParams) -> Template:
+        return await self._http.request(
+            "PATCH", f"/templates/{quote(id, safe='')}", body=params
+        )
+
+    async def delete(self, id: str) -> None:
+        await self._http.request("DELETE", f"/templates/{quote(id, safe='')}")
+
+    async def duplicate(
+        self, id: str, params: Optional[TemplateDuplicateParams] = None
+    ) -> Template:
+        return await self._http.request(
+            "POST", f"/templates/{quote(id, safe='')}/duplicate", body=params or None
+        )
+
+    async def get_draft(self, id: str) -> TemplateDraft:
+        return await self._http.request("GET", f"/templates/{quote(id, safe='')}/draft")
+
+    async def update_draft(self, id: str, params: TemplateDraftParams) -> TemplateDraft:
+        return await self._http.request(
+            "PATCH", f"/templates/{quote(id, safe='')}/draft", body=params
+        )
+
+    async def delete_draft(self, id: str) -> None:
+        await self._http.request("DELETE", f"/templates/{quote(id, safe='')}/draft")
+
+    async def publish(self, id: str) -> Template:
+        return await self._http.request("POST", f"/templates/{quote(id, safe='')}/publish")
+
+    async def _fetch_page(self, params: Optional[ListParams]) -> AsyncPage[Template]:
+        params = params or {}
+        response = await self._http.request(
+            "GET",
+            "/templates",
+            query={"limit": params.get("limit"), "after": params.get("after")},
+        )
+        return AsyncPage(
+            response, lambda after: self._fetch_page({**params, "after": after})
+        )
+
+
+class AsyncSuppressions:
+    """Operations on the ``/suppressions`` endpoints."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(
+        self, params: Optional[SuppressionListParams] = None
+    ) -> AsyncPage[Suppression]:
+        return await self._fetch_page(params)
+
+    async def create(self, params: SuppressionCreateParams) -> Suppression:
+        return await self._http.request("POST", "/suppressions", body=params)
+
+    async def get(self, email: str, topic: str) -> Suppression:
+        return await self._http.request(
+            "GET", f"/suppressions/{quote(email, safe='')}/{quote(topic, safe='')}"
+        )
+
+    async def delete(self, email: str, topic: str) -> None:
+        await self._http.request(
+            "DELETE", f"/suppressions/{quote(email, safe='')}/{quote(topic, safe='')}"
+        )
+
+    async def list_for_email(self, email: str) -> List[Suppression]:
+        response = await self._http.request("GET", f"/suppressions/{quote(email, safe='')}")
+        return response["data"]
+
+    async def delete_for_email(self, email: str) -> None:
+        await self._http.request("DELETE", f"/suppressions/{quote(email, safe='')}")
+
+    async def _fetch_page(
+        self, params: Optional[SuppressionListParams]
+    ) -> AsyncPage[Suppression]:
+        params = params or {}
+        response = await self._http.request(
+            "GET",
+            "/suppressions",
+            query={
+                "limit": params.get("limit"),
+                "after": params.get("after"),
+                "email_contains": params.get("email_contains"),
+                "topic": params.get("topic"),
+                "reason": params.get("reason"),
+                "origin": params.get("origin"),
+            },
+        )
+        return AsyncPage(
+            response, lambda after: self._fetch_page({**params, "after": after})
+        )
+
+
+class AsyncWebhooks:
+    """Operations on the ``/webhooks`` endpoints."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: Optional[ListParams] = None) -> AsyncPage[Webhook]:
+        return await self._fetch_page(params)
+
+    async def create(self, params: WebhookCreateParams) -> WebhookWithSecret:
+        return await self._http.request("POST", "/webhooks", body=params)
+
+    async def get(self, id: str) -> Webhook:
+        return await self._http.request("GET", f"/webhooks/{quote(id, safe='')}")
+
+    async def update(self, id: str, params: WebhookUpdateParams) -> Webhook:
+        return await self._http.request(
+            "PATCH", f"/webhooks/{quote(id, safe='')}", body=params
+        )
+
+    async def delete(self, id: str) -> None:
+        await self._http.request("DELETE", f"/webhooks/{quote(id, safe='')}")
+
+    async def test(self, id: str) -> WebhookTestResult:
+        return await self._http.request("POST", f"/webhooks/{quote(id, safe='')}/test")
+
+    async def rotate_secret(self, id: str) -> WebhookWithSecret:
+        return await self._http.request(
+            "POST", f"/webhooks/{quote(id, safe='')}/rotate-secret"
+        )
+
+    async def _fetch_page(self, params: Optional[ListParams]) -> AsyncPage[Webhook]:
+        params = params or {}
+        response = await self._http.request(
+            "GET",
+            "/webhooks",
+            query={"limit": params.get("limit"), "after": params.get("after")},
+        )
+        return AsyncPage(
+            response, lambda after: self._fetch_page({**params, "after": after})
+        )
+
+
+class AsyncEvents:
+    """Read access to the ``/events`` stream."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self, params: Optional[EventListParams] = None) -> AsyncPage[Event]:
+        return await self._fetch_page(params)
+
+    async def _fetch_page(self, params: Optional[EventListParams]) -> AsyncPage[Event]:
+        params = params or {}
+        tags = params.get("tags")
+        response = await self._http.request(
+            "GET",
+            "/events",
+            query={
+                "limit": params.get("limit"),
+                "after": params.get("after"),
+                "start": params.get("start"),
+                "end": params.get("end"),
+                "event_type": params.get("event_type"),
+                "recipient": params.get("recipient"),
+                "email_id": params.get("email_id"),
+                "message_id": params.get("message_id"),
+                "domain": params.get("domain"),
+                "topic": params.get("topic"),
+                "campaign": params.get("campaign"),
+                "template_id": params.get("template_id"),
+                "tags": ",".join(tags) if tags else None,
+            },
+        )
+        return AsyncPage(
+            response, lambda after: self._fetch_page({**params, "after": after})
+        )
+
+
+class AsyncIdentity:
+    """Identity operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def whoami(self) -> WhoamiResponse:
+        return await self._http.request("GET", "/whoami")

anypost/_async_http.py

@@ -0,0 +1,96 @@
+"""Asynchronous HTTP transport. Mirrors :mod:`anypost._http`, sharing its
+pure helpers (header building, backoff, decoding)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from ._exceptions import APIConnectionError, parse_error
+from ._http import (
+    RETRYABLE_STATUS,
+    QueryValue,
+    backoff_seconds,
+    build_headers,
+    clean_query,
+    connection_message,
+    decode_body,
+)
+
+
+class AsyncHttpClient:
+    """Owns an :class:`httpx.AsyncClient` and implements the async request loop."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        default_headers: Mapping[str, str],
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._max_retries = max_retries
+        self._default_headers = dict(default_headers)
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(base_url=base_url, timeout=timeout)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        query: Optional[Mapping[str, QueryValue]] = None,
+        idempotent: bool = False,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        retries = self._max_retries if max_retries is None else max_retries
+        headers = build_headers(
+            self._api_key,
+            self._default_headers,
+            has_body=body is not None,
+            idempotent=idempotent,
+            idempotency_key=idempotency_key,
+            max_retries=retries,
+            extra_headers=extra_headers,
+        )
+        kwargs: dict[str, Any] = {"headers": headers, "params": clean_query(query)}
+        if body is not None:
+            kwargs["json"] = body
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+
+        attempt = 0
+        while True:
+            try:
+                response = await self._client.request(method, path, **kwargs)
+            except httpx.RequestError as exc:
+                if attempt < retries:
+                    await asyncio.sleep(backoff_seconds(attempt, None))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(connection_message(exc), exc) from exc
+
+            if response.is_success:
+                return decode_body(response)
+
+            if response.status_code in RETRYABLE_STATUS and attempt < retries:
+                await asyncio.sleep(backoff_seconds(attempt, response.headers))
+                attempt += 1
+                continue
+
+            raise parse_error(
+                response.status_code, decode_body(response), response.headers
+            )
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()

anypost/_base64.py

@@ -0,0 +1,10 @@
+"""Base64 encoding for attachment content."""
+
+from __future__ import annotations
+
+import base64
+
+
+def bytes_to_base64(data: bytes) -> str:
+    """Base64-encode raw bytes into an ASCII string."""
+    return base64.b64encode(data).decode("ascii")