sendora 2.1.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,5 +1,22 @@
 # 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`
+  and `first_human_open_at`.
+- `messages.get` returns `tracking`, with `recording_opens`,
+  `recording_clicks` and `skipped`. Its timeline holds `Open` and `Click`
+  events, each with its `tracking`.
+- `broadcasts.get` returns `BroadcastDetail`, a `Broadcast` with `opened`,
+  `opened_by_people`, `clicked`, `clicked_by_people` and `links`.
+
 ## 2.1.0
 
 - `SendoraAccount.tracking_domains` and `AsyncSendoraAccount.tracking_domains`

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendora
-Version: 2.1.0
+Version: 2.3.0
 Summary: The Python client for Sendora's email API.
 Project-URL: Homepage, https://sendora.se/docs
 License-Expression: MIT
@@ -113,16 +113,16 @@ for result in batch.results:
 
 ## Messages
 
-| Call                                                            | Answers                                                                           |
-| --------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `sendora.messages.get(message_id)`                              | The message with its recipients, its attachments described and its events         |
-| `sendora.messages.search(**filters)`                            | `MessagePage` with `messages` and `next`, newest first                            |
-| `sendora.messages.search_all(**filters)`                        | Every match, page by page, as an iterator                                         |
-| `sendora.inbound.get(inbound_message_id)`                       | A received message: envelope, parties, headers, text, HTML, attachments described |
-| `sendora.inbound.search(**filters)`                             | `InboundPage` of received mail, newest first                                      |
-| `sendora.inbound.search_all(**filters)`                         | Every received match, page by page, as an iterator                                |
-| `sendora.inbound.raw(inbound_message_id)`                       | The raw message as `bytes`, `message/rfc822`                                      |
-| `sendora.inbound.attachment(inbound_message_id, attachment_id)` | An attachment's `bytes`                                                           |
+| Call                                                            | Answers                                                                               |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `sendora.messages.get(message_id)`                              | The message with its recipients, `tracking`, its attachments described and its events |
+| `sendora.messages.search(**filters)`                            | `MessagePage` with `messages` and `next`, newest first                                |
+| `sendora.messages.search_all(**filters)`                        | Every match, page by page, as an iterator                                             |
+| `sendora.inbound.get(inbound_message_id)`                       | A received message: envelope, parties, headers, text, HTML, attachments described     |
+| `sendora.inbound.search(**filters)`                             | `InboundPage` of received mail, newest first                                          |
+| `sendora.inbound.search_all(**filters)`                         | Every received match, page by page, as an iterator                                    |
+| `sendora.inbound.raw(inbound_message_id)`                       | The raw message as `bytes`, `message/rfc822`                                          |
+| `sendora.inbound.attachment(inbound_message_id, attachment_id)` | An attachment's `bytes`                                                               |
 
 A stream can also receive on a domain of yours: every address on it,
 whatever the local part, lands on the stream. Claim it with the stream
@@ -146,6 +146,11 @@ list of them), `from_` and `to` as an aware `datetime` or ISO 8601,
 `limit` (1 to 100, 50 by default) and `after`, the previous page's
 `next`. Bodies are never returned; the log keeps messages for 13 months.
 
+Where mail is tracked, each recipient has `tracked`, `opens`, `clicks`,
+`first_open_at` and `first_human_open_at`. `messages.get` adds `tracking`, and
+its timeline holds `Open` and `Click` events with their labels. Tracking is
+not open to accounts yet.
+
 ```python
 from datetime import UTC, datetime
 
@@ -198,12 +203,12 @@ message's `substitutions`, up to 20 strings, replace `{{ key }}` in the
 subject, the text and the HTML, escaped in the HTML; a key the content
 names that a message lacks raises `substitution_missing`.
 
-| Call                                      | Answers                                                                   |
-| ----------------------------------------- | ------------------------------------------------------------------------- |
-| `sendora.broadcasts.send(**broadcast)`    | `AcceptedBroadcast` with `broadcast_id`, `total`, `suppressed` and `test` |
-| `sendora.broadcasts.get(broadcast_id)`    | The broadcast with `status`, `released` and `failed`                      |
-| `sendora.broadcasts.list(limit=, after=)` | `BroadcastPage` with `broadcasts` and `next`, newest first                |
-| `sendora.broadcasts.cancel(broadcast_id)` | The cancelled broadcast; what had not left counts as failed               |
+| Call                                      | Answers                                                                            |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| `sendora.broadcasts.send(**broadcast)`    | `AcceptedBroadcast` with `broadcast_id`, `total`, `suppressed` and `test`          |
+| `sendora.broadcasts.get(broadcast_id)`    | The broadcast with `status`, `released`, `failed`, `opened`, `clicked` and `links` |
+| `sendora.broadcasts.list(limit=, after=)` | `BroadcastPage` with `broadcasts` and `next`, newest first                         |
+| `sendora.broadcasts.cancel(broadcast_id)` | The cancelled broadcast; what had not left counts as failed                        |
 
 ```python
 accepted = sendora.broadcasts.send(
@@ -305,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
@@ -313,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.1.0 → sendora-2.3.0}/README.md

