sendly-python 1.0.0__py3-none-any.whl → 1.1.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,9 +41,12 @@ 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
@@ -57,6 +61,7 @@ __all__ = [
     "AnalyticsResource",
     "CampaignsResource",
     "ContactsResource",
+    "DeliverabilityResource",
     "DomainsResource",
     "EmailsResource",
     "EventsResource",
@@ -74,9 +79,12 @@ __all__ = [
     "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,9 +44,12 @@ 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
@@ -59,7 +63,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.1.0"
 
 #: Default production API base. Override via ``base_url`` for staging/self-hosted.
 DEFAULT_BASE_URL = "https://api.sendly.now"
@@ -137,6 +141,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 +152,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,

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)

sendly/resources/domains.py

@@ -5,20 +5,36 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from sendly.resources._helpers import encode_path_segment
+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,
+        DomainDeletedV1,
         DomainListResponse,
+        DomainListV1,
         DomainRecord,
         DomainSetupSession,
+        DomainV1,
         DomainVerificationStatus,
+        JSONDict,
+        Query,
     )
 
 
 class DomainsResource:
-    """Register and verify sending domains."""
+    """Register and verify sending domains, 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
@@ -28,7 +44,12 @@ class DomainsResource:
 
         Pass ``region`` to pin this domain to a specific AWS SES region. On the
         first domain for a project this also locks the project's region;
-        subsequent calls must match. The response includes DNS records to set.
+        subsequent calls must match.
+
+        The response carries ``dkimTokens`` -- the SES DKIM tokens to publish as
+        CNAME records before the domain can verify -- alongside ``dkimStatus``,
+        ``spfStatus`` and ``dmarcStatus``, each the result of the last DNS check
+        for that record type.
         """
         envelope = self._client.request(method="POST", path="/api/domains", body=body)
         record: DomainRecord = self._client.unwrap(envelope)
@@ -48,7 +69,14 @@ class DomainsResource:
         return record
 
     def verify(self, id: str) -> DomainVerificationStatus:
-        """Trigger SES verification for a domain."""
+        """Trigger SES verification for a domain.
+
+        ``status`` is SES's own raw DKIM verification state (``Success``,
+        ``Pending``), while ``dkimStatus``, ``spfStatus`` and ``dmarcStatus``
+        are this platform's own DNS check per record type. ``tokens`` carries
+        the DKIM tokens SES has still to report and is absent once verification
+        has resolved.
+        """
         envelope = self._client.request(
             method="POST", path=f"/api/domains/{encode_path_segment(id)}/verify"
         )
@@ -78,6 +106,105 @@ class DomainsResource:
         session: DomainSetupSession = self._client.unwrap(envelope)
         return session
 
+    def assign_stream(self, id: str, body: Body) -> DomainRecord:
+        """Assign this sending identity to transactional or marketing traffic.
+
+        Streams are enforced, not labelled: once assigned, a send of the other
+        kind from this identity is refused with 403 -- which is what keeps a
+        campaign's complaint rate off the identity your password resets go out
+        on. Pass ``stream: None`` to unassign, returning it to carrying both.
+
+        ``streamDefault`` demotes whichever identity currently holds the default
+        for that stream, and ``defaultFromAddress`` has to be an address on this
+        identity's own host. Every field is optional; an omitted one is left
+        alone.
+
+        Legacy dialect: camelCase body, and the updated domain arrives inside
+        the ``{success, data}`` envelope this method unwraps for you.
+        """
+        envelope = self._client.request(
+            method="PATCH", path=f"/api/domains/{encode_path_segment(id)}", body=body
+        )
+        record: DomainRecord = self._client.unwrap(envelope)
+        return record
+
     def delete(self, id: str) -> None:
         """Delete a domain."""
         self._client.request(method="DELETE", path=f"/api/domains/{encode_path_segment(id)}")
