sendora 2.4.0__tar.gz → 2.5.0__tar.gz

{sendora-2.4.0 → sendora-2.5.0}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.5.0
+
+- A new event, `TrackingOptedOutEvent`, for `tracking_opted_out`: a recipient
+  asked not to be tracked, through the link that `{{ tracking_opt_out_url }}`
+  puts in your mail. `webhooks.create` without `events` takes it.
+
 ## 2.4.0
 
 - `sendora.tracking_opt_outs` manages a server's not-tracked list: `list`,

{sendora-2.4.0 → sendora-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendora
-Version: 2.4.0
+Version: 2.5.0
 Summary: The Python client for Sendora's email API.
 Project-URL: Homepage, https://sendora.se/docs
 License-Expression: MIT
@@ -262,8 +262,14 @@ until it is.
 
 An entry's `source` is `manual`, or `recipient` if the recipient asked for it.
 Remove a recipient's own entry only after new consent. An entry's `address` is
-`None` once an erasure has left only a keyed hash of it. `delete` still finds
-that entry by its address, and nothing removes it without the address.
+`None` when only a keyed hash of it is left, after an erasure or when the
+recipient asked from mail that had left the log. `delete` still finds that entry
+by its address, and nothing removes it without the address.
+
+To let a recipient ask, write `{{ tracking_opt_out_url }}` in the text or the
+HTML of a message on any stream. Each recipient then gets a copy with their own
+link to a page in Swedish and English. Its button lists the address with the
+`source` `recipient`, and sends the `tracking_opted_out` event.
 
 ```python
 sendora.tracking_opt_outs.add(address="anna@example.com")
@@ -335,7 +341,9 @@ Events: `delivered`, `bounced`, `deferred`, `spam_complaint` and
 `details` from the receiver, or for `unsubscribed` the `source` (`link` or
 `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`,
+a machine did it and, for `clicked`, give the `link`; `tracking_opted_out`
+about a recipient who asked not to be tracked, with the same fields and no
+`details`; `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

{sendora-2.4.0 → sendora-2.5.0}/README.md

@@ -240,8 +240,14 @@ until it is.
 
 An entry's `source` is `manual`, or `recipient` if the recipient asked for it.
 Remove a recipient's own entry only after new consent. An entry's `address` is
-`None` once an erasure has left only a keyed hash of it. `delete` still finds
-that entry by its address, and nothing removes it without the address.
+`None` when only a keyed hash of it is left, after an erasure or when the
+recipient asked from mail that had left the log. `delete` still finds that entry
+by its address, and nothing removes it without the address.
+
+To let a recipient ask, write `{{ tracking_opt_out_url }}` in the text or the
+HTML of a message on any stream. Each recipient then gets a copy with their own
+link to a page in Swedish and English. Its button lists the address with the
+`source` `recipient`, and sends the `tracking_opted_out` event.
 
 ```python
 sendora.tracking_opt_outs.add(address="anna@example.com")
@@ -313,7 +319,9 @@ Events: `delivered`, `bounced`, `deferred`, `spam_complaint` and
 `details` from the receiver, or for `unsubscribed` the `source` (`link` or
 `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`,
+a machine did it and, for `clicked`, give the `link`; `tracking_opted_out`
+about a recipient who asked not to be tracked, with the same fields and no
+`details`; `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

{sendora-2.4.0 → sendora-2.5.0}/src/sendora/__init__.py

@@ -42,6 +42,7 @@ from .types import (
     OpenedEvent,
     SendoraErrorCode,
     SpamComplaintEvent,
+    TrackingOptedOutEvent,
     UnknownEvent,
     UnsubscribedEvent,
     WebhookEvent,
@@ -79,6 +80,7 @@ __all__ = [
     "SendoraError",
     "SendoraErrorCode",
     "SpamComplaintEvent",
+    "TrackingOptedOutEvent",
     "UnknownEvent",
     "UnprocessableEntityError",
     "UnsubscribedEvent",

{sendora-2.4.0 → sendora-2.5.0}/src/sendora/_version.py

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

{sendora-2.4.0 → sendora-2.5.0}/src/sendora/_webhooks.py

@@ -24,6 +24,7 @@ from .types import (
     InboundEventContent,
     OpenedEvent,
     SpamComplaintEvent,
+    TrackingOptedOutEvent,
     UnknownEvent,
     UnsubscribedEvent,
     WebhookEvent,
@@ -173,6 +174,7 @@ _EVENTS: dict[str, Callable[[dict[str, object]], WebhookEvent]] = {
     "unsubscribed": lambda payload: decode(UnsubscribedEvent, payload),
     "opened": lambda payload: decode(OpenedEvent, payload),
     "clicked": lambda payload: decode(ClickedEvent, payload),
+    "tracking_opted_out": lambda payload: decode(TrackingOptedOutEvent, payload),
     "cap_warning": lambda payload: decode(CapWarningEvent, payload),
     "cap_reached": lambda payload: decode(CapReachedEvent, payload),
     "inbound": _inbound,

{sendora-2.4.0 → sendora-2.5.0}/src/sendora/types.py

@@ -146,6 +146,7 @@ __all__ = [
     "TrackingOptOut",
     "TrackingOptOutPage",
     "TrackingOptOutSource",
+    "TrackingOptedOutEvent",
     "TrackingReason",
     "TrackingSkipped",
     "TxtRecord",
@@ -1057,8 +1058,9 @@ class TrackingOptOut(Answer):
     """An address that the server never tracks.
 
     Attributes:
-        address: The address, lower-cased. ``None`` once an erasure has left
-            only a keyed hash.
+        address: The address, lower-cased. ``None`` when only a keyed hash is
+            left: after an erasure, or when the recipient asked from mail that
+            had left the log.
         source: ``manual`` if added through the API or the dashboard,
             ``recipient`` if the recipient asked for it. Remove a recipient's
             own entry only after new consent.
@@ -1236,6 +1238,7 @@ WebhookEventName = Literal[
     "unsubscribed",
     "opened",
     "clicked",
+    "tracking_opted_out",
     "cap_warning",
     "cap_reached",
     "inbound",
@@ -2210,6 +2213,21 @@ class ClickedEvent(MessageEventFields):
     details: ClickedDetails
 
 
+@model
+class TrackingOptedOutEvent(MessageEventFields):
+    """The recipient asked not to be tracked.
+
+    They used the page that ``{{ tracking_opt_out_url }}`` links to, so the
+    address is on the server's not-tracked list. A webhook that leaves out
+    ``events`` gets this event.
+
+    Attributes:
+        event: ``tracking_opted_out``.
+    """
+
+    event: Literal["tracking_opted_out"]
+
+
 @model
 class CapEventFields(Answer):
     """What both usage events carry.
@@ -2445,6 +2463,7 @@ WebhookEvent = (
     | UnsubscribedEvent
     | OpenedEvent
     | ClickedEvent
+    | TrackingOptedOutEvent
     | CapWarningEvent
     | CapReachedEvent
     | InboundEvent