@@ -91,16 +91,16 @@ for result in batch.results:
 
 ## Messages
 
-| Call                                                            | Answers                                                                           |
-| --------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `sendora.messages.get(message_id)`                              | The message with its recipients, its attachments described and its events         |
-| `sendora.messages.search(**filters)`                            | `MessagePage` with `messages` and `next`, newest first                            |
-| `sendora.messages.search_all(**filters)`                        | Every match, page by page, as an iterator                                         |
-| `sendora.inbound.get(inbound_message_id)`                       | A received message: envelope, parties, headers, text, HTML, attachments described |
-| `sendora.inbound.search(**filters)`                             | `InboundPage` of received mail, newest first                                      |
-| `sendora.inbound.search_all(**filters)`                         | Every received match, page by page, as an iterator                                |
-| `sendora.inbound.raw(inbound_message_id)`                       | The raw message as `bytes`, `message/rfc822`                                      |
-| `sendora.inbound.attachment(inbound_message_id, attachment_id)` | An attachment's `bytes`                                                           |
+| Call                                                            | Answers                                                                               |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `sendora.messages.get(message_id)`                              | The message with its recipients, `tracking`, its attachments described and its events |
+| `sendora.messages.search(**filters)`                            | `MessagePage` with `messages` and `next`, newest first                                |
+| `sendora.messages.search_all(**filters)`                        | Every match, page by page, as an iterator                                             |
+| `sendora.inbound.get(inbound_message_id)`                       | A received message: envelope, parties, headers, text, HTML, attachments described     |
+| `sendora.inbound.search(**filters)`                             | `InboundPage` of received mail, newest first                                          |
+| `sendora.inbound.search_all(**filters)`                         | Every received match, page by page, as an iterator                                    |
+| `sendora.inbound.raw(inbound_message_id)`                       | The raw message as `bytes`, `message/rfc822`                                          |
+| `sendora.inbound.attachment(inbound_message_id, attachment_id)` | An attachment's `bytes`                                                               |
 
 A stream can also receive on a domain of yours: every address on it,
 whatever the local part, lands on the stream. Claim it with the stream
@@ -124,6 +124,11 @@ list of them), `from_` and `to` as an aware `datetime` or ISO 8601,
 `limit` (1 to 100, 50 by default) and `after`, the previous page's
 `next`. Bodies are never returned; the log keeps messages for 13 months.
 
