sendora 2.2.0__tar.gz → 2.3.0__tar.gz

{sendora-2.2.0 → sendora-2.3.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.3.0
+
+- Two events, `OpenedEvent` and `ClickedEvent`, for `opened` and `clicked`:
+  a tracked copy's pixel loaded, or a tracked link was followed. A webhook
+  gets them only if it names them, so `webhooks.create` without `events`
+  takes every other event.
+
 ## 2.2.0
 
 - Each `MessageRecipient` has `tracked`, `opens`, `clicks`, `first_open_at`

{sendora-2.2.0 → sendora-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendora
-Version: 2.2.0
+Version: 2.3.0
 Summary: The Python client for Sendora's email API.
 Project-URL: Homepage, https://sendora.se/docs
 License-Expression: MIT
@@ -310,7 +310,9 @@ Events: `delivered`, `bounced`, `deferred`, `spam_complaint` and
 `unsubscribed` about a message, with `message_id`, `stream_id`,
 `recipient`, `occurred_at`, `server_id`, your `tag` and `metadata`, and
 `details` from the receiver, or for `unsubscribed` the `source` (`link` or
-`one_click`); `cap_warning` and `cap_reached` about usage, with `scope`,
+`one_click`); `opened` and `clicked` about a tracked copy, sent only to a
+webhook that names them, with the same fields and `details` that say whether
+a machine did it and, for `clicked`, give the `link`; `cap_warning` and `cap_reached` about usage, with `scope`,
 `cap`, `used` and the period; `inbound` about a message received on an
 inbound stream, with `inbound_message_id`, `envelope_recipient`, the
 sizes, the `authentication` verdicts and, for a webhook with
@@ -318,7 +320,8 @@ sizes, the `authentication` verdicts and, for a webhook with
 `to`, `subject`, `text`, `html`, `attachments` and the rest.
 `inbound_cap_warning` and `inbound_cap_reached` say that received mail
 nears or reaches the account's monthly cap, with `cap`, `used` and the
-period. Every event carries `id`, the delivery id, and `attempt`.
+period. Every event carries `id`, the delivery id, and `attempt`. Tracking is
+not open to accounts yet, so `opened` and `clicked` are not sent until it is.
 
 A failed delivery is retried with growing delays for about a day, then it
 is `dead` until you replay it. Deliveries arrive at least once and not

{sendora-2.2.0 → sendora-2.3.0}/README.md

@@ -288,7 +288,9 @@ Events: `delivered`, `bounced`, `deferred`, `spam_complaint` and
 `unsubscribed` about a message, with `message_id`, `stream_id`,
 `recipient`, `occurred_at`, `server_id`, your `tag` and `metadata`, and
 `details` from the receiver, or for `unsubscribed` the `source` (`link` or
-`one_click`); `cap_warning` and `cap_reached` about usage, with `scope`,
+`one_click`); `opened` and `clicked` about a tracked copy, sent only to a
+webhook that names them, with the same fields and `details` that say whether
+a machine did it and, for `clicked`, give the `link`; `cap_warning` and `cap_reached` about usage, with `scope`,
 `cap`, `used` and the period; `inbound` about a message received on an
 inbound stream, with `inbound_message_id`, `envelope_recipient`, the
 sizes, the `authentication` verdicts and, for a webhook with
@@ -296,7 +298,8 @@ sizes, the `authentication` verdicts and, for a webhook with
 `to`, `subject`, `text`, `html`, `attachments` and the rest.
 `inbound_cap_warning` and `inbound_cap_reached` say that received mail
 nears or reaches the account's monthly cap, with `cap`, `used` and the
-period. Every event carries `id`, the delivery id, and `attempt`.
+period. Every event carries `id`, the delivery id, and `attempt`. Tracking is
+not open to accounts yet, so `opened` and `clicked` are not sent until it is.
 
 A failed delivery is retried with growing delays for about a day, then it
 is `dead` until you replay it. Deliveries arrive at least once and not

{sendora-2.2.0 → sendora-2.3.0}/src/sendora/__init__.py

