sendora 2.4.0__tar.gz → 2.5.1__tar.gz

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

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.5.1
+
+- The README no longer says that tracking is not open to accounts. It says
+  that an administrator switches tracking on for a stream in the dashboard.
+  No call changes.
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendora
-Version: 2.4.0
+Version: 2.5.1
 Summary: The Python client for Sendora's email API.
 Project-URL: Homepage, https://sendora.se/docs
 License-Expression: MIT
@@ -148,8 +148,8 @@ list of them), `from_` and `to` as an aware `datetime` or ISO 8601,
 
 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.
+its timeline holds `Open` and `Click` events with their labels. An
+administrator switches tracking on for a stream in the dashboard.
 
 ```python
 from datetime import UTC, datetime
@@ -250,8 +250,7 @@ sendora.suppressions.delete(address="anna@example.com")
 
 Addresses the server never tracks, on any of its streams. Mail to one still
 goes out, untracked, and its opens and clicks of mail already sent are not
-recorded. Tracking is not open to accounts yet, so the list changes nothing
-until it is.
+recorded.
 
 | Call                                             | Answers                                                  |
 | ------------------------------------------------ | -------------------------------------------------------- |
@@ -262,8 +261,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 +340,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
@@ -343,8 +350,7 @@ 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`. Tracking is
-not open to accounts yet, so `opened` and `clicked` are not sent until it is.
+period. Every event carries `id`, the delivery id, and `attempt`.
 
 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
@@ -469,9 +475,8 @@ print(domain.dkim.type, domain.dkim.host, domain.dkim.value)
 
 A tracking domain is the host that tracked links and the open pixel use: a
 subdomain of a verified sending domain, with one CNAME record to add. CAA
-records above it must let Let's Encrypt issue its certificate. Tracking is
-not open to accounts yet, so a host carries no mail until it is. A host
-whose records are not right within 7 days goes.
+records above it must let Let's Encrypt issue its certificate. A host whose
+records are not right within 7 days goes.
 
 | Call                                                  | Answers                                                               |
 | ----------------------------------------------------- | --------------------------------------------------------------------- |

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

@@ -126,8 +126,8 @@ list of them), `from_` and `to` as an aware `datetime` or ISO 8601,
 
 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.
+its timeline holds `Open` and `Click` events with their labels. An
+administrator switches tracking on for a stream in the dashboard.
 
 ```python
 from datetime import UTC, datetime
@@ -228,8 +228,7 @@ sendora.suppressions.delete(address="anna@example.com")
 
 Addresses the server never tracks, on any of its streams. Mail to one still
 goes out, untracked, and its opens and clicks of mail already sent are not
-recorded. Tracking is not open to accounts yet, so the list changes nothing
-until it is.
+recorded.
 
 | Call                                             | Answers                                                  |
 | ------------------------------------------------ | -------------------------------------------------------- |
@@ -240,8 +239,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 +318,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
@@ -321,8 +328,7 @@ 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`. Tracking is
-not open to accounts yet, so `opened` and `clicked` are not sent until it is.
+period. Every event carries `id`, the delivery id, and `attempt`.
 
 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
@@ -447,9 +453,8 @@ print(domain.dkim.type, domain.dkim.host, domain.dkim.value)
 
 A tracking domain is the host that tracked links and the open pixel use: a
 subdomain of a verified sending domain, with one CNAME record to add. CAA
-records above it must let Let's Encrypt issue its certificate. Tracking is
-not open to accounts yet, so a host carries no mail until it is. A host
-whose records are not right within 7 days goes.
+records above it must let Let's Encrypt issue its certificate. A host whose
+records are not right within 7 days goes.
 
 | Call                                                  | Answers                                                               |
 | ----------------------------------------------------- | --------------------------------------------------------------------- |

{sendora-2.4.0 → sendora-2.5.1}/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.1}/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.1"

{sendora-2.4.0 → sendora-2.5.1}/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.1}/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