+Where mail is tracked, each recipient has `tracked`, `opens`, `clicks`,
+`first_open_at` and `first_human_open_at`. `messages.get` adds `tracking`, and
+its timeline holds `Open` and `Click` events with their labels. Tracking is
+not open to accounts yet.
+
 ```python
 from datetime import UTC, datetime
 
@@ -176,12 +181,12 @@ message's `substitutions`, up to 20 strings, replace `{{ key }}` in the
 subject, the text and the HTML, escaped in the HTML; a key the content
 names that a message lacks raises `substitution_missing`.
 
-| Call                                      | Answers                                                                   |
-| ----------------------------------------- | ------------------------------------------------------------------------- |
-| `sendora.broadcasts.send(**broadcast)`    | `AcceptedBroadcast` with `broadcast_id`, `total`, `suppressed` and `test` |
-| `sendora.broadcasts.get(broadcast_id)`    | The broadcast with `status`, `released` and `failed`                      |
-| `sendora.broadcasts.list(limit=, after=)` | `BroadcastPage` with `broadcasts` and `next`, newest first                |
-| `sendora.broadcasts.cancel(broadcast_id)` | The cancelled broadcast; what had not left counts as failed               |
+| Call                                      | Answers                                                                            |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| `sendora.broadcasts.send(**broadcast)`    | `AcceptedBroadcast` with `broadcast_id`, `total`, `suppressed` and `test`          |
+| `sendora.broadcasts.get(broadcast_id)`    | The broadcast with `status`, `released`, `failed`, `opened`, `clicked` and `links` |
+| `sendora.broadcasts.list(limit=, after=)` | `BroadcastPage` with `broadcasts` and `next`, newest first                         |
+| `sendora.broadcasts.cancel(broadcast_id)` | The cancelled broadcast; what had not left counts as failed                        |
 
 ```python
 accepted = sendora.broadcasts.send(
@@ -283,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
@@ -291,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.1.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.1.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.1.0"
+__version__ = "2.3.0"

{sendora-2.1.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.1.0 → sendora-2.3.0}/src/sendora/resources/broadcasts.py

@@ -7,7 +7,13 @@ from urllib.parse import quote
 from sendora._answers import decode_sent
 from sendora._transport import AsyncTransport, Call, SyncTransport
 from sendora._wire import decode, encode
-from sendora.types import AcceptedBroadcast, Broadcast, BroadcastPage, BroadcastParams
+from sendora.types import (
+    AcceptedBroadcast,
+    Broadcast,
+    BroadcastDetail,
+    BroadcastPage,
+    BroadcastParams,
+)
 
 
 class Broadcasts:
@@ -74,7 +80,7 @@ class Broadcasts:
         """
         return decode(BroadcastPage, self._transport.send(_list_call(limit, after)))
 
-    def get(self, broadcast_id: str) -> Broadcast:
+    def get(self, broadcast_id: str) -> BroadcastDetail:
         """A broadcast and how far it has come.
 
         ``released`` and ``failed`` move as the worker hands its messages
@@ -84,7 +90,7 @@ class Broadcasts:
             broadcast_id: The broadcast's id.
 
         Returns:
-            The broadcast.
+            The broadcast, with what tracking recorded of it.
 
         Raises:
             NotFoundError: No broadcast of this server has the id.
@@ -93,7 +99,7 @@ class Broadcasts:
             >>> broadcast = sendora.broadcasts.get(broadcast_id)
             >>> print(broadcast.released, "of", broadcast.total)
         """
-        return decode(Broadcast, self._transport.send(_get_call(broadcast_id)))
+        return decode(BroadcastDetail, self._transport.send(_get_call(broadcast_id)))
 
     def cancel(self, broadcast_id: str) -> Broadcast:
         """Holds every message not yet handed to the mail server.
@@ -186,7 +192,7 @@ class AsyncBroadcasts:
             BroadcastPage, await self._transport.send(_list_call(limit, after))
         )
 
-    async def get(self, broadcast_id: str) -> Broadcast:
+    async def get(self, broadcast_id: str) -> BroadcastDetail:
         """A broadcast and how far it has come.
 
         ``released`` and ``failed`` move as the worker hands its messages
@@ -196,7 +202,7 @@ class AsyncBroadcasts:
             broadcast_id: The broadcast's id.
 
         Returns:
-            The broadcast.
+            The broadcast, with what tracking recorded of it.
 
         Raises:
             NotFoundError: No broadcast of this server has the id.
@@ -205,7 +211,9 @@ class AsyncBroadcasts:
             >>> broadcast = await sendora.broadcasts.get(broadcast_id)
             >>> print(broadcast.released, "of", broadcast.total)
         """
-        return decode(Broadcast, await self._transport.send(_get_call(broadcast_id)))
+        return decode(
+            BroadcastDetail, await self._transport.send(_get_call(broadcast_id))
+        )
 
     async def cancel(self, broadcast_id: str) -> Broadcast:
         """Holds every message not yet handed to the mail server.

{sendora-2.1.0 → sendora-2.3.0}/src/sendora/resources/messages.py

@@ -21,7 +21,7 @@ class Messages:
         """One message as the log holds it, with its timeline.
 
         Its recipients with where each stands, its attachments described,
-        and every event, oldest first. Its bodies are never returned.
+        and the events, oldest first. Its bodies are never returned.
 
         Args:
             message_id: The message's id.
