sendly-python 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

sendly/__init__.py

@@ -33,6 +33,7 @@ from sendly.errors import (
 from sendly.resources.analytics import AnalyticsResource
 from sendly.resources.campaigns import CampaignsResource
 from sendly.resources.contacts import ContactsResource
+from sendly.resources.deliverability import DeliverabilityResource
 from sendly.resources.domains import DomainsResource
 from sendly.resources.emails import EmailsResource
 from sendly.resources.events import EventsResource
@@ -40,12 +41,16 @@ from sendly.resources.lists import ListsResource
 from sendly.resources.mailboxes import MailboxesResource
 from sendly.resources.projects import ProjectsResource
 from sendly.resources.segments import SegmentsResource
+from sendly.resources.snippets import SnippetsResource
 from sendly.resources.suppression import SuppressionResource
 from sendly.resources.templates import TemplatesResource
+from sendly.resources.topics import TopicsResource
 from sendly.resources.usage import UsageResource
+from sendly.resources.validation import ValidationResource
 from sendly.resources.verify import VerifyResource
 from sendly.resources.webhooks import WebhooksResource
 from sendly.resources.workflows import WorkflowsResource
+from sendly.types import SendlyFile
 from sendly.webhook_utils import DEFAULT_TOLERANCE_MS, construct_event, verify_signature
 
 __version__ = SDK_VERSION
@@ -57,6 +62,7 @@ __all__ = [
     "AnalyticsResource",
     "CampaignsResource",
     "ContactsResource",
+    "DeliverabilityResource",
     "DomainsResource",
     "EmailsResource",
     "EventsResource",
@@ -69,14 +75,18 @@ __all__ = [
     "SendlyConflictError",
     "SendlyConnectionError",
     "SendlyError",
+    "SendlyFile",
     "SendlyNotFoundError",
     "SendlyPermissionError",
     "SendlyRateLimitError",
     "SendlyServerError",
     "SendlyValidationError",
+    "SnippetsResource",
     "SuppressionResource",
     "TemplatesResource",
+    "TopicsResource",
     "UsageResource",
+    "ValidationResource",
     "VerifyResource",
     "WebhooksResource",
     "WorkflowsResource",

sendly/client.py

@@ -36,6 +36,7 @@ from sendly.errors import (
 from sendly.resources.analytics import AnalyticsResource
 from sendly.resources.campaigns import CampaignsResource
 from sendly.resources.contacts import ContactsResource
+from sendly.resources.deliverability import DeliverabilityResource
 from sendly.resources.domains import DomainsResource
 from sendly.resources.emails import EmailsResource
 from sendly.resources.events import EventsResource
@@ -43,12 +44,16 @@ from sendly.resources.lists import ListsResource
 from sendly.resources.mailboxes import MailboxesResource
 from sendly.resources.projects import ProjectsResource
 from sendly.resources.segments import SegmentsResource
+from sendly.resources.snippets import SnippetsResource
 from sendly.resources.suppression import SuppressionResource
 from sendly.resources.templates import TemplatesResource
+from sendly.resources.topics import TopicsResource
 from sendly.resources.usage import UsageResource
+from sendly.resources.validation import ValidationResource
 from sendly.resources.verify import VerifyResource
 from sendly.resources.webhooks import WebhooksResource
 from sendly.resources.workflows import WorkflowsResource
+from sendly.types import SendlyFile
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -59,7 +64,7 @@ if TYPE_CHECKING:
 __all__ = ["DEFAULT_BASE_URL", "SDK_VERSION", "Sendly"]
 
 #: Package version. Kept in sync with ``pyproject.toml``.
-SDK_VERSION = "1.0.0"
+SDK_VERSION = "1.2.0"
 
 #: Default production API base. Override via ``base_url`` for staging/self-hosted.
 DEFAULT_BASE_URL = "https://api.sendly.now"
@@ -137,6 +142,7 @@ class Sendly:
         self.webhooks = WebhooksResource(self)
         self.suppression = SuppressionResource(self)
         self.lists = ListsResource(self)
+        self.snippets = SnippetsResource(self)
         # Reads only -- the mailbox writes need a user, which an API key is not.
         self.mailboxes = MailboxesResource(self)
         # /api/v1 surface. Same client, same auth; bare resource bodies instead
@@ -147,6 +153,9 @@ class Sendly:
         self.analytics = AnalyticsResource(self)
         self.usage = UsageResource(self)
         self.projects = ProjectsResource(self)
+        self.topics = TopicsResource(self)
+        self.validation = ValidationResource(self)
+        self.deliverability = DeliverabilityResource(self)
 
     def request(
         self,
@@ -166,30 +175,7 @@ class Sendly:
         success body, or ``None`` for 204 / ``no_content``. Errors are raised as
         :class:`SendlyError` subclasses based on status.
         """
-        url = self._build_url(path, query)
-        request_headers: dict[str, str] = {
-            "Authorization": f"Bearer {self._api_key}",
-            "Accept": "application/json",
-            "User-Agent": USER_AGENT,
-            **self._default_headers,
-            **(dict(headers) if headers else {}),
-        }
-
-        content: str | None = None
-        if body is not None:
-            request_headers["Content-Type"] = "application/json"
-            content = json.dumps(body)
-
-        try:
-            response = self._client.request(
-                method,
-                url,
-                content=content,
-                headers=request_headers,
-                timeout=self._timeout,
-            )
-        except httpx.HTTPError as exc:
-            raise SendlyConnectionError(f"Sendly request failed: {exc}", exc) from exc
+        response = self._send(method=method, path=path, body=body, query=query, headers=headers)
 
         # 204 No Content or caller-forced no-content (DELETE endpoints, which
         # now respond 200 with an id body the SDK intentionally discards).
@@ -221,6 +207,67 @@ class Sendly:
 
         return parsed
 
+    def request_bytes(
+        self,
+        *,
+        method: str,
+        path: str,
+        query: Query | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> SendlyFile:
+        """Like :meth:`request`, for an operation whose success body is a file.
+
+        Returns the raw bytes with the response's own ``Content-Type`` and
+        ``Content-Disposition``. A failure is still a JSON error document and is
+        raised as the same :class:`SendlyError` subclasses. Reading the body as
+        text, as :meth:`request` does, would mangle any file that is not UTF-8.
+        """
+        response = self._send(
+            method=method, path=path, query=query, headers={"Accept": "*/*", **(headers or {})}
+        )
+        if not response.is_success:
+            self._raise_for_error(response)
+        return SendlyFile(
+            data=response.content,
+            content_type=response.headers.get("content-type"),
+            content_disposition=response.headers.get("content-disposition"),
+        )
+
+    def _send(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Body | None = None,
+        query: Query | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Issue the request; errors and parsing are the caller's."""
+        url = self._build_url(path, query)
+        request_headers: dict[str, str] = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+            **self._default_headers,
+            **(dict(headers) if headers else {}),
+        }
+
+        content: str | None = None
+        if body is not None:
+            request_headers["Content-Type"] = "application/json"
+            content = json.dumps(body)
+
+        try:
+            return self._client.request(
+                method,
+                url,
+                content=content,
+                headers=request_headers,
+                timeout=self._timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise SendlyConnectionError(f"Sendly request failed: {exc}", exc) from exc
+
     def unwrap(self, envelope: Any) -> Any:
         """Return the ``data`` field of a ``{success, data}`` envelope, else the
         value unchanged. Centralizing this keeps resource code clean.

sendly/resources/_pagination.py

@@ -25,8 +25,11 @@ def iterate_cursor(
     ``fetch`` receives the query for one page — the caller's own filters, plus
     the ``after`` cursor from page two onward — and returns the raw cursor
     envelope. Iteration stops when ``has_more`` is false or ``next_cursor`` is
-    ``None``, and also when a page carries no ``data`` list, so a malformed
-    response ends the walk instead of looping forever.
+    ``None``, when a page carries no ``data`` list, and when a page hands back
+    the very cursor it was given -- so a malformed or stuck response ends the
+    walk instead of looping forever. The last of those came from the two
+    hand-rolled walkers this helper absorbed in 1.1; consolidating them must not
+    drop a stop condition the resources that had it were relying on.
 
     The caller's filters are held fixed for the whole walk on purpose: changing
     them mid-pagination invalidates the cursor and the API answers ``422
@@ -44,6 +47,6 @@ def iterate_cursor(
         if not page.get("has_more"):
             return
         cursor = page.get("next_cursor")
-        if not cursor:
+        if not cursor or cursor == params.get("after"):
             return
         params = {**params, "after": cursor}

sendly/resources/campaigns.py

@@ -14,8 +14,10 @@ if TYPE_CHECKING:
     from sendly.types import (
         Body,
         CampaignDeleted,
+        CampaignFailureListV1,
         CampaignList,
         CampaignRecord,
+        CampaignRetryFailedV1,
         CampaignStats,
         JSONDict,
         Query,
@@ -133,3 +135,44 @@ class CampaignsResource:
             method="GET", path=f"/api/v1/campaigns/{encode_path_segment(id)}/stats"
         )
         return response
+
+    def list_failures(self, id: str, query: Query | None = None) -> CampaignFailureListV1:
+        """The recipients this campaign did not reach, and why.
+
+        :meth:`stats` says how many sends failed; only this says who. ``reason``
+        comes from a fixed vocabulary rather than the underlying error text, so
+        it is stable enough to branch on, and is ``None`` on rows recorded
+        before reasons were captured.
+
+        Cursor-paginated (``limit`` / ``after``) like every other v1 list, but
+        uniquely it also carries ``total``: :meth:`retry_failed` acts on that
+        number, and ``has_more`` alone cannot tell you whether 3 or 30,000 sends
+        failed.
+        """
+        response: CampaignFailureListV1 = self._client.request(
+            method="GET",
+            path=f"/api/v1/campaigns/{encode_path_segment(id)}/failures",
+            query=query,
+        )
+        return response
+
+    def iter_list_failures(self, id: str, query: Query | None = None) -> Iterator[JSONDict]:
+        """Iterate every failed send across pages, one recipient at a time."""
+        return iterate_cursor(lambda params: self.list_failures(id, params), query)
+
+    def retry_failed(self, id: str) -> CampaignRetryFailedV1:
+        """Re-drive only the recipients whose send failed.
+
+        Nobody who already received the campaign is mailed a second time: each
+        ledger row is claimed before it is touched, and a row whose email exists
+        already is re-queued rather than re-sent.
+
+        The walk runs in the background, so this returns as soon as it is
+        queued, reporting ``queued`` -- how many failed rows it was started for.
+        Only a ``SENT`` campaign qualifies (400 ``validation_error`` otherwise),
+        and a retry already running answers 409 ``conflict``. Takes no body.
+        """
+        response: CampaignRetryFailedV1 = self._client.request(
+            method="POST", path=f"/api/v1/campaigns/{encode_path_segment(id)}/retry-failed"
+        )
+        return response

sendly/resources/contacts.py

@@ -5,20 +5,35 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from sendly.resources._helpers import encode_path_segment, idempotency_headers
+from sendly.resources._pagination import iterate_cursor
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from sendly.client import Sendly
     from sendly.types import (
         Body,
+        ContactDeletedV1,
         ContactListResponse,
+        ContactListV1,
         ContactRecord,
+        ContactTopicPreferencesV1,
+        ContactV1,
         JSONDict,
         Query,
     )
 
 
 class ContactsResource:
-    """Create, query, and manage contacts."""
+    """Create, query, and manage contacts, on both surfaces.
+
+    The unsuffixed methods speak the legacy ``/api/*`` dialect — camelCase
+    bodies inside a ``{success, data}`` envelope the SDK unwraps. The
+    ``_v1``-suffixed methods speak ``/api/v1``: bare snake_case bodies, cursor
+    pagination, and RFC 9457 problem documents on error. Both answer the same
+    questions, so the suffix is there to keep a call site from confusing one for
+    the other.
+    """
 
     def __init__(self, client: Sendly) -> None:
         self._client = client
@@ -91,3 +106,86 @@ class ContactsResource:
         self._client.request(
             method="DELETE", path=f"/api/contacts/{encode_path_segment(id)}", no_content=True
         )
+
+    def list_v1(self, query: Query | None = None) -> ContactListV1:
+        """List contacts on the ``/api/v1`` surface.
+
+        Accepts ``limit`` (1-100, default 20), ``after`` (opaque cursor),
+        ``search`` (case-insensitive substring on the address) and
+        ``subscribed`` (the string ``"true"`` or ``"false"``), and answers
+        ``{data, has_more, next_cursor}``. Hold the filters steady across one
+        walk — the cursor encodes them, and changing one mid-pagination is
+        answered with 422 ``validation_error`` telling you to restart from the
+        first page.
+        """
+        response: ContactListV1 = self._client.request(
+            method="GET", path="/api/v1/contacts", query=query
+        )
+        return response
+
+    def iter_list_v1(self, query: Query | None = None) -> Iterator[JSONDict]:
+        """Iterate every v1 contact across pages, following the cursor for you."""
+        return iterate_cursor(self.list_v1, query)
+
+    def create_v1(self, body: Body) -> ContactV1:
+        """Create a contact. Requires ``email``.
+
+        ``subscribed`` defaults to true server-side, and ``custom_fields`` is
+        arbitrary JSON that templates read back as ``{{ variables }}``.
+        """
+        response: ContactV1 = self._client.request(
+            method="POST", path="/api/v1/contacts", body=body
+        )
+        return response
+
+    def get_v1(self, id: str) -> ContactV1:
+        """Fetch a single contact by id.
+
+        v1 has no lookup-by-address route — reach a contact you only know the
+        email of through :meth:`list_v1`'s ``search`` filter.
+        """
+        response: ContactV1 = self._client.request(
+            method="GET", path=f"/api/v1/contacts/{encode_path_segment(id)}"
+        )
+        return response
+
+    def update_v1(self, id: str, body: Body) -> ContactV1:
+        """Patch a contact's ``subscribed`` flag or ``custom_fields``.
+
+        ``email`` is deliberately not patchable: an address is the contact's
+        identity on this surface, and rewriting it in place would change who
+        every earlier send was addressed to. Create the new address instead.
+
+        ``custom_fields`` is **replaced, not merged** — the object you send
+        becomes the whole of it, so read the contact and send back every key you
+        mean to keep. A partial object silently drops the rest.
+        """
+        response: ContactV1 = self._client.request(
+            method="PATCH", path=f"/api/v1/contacts/{encode_path_segment(id)}", body=body
+        )
+        return response
+
+    def delete_v1(self, id: str) -> ContactDeletedV1:
+        """Delete a contact, returning the ``{id, deleted}`` confirmation body.
+
+        Unlike the legacy :meth:`delete`, the acknowledgement is handed back
+        rather than discarded.
+        """
+        response: ContactDeletedV1 = self._client.request(
+            method="DELETE", path=f"/api/v1/contacts/{encode_path_segment(id)}"
+        )
+        return response
+
+    def topic_preferences(self, id: str) -> ContactTopicPreferencesV1:
+        """Read everything this contact has said about what they want.
+
+        The top-level ``subscribed`` is the global marketing opt-out and
+        outranks every topic: false means no marketing reaches them whatever the
+        topic rows say. Each topic's own ``subscribed`` is the effective answer
+        the send path reaches today, with the topic's ``default_opt_in`` already
+        folded in, so a contact who has never answered still reads correctly.
+        """
+        response: ContactTopicPreferencesV1 = self._client.request(
+            method="GET", path=f"/api/v1/contacts/{encode_path_segment(id)}/topics"
+        )
+        return response

sendly/resources/deliverability.py

@@ -0,0 +1,109 @@
+"""Deliverability resource (``/api/v1``)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sendly.resources._pagination import iterate_cursor
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sendly.client import Sendly
+    from sendly.types import (
+        DeliverabilityDiagnosisV1,
+        DmarcReportListV1,
+        JSONDict,
+        Query,
+        RecipientDomainStatsListV1,
+    )
+
+
+class DeliverabilityResource:
+    """Why mail from your domains is, or is not, arriving.
+
+    Responses are bare ``/api/v1`` bodies -- no ``{success, data}`` envelope --
+    and errors are RFC 9457 problem documents.
+    """
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def diagnose(self, query: Query) -> DeliverabilityDiagnosisV1:
+        """Diagnose one of your SENDING domains.
+
+        Answers with its DNS identity, the project's recent delivery outcomes,
+        optionally one recipient's suppression state, and the ``findings`` drawn
+        from them, worst first. Branch on a finding's ``code``, never on its
+        prose.
+
+        ``domain`` is required -- the endpoint answers about one domain. The
+        optional ``address`` is a RECIPIENT to check alongside it, because being
+        suppressed is the single most common reason one person stops receiving
+        mail while everyone else still does. ``window_days`` (1-30, default 7)
+        only moves the delivery counters.
+
+        Nothing here is looked up live: the DNS statuses are the verification
+        refresh job's cached results, and ``identity.last_checked_at`` says when
+        they were filled. ``recent_delivery`` is project-wide rather than
+        per-domain -- its own ``scope`` field says so -- because an email row
+        records no sending domain.
+        """
+        response: DeliverabilityDiagnosisV1 = self._client.request(
+            method="GET", path="/api/v1/deliverability/diagnose", query=query
+        )
+        return response
+
+    def list_domain_stats(self, query: Query | None = None) -> RecipientDomainStatsListV1:
+        """Delivery outcomes by RECIPIENT domain and UTC day, newest day first.
+
+        These are the domains you send TO -- ``gmail.com``, ``outlook.com`` --
+        not the domains you send FROM. That is the axis :meth:`diagnose` cannot
+        report: its project-wide rates hide the case that matters most, one
+        recipient domain refusing nearly everything while the rest of your mail
+        is healthy.
+
+        Cursor-paginated on ``limit`` + ``after``. The counts come from an hourly
+        rollup job over a rolling 30-day window, not from a query run on request;
+        each row's ``computed_at`` says when it was last rebuilt. No rate is
+        published, because a rate over three sends is not information.
+        """
+        response: RecipientDomainStatsListV1 = self._client.request(
+            method="GET", path="/api/v1/deliverability/domains", query=query
+        )
+        return response
+
+    def iter_list_domain_stats(self, query: Query | None = None) -> Iterator[JSONDict]:
+        """Iterate every recipient-domain row across pages, one day-and-domain at a time."""
+        return iterate_cursor(self.list_domain_stats, query)
+
+    def list_dmarc_reports(self, query: Query | None = None) -> DmarcReportListV1:
+        """DMARC aggregate (RUA) reports about your domains, newest window first.
+
+        Cursor-paginated on ``limit`` + ``after``.
+
+        An empty list is the correct answer, not a bug, until a policy domain is
+        registered in this project and its DMARC record names an address we
+        receive: only reports about a registered domain are stored, and receivers
+        send them on their own schedule (typically once a day).
+
+        ``intake_configured`` says which kind of empty you are looking at. When
+        it is ``False`` this deployment has no DMARC report intake mailbox at
+        all, so no report can ever arrive and an empty ``data`` means the
+        feature is off -- not that your domains are clean. The two are otherwise
+        indistinguishable, so read the flag before reporting "no DMARC failures"
+        to anyone.
+
+        ``pass_count`` counts DMARC ALIGNMENT taken from ``policy_evaluated``,
+        not raw authentication results -- a message can pass SPF for a domain
+        that is not the one in its From header, which is exactly the case DMARC
+        exists to catch.
+        """
+        response: DmarcReportListV1 = self._client.request(
+            method="GET", path="/api/v1/deliverability/dmarc", query=query
+        )
+        return response
+
+    def iter_list_dmarc_reports(self, query: Query | None = None) -> Iterator[JSONDict]:
+        """Iterate every DMARC report across pages, one report at a time."""
+        return iterate_cursor(self.list_dmarc_reports, query)