sendora 2.3.0__tar.gz → 2.4.0__tar.gz

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

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.4.0
+
+- `sendora.tracking_opt_outs` manages a server's not-tracked list: `list`,
+  `list_all`, `add` and `delete`. An entry names its `address`, which is
+  `None` once an erasure has left only a keyed hash, and its `source`.
+
 ## 2.3.0
 
 - Two events, `OpenedEvent` and `ClickedEvent`, for `opened` and `clicked`:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendora
-Version: 2.3.0
+Version: 2.4.0
 Summary: The Python client for Sendora's email API.
 Project-URL: Homepage, https://sendora.se/docs
 License-Expression: MIT
@@ -33,7 +33,7 @@ pip install sendora
 
 Two kinds of key, two clients. `Sendora` takes a server key (`sk_…`) and
 does everything inside one server: sending, broadcasts, the log, received
-mail, streams, suppressions, tokens, webhooks and the server's own limits.
+mail, streams, suppressions, the not-tracked list, tokens, webhooks and the server's own limits.
 `SendoraAccount` takes an account key (`ak_…`) and manages the account:
 its servers, their keys, its sending and tracking domains. `AsyncSendora` and
 `AsyncSendoraAccount` are the same clients for asyncio. Both keys are
@@ -246,6 +246,29 @@ request. A refused send carries `stream_id` beside `suppressed`.
 sendora.suppressions.delete(address="anna@example.com")
 ```
 
+## The not-tracked list
+
+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.
+
+| Call                                             | Answers                                                  |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| `sendora.tracking_opt_outs.list(limit=, after=)` | `TrackingOptOutPage` with `tracking_opt_outs` and `next` |
+| `sendora.tracking_opt_outs.list_all()`           | Every entry, as an iterator                              |
+| `sendora.tracking_opt_outs.add(address=)`        | `TrackingOptOut`, as it stands if the address was listed |
+| `sendora.tracking_opt_outs.delete(address=)`     | `None`; `not_found` if the address is not listed         |
+
+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.
+
+```python
+sendora.tracking_opt_outs.add(address="anna@example.com")
+```
+
 ## Tokens
 
 The server's own keys, from its own key. Every key of a server has the
@@ -532,7 +555,7 @@ except SendoraError as error:
 | `account_not_active`              | 403    | The account is not approved to send, or not active for an inbound stream.                                  |
 | `spam_complaint_locked`           | 403    | Only support can lift a spam-complaint suppression.                                                        |
 | `unsubscribe_locked`              | 403    | Only support can lift a recipient's own unsubscribe.                                                       |
-| `not_found`                       | 404    | No such id on this server, or no such suppressed address.                                                  |
+| `not_found`                       | 404    | No such id on this server, or no such suppressed or not-tracked address.                                   |
 | `domain_exists`                   | 409    | The account already has the domain; `existing_id` names it.                                                |
 | `domain_reserved`                 | 400    | The name is Sendora's own; no account can receive on it.                                                   |
 | `tracking_domain_exists`          | 409    | The account already has the host, or one on that sending domain; `existing_id` names it.                   |

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

@@ -11,7 +11,7 @@ pip install sendora
 
 Two kinds of key, two clients. `Sendora` takes a server key (`sk_…`) and
 does everything inside one server: sending, broadcasts, the log, received
-mail, streams, suppressions, tokens, webhooks and the server's own limits.
+mail, streams, suppressions, the not-tracked list, tokens, webhooks and the server's own limits.
 `SendoraAccount` takes an account key (`ak_…`) and manages the account:
 its servers, their keys, its sending and tracking domains. `AsyncSendora` and
 `AsyncSendoraAccount` are the same clients for asyncio. Both keys are
@@ -224,6 +224,29 @@ request. A refused send carries `stream_id` beside `suppressed`.
 sendora.suppressions.delete(address="anna@example.com")
 ```
 
+## The not-tracked list
+
+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.
+
+| Call                                             | Answers                                                  |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| `sendora.tracking_opt_outs.list(limit=, after=)` | `TrackingOptOutPage` with `tracking_opt_outs` and `next` |
+| `sendora.tracking_opt_outs.list_all()`           | Every entry, as an iterator                              |
+| `sendora.tracking_opt_outs.add(address=)`        | `TrackingOptOut`, as it stands if the address was listed |
+| `sendora.tracking_opt_outs.delete(address=)`     | `None`; `not_found` if the address is not listed         |
+
+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.
+
+```python
+sendora.tracking_opt_outs.add(address="anna@example.com")
+```
+
 ## Tokens
 
 The server's own keys, from its own key. Every key of a server has the