@@ -91,7 +91,7 @@ class AsyncMessages:
         """One message as the log holds it, with its timeline.
 
         Its recipients with where each stands, its attachments described,
-        and every event, oldest first. Its bodies are never returned.
+        and the events, oldest first. Its bodies are never returned.
 
         Args:
             message_id: The message's id.

{sendora-2.1.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.1.0 → sendora-2.3.0}/src/sendora/types.py

@@ -39,6 +39,8 @@ __all__ = [
     "BouncedDetails",
     "BouncedEvent",
     "Broadcast",
+    "BroadcastDetail",
+    "BroadcastLink",
     "BroadcastMessageParams",
     "BroadcastPage",
     "BroadcastParams",
@@ -46,6 +48,8 @@ __all__ = [
     "CapEventFields",
     "CapReachedEvent",
     "CapWarningEvent",
+    "ClickedDetails",
+    "ClickedEvent",
     "CnameRecord",
     "CreatedServer",
     "CreatedToken",
@@ -89,12 +93,16 @@ __all__ = [
     "MessageDetail",
     "MessageEvent",
     "MessageEventFields",
+    "MessageEventTracking",
     "MessageEventType",
     "MessagePage",
     "MessageRecipient",
     "MessageSearchParams",
     "MessageStatus",
+    "MessageTracking",
     "MxRecord",
+    "OpenedDetails",
+    "OpenedEvent",
     "OwnServer",
     "RecipientKind",
     "RecipientStatus",
@@ -122,14 +130,21 @@ __all__ = [
     "SuppressionReason",
     "Token",
     "TokenList",
+    "TrackedLink",
+    "TrackingAgent",
+    "TrackingAutomated",
     "TrackingCaaCheck",
     "TrackingCaaCheckResult",
     "TrackingCaaRecord",
+    "TrackingClient",
     "TrackingCnameCheck",
     "TrackingCnameRecord",
+    "TrackingDevice",
     "TrackingDomain",
     "TrackingDomainList",
     "TrackingDomainState",
+    "TrackingReason",
+    "TrackingSkipped",
     "TxtRecord",
     "UnknownEvent",
     "UnsubscribedDetails",
@@ -472,10 +487,58 @@ MessageEventType = Literal[
     "DeferredInjectionRebind",
     "Rejection",
     "Delayed",
+    "Open",
+    "Click",
 ]
 """A step of a message's timeline: ``Reception`` when the mail server took
 it, ``Delivery``, ``TransientFailure``, ``Bounce``, ``OOB`` for a bounce
-report received by mail, ``Feedback`` for a spam complaint."""
+report received by mail, ``Feedback`` for a spam complaint, ``Open`` and
+``Click`` for what tracking recorded."""
+
+TrackingAutomated = Literal["likely", "unlikely", "unknown"]
+"""Whether a machine rather than a person did it: ``unknown`` where nobody
+can tell, as with Apple's privacy protection."""
+
+TrackingAgent = Literal[
+    "apple_privacy",
+    "gmail_prefetch",
+    "gmail_proxy",
+    "yahoo_proxy",
+    "outlook_prefetch",
+    "proton_proxy",
+    "scanner",
+    "crawler",
+]
+"""The proxy or machine an open or a click came through."""
+
+TrackingReason = Literal[
+    "privacy_proxy",
+    "prefetch_signature",
+    "delivery_timing",
+    "link_burst",
+    "scanner_network",
+    "bot_user_agent",
+    "many_networks",
+]
+"""Why an open or a click was labelled a machine's."""
+
+TrackingClient = Literal[
+    "apple_mail",
+    "gmail",
+    "outlook",
+    "yahoo",
+    "thunderbird",
+    "proton",
+    "browser",
+    "other",
+]
+"""The mail program an open or a click came from."""
+
+TrackingDevice = Literal["desktop", "mobile", "tablet"]
+"""The kind of device an open or a click came from."""
+
+TrackingSkipped = Literal["no_tracking_domain", "gmail_clipping"]
+"""Why tracking stayed out of at least one copy of a message."""
 
 
 @model
@@ -486,11 +549,25 @@ class MessageRecipient(Answer):
         address: The address.
         kind: Whether it was in ``to``, ``cc`` or ``bcc``.
         status: Where its delivery stands.
+        tracked: Whether tracking applied to its copy when it left. It does
+            not say to opens, links or both, or that the HTML held a link to
+            track.
+        opens: Opens recorded, machines' included.
+        clicks: Clicks recorded, machines' included.
+        first_open_at: The first open, or the first click that was likely a
+            person's; ``None`` before that.
+        first_human_open_at: The same, counting only what was likely a
+            person; ``None`` before that.
     """
 
     address: str
     kind: RecipientKind
     status: RecipientStatus
+    tracked: bool
+    opens: int
+    clicks: int
+    first_open_at: datetime | None
+    first_human_open_at: datetime | None
 
 
 @model
@@ -542,6 +619,47 @@ class MessageAttachment(Answer):
     size: int
 
 
+@model
+class TrackedLink(Answer):
+    """The link a recipient clicked.
+
+    Attributes:
+        index: Its position in the HTML, the same in every copy, counting
+            from 0.
+        url: Where it led; ``None`` once it has gone with the message's text
+            and HTML.
+    """
+
+    index: int
+    url: str | None
+
+
+@model
+class MessageEventTracking(Answer):
+    """What tracking knows of an ``Open`` or 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 clicked; ``None`` on an ``Open``.
+    """
+
+    automated: TrackingAutomated
+    agent: TrackingAgent | None
+    reasons: list[TrackingReason]
+    client: TrackingClient | None
+    device: TrackingDevice | None
+    first: bool
+    first_human: bool
+    link: TrackedLink | None
+
+
 @model
 class MessageEvent(Answer):
     """One step of a message's timeline.