+
+    def list_v1(self, query: Query | None = None) -> DomainListV1:
+        """List sending domains, newest first.
+
+        Accepts ``limit`` (1-100, default 20) and ``after`` (opaque cursor), and
+        answers ``{data, has_more, next_cursor}``. :meth:`iter_list_v1` drives
+        that walk for you.
+
+        ``verified`` is SES's verdict on the identity and is what decides
+        whether mail can leave from this domain; ``dkim_verified`` is a separate
+        fact -- what the DNS health refresh last read for the DKIM records -- so
+        the two disagree while a re-check is in flight and neither is a spelling
+        of the other.
+        """
+        response: DomainListV1 = self._client.request(
+            method="GET", path="/api/v1/domains", query=query
+        )
+        return response
+
+    def iter_list_v1(self, query: Query | None = None) -> Iterator[JSONDict]:
+        """Iterate every sending domain across pages, following the cursor for you."""
+        return iterate_cursor(self.list_v1, query)
+
+    def create_v1(self, body: Body) -> DomainV1:
+        """Register a sending domain and start SES DKIM verification.
+
+        The identity comes back with ``verified`` false -- nothing is verified
+        until the DKIM records are published in the domain's own DNS and SES
+        resolves them, so poll :meth:`verify_v1` after publishing them.
+
+        The first domain a project adds LOCKS the project's SES ``region``;
+        every later domain must match it. ``stream_default`` requires
+        ``stream``, and sending it alone is answered with 422
+        ``validation_error`` rather than ignored.
+        """
+        response: DomainV1 = self._client.request(method="POST", path="/api/v1/domains", body=body)
+        return response
+
+    def get_v1(self, id: str) -> DomainV1:
+        """Fetch a single sending domain by id."""
+        response: DomainV1 = self._client.request(
+            method="GET", path=f"/api/v1/domains/{encode_path_segment(id)}"
+        )
+        return response
+
+    def verify_v1(self, id: str) -> DomainV1:
+        """Re-read the domain's state from SES and DNS, and return it refreshed.
+
+        This does not verify anything and changes none of the domain's own
+        fields. Verification happens in the domain's DNS, when its owner
+        publishes the DKIM records SES minted at creation, and Amazon decides
+        when those resolve. What this call does is ask SES what it currently
+        sees, re-check SPF and DMARC, and persist that answer -- so a caller
+        polling after a DNS change learns the outcome without waiting for the
+        periodic sweep. Calling it on a domain whose records are not published
+        yet is not an error and does not hurry anything.
+
+        A POST rather than a GET because the refreshed state is persisted and a
+        verified/unverified transition notifies the project.
+        """
+        response: DomainV1 = self._client.request(
+            method="POST", path=f"/api/v1/domains/{encode_path_segment(id)}/verify"
+        )
+        return response
+
+    def delete_v1(self, id: str) -> DomainDeletedV1:
+        """Remove a sending domain. Returns the ``{id, deleted}`` confirmation body.
+
+        Refused with 409 ``conflict`` while a template, workflow step or active
+        campaign still sends from an address on this host. The SES identity goes
+        too unless another project holds the same host -- and its DKIM keys with
+        it, so re-adding later mints records that must be published again.
+        """
+        response: DomainDeletedV1 = self._client.request(
+            method="DELETE", path=f"/api/v1/domains/{encode_path_segment(id)}"
+        )
+        return response

sendly/resources/emails.py

@@ -11,13 +11,13 @@ if TYPE_CHECKING:
     from sendly.types import (
         BatchSendResponse,
         Body,
-        EmailGetResponse,
+        EmailDetailResponse,
         EmailListResponse,
+        EmailResponse,
         EmailTestV1,
         EmailV1,
         Query,
         SendEmailData,
-        SuccessEmpty,
     )
 
 
@@ -105,16 +105,28 @@ class EmailsResource:
         )
         return response
 
-    def get(self, id: str) -> EmailGetResponse:
-        """Fetch a single email and its delivery events."""
-        response: EmailGetResponse = self._client.request(
+    def get(self, id: str) -> EmailDetailResponse:
+        """Fetch a single email together with its DELIVERY history, oldest first.
+
+        ``events`` here is the delivery timeline behind ``status`` -- not the
+        custom events recorded with ``events.record``, which are read from
+        ``events.list``. Before 1.1 this operation answered the wrong relation
+        and published the message's dedup and idempotency ledger keys with it.
+        """
+        response: EmailDetailResponse = self._client.request(
             method="GET", path=f"/api/emails/{encode_path_segment(id)}"
         )
         return response
 
-    def cancel_schedule(self, id: str) -> SuccessEmpty:
-        """Cancel a scheduled (PENDING) email before it fires."""
-        response: SuccessEmpty = self._client.request(
+    def cancel_schedule(self, id: str) -> EmailResponse:
+        """Cancel a scheduled (PENDING) email before it fires.
+
+        Answers the email itself, not an empty acknowledgement: the contract has
+        always published that shape here, and the caller wants the row's new
+        status more than a success flag it already inferred from the absence of
+        an exception.
+        """
+        response: EmailResponse = self._client.request(
             method="DELETE", path=f"/api/emails/{encode_path_segment(id)}/schedule"
         )
         return response

sendly/resources/events.py

@@ -49,7 +49,9 @@ class EventsResource:
     def record(self, body: Body) -> EventRecord:
         """Record a custom event for a contact (``/api/v1``).
 
-        Requires ``name``; optionally takes ``contact_id`` and a ``data`` object.
+        Requires ``name``; optionally takes ``contact_id`` and a ``payload``
+        object. It was ``data`` before 1.1 -- on a wire where every legacy
+        envelope has a ``data``, the name said nothing about whose it was.
         The v1 counterpart of :meth:`track`, returning the created event body
         rather than a ``{success, data}`` envelope.