@@ -510,7 +533,7 @@ except SendoraError as error:
 | `account_not_active`              | 403    | The account is not approved to send, or not active for an inbound stream.                                  |
 | `spam_complaint_locked`           | 403    | Only support can lift a spam-complaint suppression.                                                        |
 | `unsubscribe_locked`              | 403    | Only support can lift a recipient's own unsubscribe.                                                       |
-| `not_found`                       | 404    | No such id on this server, or no such suppressed address.                                                  |
+| `not_found`                       | 404    | No such id on this server, or no such suppressed or not-tracked address.                                   |
 | `domain_exists`                   | 409    | The account already has the domain; `existing_id` names it.                                                |
 | `domain_reserved`                 | 400    | The name is Sendora's own; no account can receive on it.                                                   |
 | `tracking_domain_exists`          | 409    | The account already has the host, or one on that sending domain; `existing_id` names it.                   |

{sendora-2.3.0 → sendora-2.4.0}/src/sendora/_client.py

@@ -14,6 +14,7 @@ from .resources.server import AsyncThisServer, ThisServer
 from .resources.streams import AsyncStreams, Streams
 from .resources.suppressions import AsyncSuppressions, Suppressions
 from .resources.tokens import AsyncTokens, Tokens
+from .resources.tracking_opt_outs import AsyncTrackingOptOuts, TrackingOptOuts
 from .resources.webhooks import AsyncWebhooks, Webhooks
 
 _SERVER_KEY = "SENDORA_API_TOKEN"
@@ -31,6 +32,7 @@ class Sendora:
         broadcasts: Sends one message to many on a broadcast stream.
         streams: The server's streams.
         suppressions: The addresses each stream no longer sends to.
+        tracking_opt_outs: The addresses the server never tracks.
         tokens: The server's keys.
         server: The key's own server, its mode and its limits.
         webhooks: Where the server's events are posted, and their deliveries.
@@ -100,6 +102,7 @@ class Sendora:
         self.broadcasts: Broadcasts = Broadcasts(transport)
         self.streams: Streams = Streams(transport)
         self.suppressions: Suppressions = Suppressions(transport)
+        self.tracking_opt_outs: TrackingOptOuts = TrackingOptOuts(transport)
         self.tokens: Tokens = Tokens(transport)
         self.server: ThisServer = ThisServer(transport)
         self.webhooks: Webhooks = Webhooks(transport)
@@ -157,6 +160,7 @@ class AsyncSendora:
         broadcasts: Sends one message to many on a broadcast stream.
         streams: The server's streams.
         suppressions: The addresses each stream no longer sends to.
+        tracking_opt_outs: The addresses the server never tracks.
         tokens: The server's keys.
         server: The key's own server, its mode and its limits.
         webhooks: Where the server's events are posted, and their deliveries.
@@ -226,6 +230,7 @@ class AsyncSendora:
         self.broadcasts: AsyncBroadcasts = AsyncBroadcasts(transport)
         self.streams: AsyncStreams = AsyncStreams(transport)
         self.suppressions: AsyncSuppressions = AsyncSuppressions(transport)
+        self.tracking_opt_outs: AsyncTrackingOptOuts = AsyncTrackingOptOuts(transport)
         self.tokens: AsyncTokens = AsyncTokens(transport)
         self.server: AsyncThisServer = AsyncThisServer(transport)
         self.webhooks: AsyncWebhooks = AsyncWebhooks(transport)

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

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

{sendora-2.3.0 → sendora-2.4.0}/src/sendora/resources/__init__.py

@@ -13,6 +13,7 @@ from .streams import AsyncStreams, Streams
 from .suppressions import AsyncSuppressions, Suppressions
 from .tokens import AsyncTokens, Tokens
 from .tracking_domains import AsyncTrackingDomains, TrackingDomains