@@ -555,6 +673,8 @@ class MessageEvent(Answer):
         details: The receiver's response text.
         classification: How a bounce was classified, such as
             ``InvalidRecipient``.
+        tracking: What tracking knows of an ``Open`` or a ``Click``; ``None``
+            on any other event.
     """
 
     recipient: str | None
@@ -563,6 +683,28 @@ class MessageEvent(Answer):
     code: int | None
     details: str | None
     classification: str | None
+    tracking: MessageEventTracking | None
+
+
+@model
+class MessageTracking(Answer):
+    """Whether opens and clicks are recorded now, and why tracking stayed out.
+
+    Attributes:
+        recording_opens: Whether new opens of this message are recorded now,
+            by its own setting, then its broadcast's, then its stream's at
+            this moment. This says nothing of what a copy already sent
+            carries.
+        recording_clicks: The same for clicks on its links.
+        skipped: Why tracking stayed out of at least one copy: the from
+            domain had no working tracking domain, or tracked links would
+            have taken the HTML past where Gmail clips it. Each recipient's
+            ``tracked`` says whether its copy was tracked.
+    """
+
+    recording_opens: bool
+    recording_clicks: bool
+    skipped: TrackingSkipped | None
 
 
 @model
@@ -570,10 +712,13 @@ class MessageDetail(Message):
     """A message with its attachments described and its timeline.
 
     Attributes:
+        tracking: Whether opens and clicks are recorded now.
         attachments: Each attachment, described.
-        events: Every event, oldest first.
+        events: The events, oldest first. Opens and clicks are capped, while
+            each recipient's ``opens`` and ``clicks`` count them all.
     """
 
+    tracking: MessageTracking
     attachments: list[MessageAttachment]
     events: list[MessageEvent]
 
@@ -751,6 +896,47 @@ class Broadcast(Answer):
     completed_at: datetime | None
 
 
+@model
+class BroadcastLink(Answer):
+    """A tracked link of a broadcast that has a click.
+
+    Attributes:
+        index: Its position in the HTML, the same in every copy, counting
+            from 0.
+        url: Where the first click led, since a substitution can give a link
+            another URL per recipient; ``None`` once it has gone with the
+            content.
+        clicked: Recipients who clicked this link, machines' included.
+        clicked_by_people: Those of them likely to be people.
+    """
+
+    index: int
+    url: str | None
+    clicked: int
+    clicked_by_people: int
+
+
+@model
+class BroadcastDetail(Broadcast):
+    """A broadcast, how far it has come and what tracking recorded of it.
+
+    Attributes:
+        opened: Recipients with an open, machines' included, or a click that
+            was likely a person's.
+        opened_by_people: Those of them likely to be people.
+        clicked: Recipients who clicked a link, machines' included.
+        clicked_by_people: Those of them likely to be people.
+        links: Each tracked link that has a click, by its index, counted from
+            the clicks each recipient keeps.
+    """
+
+    opened: int
+    opened_by_people: int
+    clicked: int
+    clicked_by_people: int
+    links: list[BroadcastLink]
+
+
 @model
 class BroadcastPage(Answer):
     """One page of the server's broadcasts, newest first.
@@ -1007,6 +1193,8 @@ WebhookEventName = Literal[
     "deferred",
     "spam_complaint",
     "unsubscribed",
+    "opened",
+    "clicked",
     "cap_warning",
     "cap_reached",
     "inbound",
@@ -1901,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.
@@ -2134,6 +2402,8 @@ WebhookEvent = (
     | DeferredEvent
     | SpamComplaintEvent
     | UnsubscribedEvent
+    | OpenedEvent
+    | ClickedEvent
     | CapWarningEvent
     | CapReachedEvent
     | InboundEvent