sendora 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendora
-Version: 2.1.0
+Version: 2.2.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(

{sendora-2.1.0 → sendora-2.2.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(

{sendora-2.1.0 → sendora-2.2.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.2.0"

{sendora-2.1.0 → sendora-2.2.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.2.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.2.0}/src/sendora/types.py

@@ -39,6 +39,8 @@ __all__ = [
     "BouncedDetails",
     "BouncedEvent",
     "Broadcast",
+    "BroadcastDetail",
+    "BroadcastLink",
     "BroadcastMessageParams",
     "BroadcastPage",
     "BroadcastParams",
@@ -89,11 +91,13 @@ __all__ = [
     "MessageDetail",
     "MessageEvent",
     "MessageEventFields",
+    "MessageEventTracking",
     "MessageEventType",
     "MessagePage",
     "MessageRecipient",
     "MessageSearchParams",
     "MessageStatus",
+    "MessageTracking",
     "MxRecord",
     "OwnServer",
     "RecipientKind",
@@ -122,14 +126,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 +483,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 Mail."""
+
+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 +545,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 +615,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 +669,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 +679,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 +708,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 +892,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.