+from .tracking_opt_outs import AsyncTrackingOptOuts, TrackingOptOuts
 from .webhooks import AsyncWebhooks, Webhooks
 
 __all__ = [
@@ -30,6 +31,7 @@ __all__ = [
     "AsyncThisServer",
     "AsyncTokens",
     "AsyncTrackingDomains",
+    "AsyncTrackingOptOuts",
     "AsyncWebhooks",
     "Broadcasts",
     "Domains",
@@ -45,5 +47,6 @@ __all__ = [
     "ThisServer",
     "Tokens",
     "TrackingDomains",
+    "TrackingOptOuts",
     "Webhooks",
 ]

sendora-2.4.0/src/sendora/resources/tracking_opt_outs.py

@@ -0,0 +1,226 @@
+"""The addresses the key's server never tracks, one list per server."""
+
+from collections.abc import AsyncIterator, Iterator
+
+from sendora._pages import iterate, iterate_async
+from sendora._transport import AsyncTransport, Call, SyncTransport
+from sendora._wire import decode
+from sendora.types import TrackingOptOut, TrackingOptOutPage
+
+
+class TrackingOptOuts:
+    """Reads the server's not-tracked list, adds an address and removes one."""
+
+    def __init__(self, transport: SyncTransport) -> None:
+        """Takes the client's transport."""
+        self._transport = transport
+
+    def list(
+        self, *, limit: int | None = None, after: str | None = None
+    ) -> TrackingOptOutPage:
+        """One page of the server's not-tracked list, newest first.
+
+        An entry whose ``address`` is ``None`` was erased, and only a keyed
+        hash of it remains.
+
+        Args:
+            limit: The page size, 1 to 1000; 100 when left out.
+            after: The ``next`` of the previous page.
+
+        Returns:
+            The page.
+
+        Example:
+            >>> page = sendora.tracking_opt_outs.list(limit=200)
+        """
+        return decode(
+            TrackingOptOutPage, self._transport.send(_list_call(limit, after))
+        )
+
+    def list_all(
+        self, *, limit: int | None = None, after: str | None = None
+    ) -> Iterator[TrackingOptOut]:
+        """Every entry of the list, page by page, from ``after`` on.
+
+        Each page is a request of its own, repeated on its own when it
+        fails.
+
+        Args:
+            limit: The page size, 1 to 1000; 100 when left out.
+            after: The cursor to begin after.
+
+        Yields:
+            Each entry.
+
+        Example:
+            >>> for entry in sendora.tracking_opt_outs.list_all():
+            ...     print(entry.address, entry.source)
+        """
+        yield from iterate(
+            lambda cursor: self.list(limit=limit, after=cursor),
+            _entries_of,
+            _next_of,
+            after,
+        )
+
+    def add(self, *, address: str) -> TrackingOptOut:
+        """Puts an address on the server's list, so that it is never tracked.
+
+        That holds for mail already sent too. An address already on the list
+        changes nothing, and the entry comes back as it stands.
+
+        Args:
+            address: The address never to track.
+
+        Returns:
+            The entry.
+
+        Example:
+            >>> entry = sendora.tracking_opt_outs.add(address="anna@example.com")
+        """
+        return decode(TrackingOptOut, self._transport.send(_add_call(address)))
+
+    def delete(self, *, address: str) -> None:
+        """Takes an address off the server's list, so it can be tracked again.
+
+        Remove an entry whose ``source`` is ``recipient`` only after new
+        consent. An erased entry is found by its address too. A delete
+        repeated after a lost answer whose first attempt took effect raises
+        ``not_found``.
+
+        Args:
+            address: The address to track again.
+
+        Raises:
+            NotFoundError: The address is not on the list.
+
+        Example:
+            >>> sendora.tracking_opt_outs.delete(address="anna@example.com")
+        """
+        self._transport.send(_delete_call(address))
+
+
+class AsyncTrackingOptOuts:
+    """Reads the server's not-tracked list, adds an address and removes one."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        """Takes the client's transport."""
+        self._transport = transport
+
+    async def list(
+        self, *, limit: int | None = None, after: str | None = None
+    ) -> TrackingOptOutPage:
+        """One page of the server's not-tracked list, newest first.
+
+        An entry whose ``address`` is ``None`` was erased, and only a keyed
+        hash of it remains.
+
+        Args:
+            limit: The page size, 1 to 1000; 100 when left out.
+            after: The ``next`` of the previous page.
+
+        Returns:
+            The page.
+
+        Example:
+            >>> page = await sendora.tracking_opt_outs.list(limit=200)
+        """
+        return decode(
+            TrackingOptOutPage, await self._transport.send(_list_call(limit, after))
+        )
+
+    async def list_all(
+        self, *, limit: int | None = None, after: str | None = None
+    ) -> AsyncIterator[TrackingOptOut]:
+        """Every entry of the list, page by page, from ``after`` on.
+
+        Each page is a request of its own, repeated on its own when it
+        fails.
+
+        Args:
+            limit: The page size, 1 to 1000; 100 when left out.
+            after: The cursor to begin after.
+
+        Yields:
+            Each entry.
+
+        Example:
+            >>> async for entry in sendora.tracking_opt_outs.list_all():
+            ...     print(entry.address, entry.source)
+        """
+        async for entry in iterate_async(
+            lambda cursor: self.list(limit=limit, after=cursor),
+            _entries_of,
+            _next_of,
+            after,
+        ):
+            yield entry
+
+    async def add(self, *, address: str) -> TrackingOptOut:
+        """Puts an address on the server's list, so that it is never tracked.
+
+        That holds for mail already sent too. An address already on the list
+        changes nothing, and the entry comes back as it stands.
+
+        Args:
+            address: The address never to track.
+
+        Returns:
+            The entry.
+
+        Example:
+            >>> entry = await sendora.tracking_opt_outs.add(address="anna@example.com")
+        """
+        return decode(TrackingOptOut, await self._transport.send(_add_call(address)))
+
+    async def delete(self, *, address: str) -> None:
+        """Takes an address off the server's list, so it can be tracked again.
+
+        Remove an entry whose ``source`` is ``recipient`` only after new
+        consent. An erased entry is found by its address too. A delete
+        repeated after a lost answer whose first attempt took effect raises
+        ``not_found``.
+
+        Args:
+            address: The address to track again.
+
+        Raises:
+            NotFoundError: The address is not on the list.
+
+        Example:
+            >>> await sendora.tracking_opt_outs.delete(address="anna@example.com")
+        """
+        await self._transport.send(_delete_call(address))
+
+
+def _list_call(limit: int | None, after: str | None) -> Call:
+    return Call(
+        "GET",
+        "/v1/tracking-opt-outs",
+        idempotent=True,
+        query={"limit": limit, "after": after},
+    )
+
+
+def _add_call(address: str) -> Call:
+    return Call(
+        "POST", "/v1/tracking-opt-outs", idempotent=True, body={"address": address}
+    )
+
+
+def _delete_call(address: str) -> Call:
+    return Call(
+        "POST",
+        "/v1/tracking-opt-outs/delete",
+        idempotent=True,
+        body={"address": address},
+        expect="none",
+    )
+
+
+def _entries_of(page: TrackingOptOutPage) -> list[TrackingOptOut]:
+    return page.tracking_opt_outs
+
+
+def _next_of(page: TrackingOptOutPage) -> str | None:
+    return page.next

{sendora-2.3.0 → sendora-2.4.0}/src/sendora/skills/sendora/SKILL.md

@@ -14,7 +14,8 @@ and every event is in it.
 
 - Two kinds of key, two clients. A server key (`sk_…`) drives
   `Sendora()`: `email`, `broadcasts`, `messages`, `inbound`,
-  `inbound_domains`, `server`, `streams`, `suppressions`, `tokens`,
+  `inbound_domains`, `server`, `streams`, `suppressions`,
+  `tracking_opt_outs`, `tokens`,
   `webhooks`, everything inside one server. An account key (`ak_…`)
   drives `SendoraAccount()`: `servers`, `servers.tokens`, `domains` and
   `tracking_domains`, and it never sends. A key of the wrong kind raises `wrong_token_kind`.
@@ -63,6 +64,9 @@ and every event is in it.
   comparing `event.event`, and handle `UnknownEvent`, an event newer than
   the release. Answer 2xx quickly and do the work afterwards. Deliveries
   arrive at least once, so key handling on `event.id`.
+- `tracking_opt_outs` is the server's list of addresses that are never
+  tracked. Remove an entry whose `source` is `recipient` only after new
+  consent. An erased entry has `address=None`, and only its address removes it.
 - Addresses on the suppression list are refused with
   `recipient_suppressed`; lift a hard bounce with
   `suppressions.delete(address=...)`; a spam complaint or an unsubscribe

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

@@ -143,6 +143,9 @@ __all__ = [
     "TrackingDomain",
     "TrackingDomainList",
     "TrackingDomainState",
+    "TrackingOptOut",
+    "TrackingOptOutPage",
+    "TrackingOptOutSource",
     "TrackingReason",
     "TrackingSkipped",
     "TxtRecord",
@@ -1045,6 +1048,44 @@ class SuppressionPage(Answer):
     next: str | None
 
 
+TrackingOptOutSource = Literal["manual", "recipient"]
+"""How an address came onto a server's not-tracked list."""
+
+
+@model
+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.
+        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.
+        message_id: The message that a recipient asked from. ``None`` on a
+            manual entry, and once that message or the address has gone.
+        created_at: When it was added.
+    """
+
+    address: str | None
+    source: TrackingOptOutSource
+    message_id: str | None
+    created_at: datetime
+
+
+@model
+class TrackingOptOutPage(Answer):
+    """One page of a server's not-tracked list, newest first.
+
+    Attributes:
+        tracking_opt_outs: The page's entries.
+        next: Pass as ``after`` for the next page; ``None`` on the last.
+    """
+
+    tracking_opt_outs: list[TrackingOptOut]
+    next: str | None
+
+
 @model
 class Token(Answer):
     """A key of a server; its value is shown only when it is created.