@@ -33,11 +33,13 @@ from .types import (
     BouncedEvent,
     CapReachedEvent,
     CapWarningEvent,
+    ClickedEvent,
     DeferredEvent,
     DeliveredEvent,
     InboundCapReachedEvent,
     InboundCapWarningEvent,
     InboundEvent,
+    OpenedEvent,
     SendoraErrorCode,
     SpamComplaintEvent,
     UnknownEvent,
@@ -58,6 +60,7 @@ __all__ = [
     "BouncedEvent",
     "CapReachedEvent",
     "CapWarningEvent",
+    "ClickedEvent",
     "ConflictError",
     "DeferredEvent",
     "DeliveredEvent",
@@ -67,6 +70,7 @@ __all__ = [
     "InboundEvent",
     "InternalServerError",
     "NotFoundError",
+    "OpenedEvent",
     "PermissionDeniedError",
     "RateLimitError",
     "ResponseValidationError",

{sendora-2.2.0 → sendora-2.3.0}/src/sendora/_version.py

@@ -1,3 +1,3 @@
 """The package's version: the build reads it, and every request names it."""
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{sendora-2.2.0 → sendora-2.3.0}/src/sendora/_webhooks.py

@@ -15,12 +15,14 @@ from .types import (
     BouncedEvent,
     CapReachedEvent,
     CapWarningEvent,
+    ClickedEvent,
     DeferredEvent,
     DeliveredEvent,
     InboundCapReachedEvent,
     InboundCapWarningEvent,
     InboundEvent,
     InboundEventContent,
+    OpenedEvent,
     SpamComplaintEvent,
     UnknownEvent,
     UnsubscribedEvent,
@@ -169,6 +171,8 @@ _EVENTS: dict[str, Callable[[dict[str, object]], WebhookEvent]] = {
     "deferred": lambda payload: decode(DeferredEvent, payload),
     "spam_complaint": lambda payload: decode(SpamComplaintEvent, payload),
     "unsubscribed": lambda payload: decode(UnsubscribedEvent, payload),
+    "opened": lambda payload: decode(OpenedEvent, payload),
+    "clicked": lambda payload: decode(ClickedEvent, payload),
     "cap_warning": lambda payload: decode(CapWarningEvent, payload),
     "cap_reached": lambda payload: decode(CapReachedEvent, payload),
     "inbound": _inbound,

{sendora-2.2.0 → sendora-2.3.0}/src/sendora/resources/webhooks.py

@@ -44,7 +44,8 @@ class Webhooks:
         Args:
             url: Where the events are posted: https, without credentials or
                 a fragment.
-            events: The events to deliver; every event when left out.
+            events: The events to deliver; every event except ``opened`` and
+                ``clicked`` when left out.
             stream_id: The one stream whose message events it receives;
                 every stream when left out. Usage events arrive either way.
             inbound_content: How the ``inbound`` event carries a received
@@ -261,7 +262,8 @@ class AsyncWebhooks:
         Args:
             url: Where the events are posted: https, without credentials or
                 a fragment.
-            events: The events to deliver; every event when left out.
+            events: The events to deliver; every event except ``opened`` and
+                ``clicked`` when left out.
             stream_id: The one stream whose message events it receives;
                 every stream when left out. Usage events arrive either way.
             inbound_content: How the ``inbound`` event carries a received

{sendora-2.2.0 → sendora-2.3.0}/src/sendora/types.py

@@ -48,6 +48,8 @@ __all__ = [
     "CapEventFields",
     "CapReachedEvent",
     "CapWarningEvent",
+    "ClickedDetails",
+    "ClickedEvent",
     "CnameRecord",
     "CreatedServer",
     "CreatedToken",
@@ -99,6 +101,8 @@ __all__ = [
     "MessageStatus",
     "MessageTracking",
     "MxRecord",
+    "OpenedDetails",
+    "OpenedEvent",
     "OwnServer",
     "RecipientKind",
     "RecipientStatus",
@@ -493,7 +497,7 @@ report received by mail, ``Feedback`` for a spam complaint, ``Open`` and
 
 TrackingAutomated = Literal["likely", "unlikely", "unknown"]
 """Whether a machine rather than a person did it: ``unknown`` where nobody
-can tell, as with Apple Mail."""
+can tell, as with Apple's privacy protection."""
 
 TrackingAgent = Literal[
     "apple_privacy",
@@ -1189,6 +1193,8 @@ WebhookEventName = Literal[
     "deferred",
     "spam_complaint",
     "unsubscribed",
+    "opened",
+    "clicked",
     "cap_warning",
     "cap_reached",
     "inbound",
@@ -2083,6 +2089,86 @@ class UnsubscribedEvent(MessageEventFields):
     details: UnsubscribedDetails
 
 
+@model
+class OpenedDetails(Answer):
+    """What tracking knows of an open.
+
+    Attributes:
+        automated: Whether a machine rather than a person did it.
+        agent: The proxy or machine it came through, where Sendora knows it.
+        reasons: Why it was labelled a machine's.
+        client: The mail program, where Sendora knows it.
+        device: The kind of device, where Sendora knows it.
+        first: The recipient's first event of this kind.
+        first_human: The recipient's first event of this kind that was
+            likely a person's.
+    """
+
+    automated: TrackingAutomated
+    agent: TrackingAgent | None
+    reasons: list[TrackingReason]
+    client: TrackingClient | None
+    device: TrackingDevice | None
+    first: bool
+    first_human: bool
+
+
+@model
+class OpenedEvent(MessageEventFields):
+    """The pixel of a tracked copy loaded, for a person or a machine.
+
+    A webhook gets this event only if it names it.
+
+    Attributes:
+        event: ``opened``.
+        details: What tracking knows of it.
+    """
+
+    event: Literal["opened"]
+    details: OpenedDetails
+
+
+@model
+class ClickedDetails(Answer):
+    """What tracking knows of a click.
+
+    Attributes:
+        automated: Whether a machine rather than a person did it.
+        agent: The proxy or machine it came through, where Sendora knows it.
+        reasons: Why it was labelled a machine's.
+        client: The mail program, where Sendora knows it.
+        device: The kind of device, where Sendora knows it.
+        first: The recipient's first event of this kind.
+        first_human: The recipient's first event of this kind that was
+            likely a person's.
+        link: The link that was followed.
+    """
+
+    automated: TrackingAutomated
+    agent: TrackingAgent | None
+    reasons: list[TrackingReason]
+    client: TrackingClient | None
+    device: TrackingDevice | None
+    first: bool
+    first_human: bool
+    link: TrackedLink
+
+
+@model
+class ClickedEvent(MessageEventFields):
+    """A tracked link was followed, by a person or a machine.
+
+    A webhook gets this event only if it names it.
+
+    Attributes:
+        event: ``clicked``.
+        details: What tracking knows of it.
+    """
+
+    event: Literal["clicked"]
+    details: ClickedDetails
+
+
 @model
 class CapEventFields(Answer):
     """What both usage events carry.
@@ -2316,6 +2402,8 @@ WebhookEvent = (
     | DeferredEvent
     | SpamComplaintEvent
     | UnsubscribedEvent
+    | OpenedEvent
+    | ClickedEvent
     | CapWarningEvent
     | CapReachedEvent
     | InboundEvent