sendora 2.0.2__tar.gz → 2.2.0__tar.gz

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

@@ -1,5 +1,21 @@
 # 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`
+  add, list, read, check and remove tracking domains, with the models
+  `TrackingDomain` and `TrackingDomainList` and five new error codes.
+
 ## 2.0.2
 
 - The README says what `payment_required` means in each of its four cases:

{sendora-2.0.2 → sendora-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendora
-Version: 2.0.2
+Version: 2.2.0
 Summary: The Python client for Sendora's email API.
 Project-URL: Homepage, https://sendora.se/docs
 License-Expression: MIT
@@ -35,7 +35,7 @@ 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.
 `SendoraAccount` takes an account key (`ak_…`) and manages the account:
-its servers, their keys and its sending domains. `AsyncSendora` and
+its servers, their keys, its sending and tracking domains. `AsyncSendora` and
 `AsyncSendoraAccount` are the same clients for asyncio. Both keys are
 secrets: keep them on the server and never ship them to a browser.
 
@@ -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(
@@ -436,6 +441,25 @@ print(domain.return_path.type, domain.return_path.host, domain.return_path.value
 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.
+
+| Call                                                  | Answers                                                               |
+| ----------------------------------------------------- | --------------------------------------------------------------------- |
+| `account.tracking_domains.create(host=)`              | `TrackingDomain` with `cname` to add                                  |
+| `account.tracking_domains.list()`                     | `TrackingDomainList` with `tracking_domains`                          |
+| `account.tracking_domains.get(tracking_domain_id)`    | One tracking domain with what the last check found                    |
+| `account.tracking_domains.verify(tracking_domain_id)` | The tracking domain as it stands: `state`, `cname.check`, `caa.check` |
+| `account.tracking_domains.delete(tracking_domain_id)` | `None`; new mail stops using it at once                               |
+
+```python
+tracking = account.tracking_domains.create(host="links.example.se")
+print(tracking.cname.type, tracking.cname.host, tracking.cname.value)
+```
+
 An erasure removes one person's data from every server of the account,
 as a request under the right to erasure asks. The content of every
 message to or from the address, sent and received, is deleted, and the
@@ -508,6 +532,11 @@ except SendoraError as error:
 | `not_found`                       | 404    | No such id on this server, or no such suppressed 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.                   |
+| `tracking_domain_limit`           | 409    | The account has as many tracking domains as it may.                                                        |
+| `tracking_host_is_sending_domain` | 422    | The host is a sending domain itself; choose a subdomain.                                                   |
+| `tracking_host_not_verified`      | 422    | The host is not under a verified sending domain of the account.                                            |
+| `tracking_host_taken`             | 409    | Another account holds the host.                                                                            |
 | `inbound_domain_exists`           | 409    | The stream already has a domain (`existing_id` names it), or another account holds the name verified.      |
 | `webhook_exists`                  | 409    | The server already has a webhook for that URL; `existing_id` names it.                                     |
 | `stream_exists`                   | 409    | The server already has a stream with that name; `existing_id` names it.                                    |
@@ -574,7 +603,7 @@ seconds of waiting in all. A longer `retry_after` is raised at once for
 you to schedule. A call that creates something (`streams.create`,
 `tokens.create`, `webhooks.create`, `webhooks.create_secret`,
 `webhooks.replay`, `inbound_domains.create`, `servers.create`,
-`servers.tokens.create`, `domains.create`) is repeated only after a
+`servers.tokens.create`, `domains.create`, `tracking_domains.create`) is repeated only after a
 `rate_limited` or `sending_disabled` answer, never after a lost connection
 or a server error, so nothing is created twice. Nothing else is retried.
 

{sendora-2.0.2 → sendora-2.2.0}/README.md

@@ -13,7 +13,7 @@ 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.
 `SendoraAccount` takes an account key (`ak_…`) and manages the account:
-its servers, their keys and its sending domains. `AsyncSendora` and
+its servers, their keys, its sending and tracking domains. `AsyncSendora` and
 `AsyncSendoraAccount` are the same clients for asyncio. Both keys are
 secrets: keep them on the server and never ship them to a browser.
 
@@ -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(
@@ -414,6 +419,25 @@ print(domain.return_path.type, domain.return_path.host, domain.return_path.value
 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.
+
+| Call                                                  | Answers                                                               |
+| ----------------------------------------------------- | --------------------------------------------------------------------- |
+| `account.tracking_domains.create(host=)`              | `TrackingDomain` with `cname` to add                                  |
+| `account.tracking_domains.list()`                     | `TrackingDomainList` with `tracking_domains`                          |
+| `account.tracking_domains.get(tracking_domain_id)`    | One tracking domain with what the last check found                    |
+| `account.tracking_domains.verify(tracking_domain_id)` | The tracking domain as it stands: `state`, `cname.check`, `caa.check` |
+| `account.tracking_domains.delete(tracking_domain_id)` | `None`; new mail stops using it at once                               |
+
+```python
+tracking = account.tracking_domains.create(host="links.example.se")
+print(tracking.cname.type, tracking.cname.host, tracking.cname.value)
+```
+
 An erasure removes one person's data from every server of the account,
 as a request under the right to erasure asks. The content of every
 message to or from the address, sent and received, is deleted, and the
@@ -486,6 +510,11 @@ except SendoraError as error:
 | `not_found`                       | 404    | No such id on this server, or no such suppressed 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.                   |
+| `tracking_domain_limit`           | 409    | The account has as many tracking domains as it may.                                                        |
+| `tracking_host_is_sending_domain` | 422    | The host is a sending domain itself; choose a subdomain.                                                   |
+| `tracking_host_not_verified`      | 422    | The host is not under a verified sending domain of the account.                                            |
+| `tracking_host_taken`             | 409    | Another account holds the host.                                                                            |
 | `inbound_domain_exists`           | 409    | The stream already has a domain (`existing_id` names it), or another account holds the name verified.      |
 | `webhook_exists`                  | 409    | The server already has a webhook for that URL; `existing_id` names it.                                     |
 | `stream_exists`                   | 409    | The server already has a stream with that name; `existing_id` names it.                                    |
@@ -552,7 +581,7 @@ seconds of waiting in all. A longer `retry_after` is raised at once for
 you to schedule. A call that creates something (`streams.create`,
 `tokens.create`, `webhooks.create`, `webhooks.create_secret`,
 `webhooks.replay`, `inbound_domains.create`, `servers.create`,
-`servers.tokens.create`, `domains.create`) is repeated only after a
+`servers.tokens.create`, `domains.create`, `tracking_domains.create`) is repeated only after a
 `rate_limited` or `sending_disabled` answer, never after a lost connection
 or a server error, so nothing is created twice. Nothing else is retried.
 

{sendora-2.0.2 → sendora-2.2.0}/src/sendora/_account.py

@@ -8,6 +8,7 @@ from ._transport import AsyncHttpClient, AsyncTransport, HttpClient, SyncTranspo
 from .resources.domains import AsyncDomains, Domains
 from .resources.erasures import AsyncErasures, Erasures
 from .resources.servers import AsyncServers, Servers
+from .resources.tracking_domains import AsyncTrackingDomains, TrackingDomains
 
 _ACCOUNT_KEY = "SENDORA_ACCOUNT_TOKEN"
 
@@ -23,6 +24,7 @@ class SendoraAccount:
     Attributes:
         servers: The account's servers, and each server's keys.
         domains: The account's sending domains.
+        tracking_domains: The hosts that tracked links and the open pixel use.
         erasures: A person's data erased from every server of the account.
 
     Example:
@@ -81,6 +83,7 @@ class SendoraAccount:
         self._transport = transport
         self.servers: Servers = Servers(transport)
         self.domains: Domains = Domains(transport)
+        self.tracking_domains: TrackingDomains = TrackingDomains(transport)
         self.erasures: Erasures = Erasures(transport)
 
     def with_options(
@@ -131,6 +134,7 @@ class AsyncSendoraAccount:
     Attributes:
         servers: The account's servers, and each server's keys.
         domains: The account's sending domains.
+        tracking_domains: The hosts that tracked links and the open pixel use.
         erasures: A person's data erased from every server of the account.
 
     Example:
@@ -188,6 +192,7 @@ class AsyncSendoraAccount:
         self._transport = transport
         self.servers: AsyncServers = AsyncServers(transport)
         self.domains: AsyncDomains = AsyncDomains(transport)
+        self.tracking_domains: AsyncTrackingDomains = AsyncTrackingDomains(transport)
         self.erasures: AsyncErasures = AsyncErasures(transport)
 
     def with_options(

{sendora-2.0.2 → sendora-2.2.0}/src/sendora/_answers.py

@@ -246,6 +246,7 @@ _EXISTING_IDS = {
     "stream_exists": "streamId",
     "inbound_stream_exists": "streamId",
     "inbound_domain_exists": "inboundDomainId",
+    "tracking_domain_exists": "trackingDomainId",
 }
 
 

{sendora-2.0.2 → 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.0.2"
+__version__ = "2.2.0"

{sendora-2.0.2 → sendora-2.2.0}/src/sendora/resources/__init__.py

@@ -12,6 +12,7 @@ from .servers import AsyncServers, AsyncServerTokens, Servers, ServerTokens
 from .streams import AsyncStreams, Streams
 from .suppressions import AsyncSuppressions, Suppressions
 from .tokens import AsyncTokens, Tokens
+from .tracking_domains import AsyncTrackingDomains, TrackingDomains
 from .webhooks import AsyncWebhooks, Webhooks
 
 __all__ = [
@@ -28,6 +29,7 @@ __all__ = [
     "AsyncSuppressions",
     "AsyncThisServer",
     "AsyncTokens",
+    "AsyncTrackingDomains",
     "AsyncWebhooks",
     "Broadcasts",
     "Domains",
@@ -42,5 +44,6 @@ __all__ = [
     "Suppressions",
     "ThisServer",
     "Tokens",
+    "TrackingDomains",
     "Webhooks",
 ]

{sendora-2.0.2 → 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.0.2 → 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.2.0/src/sendora/resources/tracking_domains.py

@@ -0,0 +1,236 @@
+"""The account's tracking domains, which tracked links and the open pixel use."""
+
+from urllib.parse import quote
+
+from sendora._transport import AsyncTransport, Call, SyncTransport
+from sendora._wire import decode
+from sendora.types import TrackingDomain, TrackingDomainList
+
+
+class TrackingDomains:
+    """Adds, checks and removes the hosts that tracked links use."""
+
+    def __init__(self, transport: SyncTransport) -> None:
+        """Takes the client's transport."""
+        self._transport = transport
+
+    def create(self, *, host: str) -> TrackingDomain:
+        """Claims a host under a verified sending domain and answers the record to add.
+
+        A host whose records are not right within 7 days goes. A create is
+        never repeated after a lost connection, which may have claimed it.
+
+        Args:
+            host: The host, such as ``links.example.se``.
+
+        Returns:
+            The tracking domain, with the CNAME record to add.
+
+        Raises:
+            ConflictError: The account has the host or one on that sending
+                domain (``tracking_domain_exists``, with ``existing_id``),
+                another account holds it (``tracking_host_taken``), or the
+                account has no room (``tracking_domain_limit``).
+            UnprocessableEntityError: The host is not under a verified sending
+                domain, or is one itself.
+
+        Example:
+            >>> added = account.tracking_domains.create(host="links.example.se")
+            >>> print(added.cname.host, added.cname.value)
+        """
+        return decode(TrackingDomain, self._transport.send(_create_call(host)))
+
+    def list(self) -> TrackingDomainList:
+        """Every tracking domain of the account.
+
+        Returns:
+            The tracking domains.
+
+        Example:
+            >>> listed = account.tracking_domains.list()
+            >>> print(len(listed.tracking_domains))
+        """
+        return decode(TrackingDomainList, self._transport.send(_LIST))
+
+    def get(self, tracking_domain_id: str) -> TrackingDomain:
+        """One tracking domain by its id, with what the last check found.
+
+        Args:
+            tracking_domain_id: The tracking domain's id.
+
+        Returns:
+            The tracking domain.
+
+        Raises:
+            NotFoundError: The account has no tracking domain with the id.
+
+        Example:
+            >>> domain = account.tracking_domains.get(tracking_domain_id)
+        """
+        call = _get_call(tracking_domain_id)
+        return decode(TrackingDomain, self._transport.send(call))
+
+    def verify(self, tracking_domain_id: str) -> TrackingDomain:
+        """Looks the CNAME and the CAA records up now.
+
+        A ``dns_error`` changes nothing.
+
+        Args:
+            tracking_domain_id: The tracking domain's id.
+
+        Returns:
+            The tracking domain as it stands.
+
+        Raises:
+            NotFoundError: The account has no tracking domain with the id.
+
+        Example:
+            >>> checked = account.tracking_domains.verify(tracking_domain_id)
+            >>> print(checked.state, checked.cname.check, checked.caa.check)
+        """
+        call = _verify_call(tracking_domain_id)
+        return decode(TrackingDomain, self._transport.send(call))
+
+    def delete(self, tracking_domain_id: str) -> None:
+        """Removes the tracking domain; new mail stops using it at once.
+
+        Links in sent mail keep working while the CNAME record points at
+        Sendora. A delete repeated after a lost answer whose first attempt
+        took effect raises ``not_found``.
+
+        Args:
+            tracking_domain_id: The tracking domain's id.
+
+        Raises:
+            NotFoundError: The account has no tracking domain with the id.
+
+        Example:
+            >>> account.tracking_domains.delete(tracking_domain_id)
+        """
+        self._transport.send(_delete_call(tracking_domain_id))
+
+
+class AsyncTrackingDomains:
+    """Adds, checks and removes the hosts that tracked links use."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        """Takes the client's transport."""
+        self._transport = transport
+
+    async def create(self, *, host: str) -> TrackingDomain:
+        """Claims a host under a verified sending domain and answers the record to add.
+
+        A host whose records are not right within 7 days goes. A create is
+        never repeated after a lost connection, which may have claimed it.
+
+        Args:
+            host: The host, such as ``links.example.se``.
+
+        Returns:
+            The tracking domain, with the CNAME record to add.
+
+        Raises:
+            ConflictError: The account has the host or one on that sending
+                domain (``tracking_domain_exists``, with ``existing_id``),
+                another account holds it (``tracking_host_taken``), or the
+                account has no room (``tracking_domain_limit``).
+            UnprocessableEntityError: The host is not under a verified sending
+                domain, or is one itself.
+
+        Example:
+            >>> added = await account.tracking_domains.create(host="links.example.se")
+            >>> print(added.cname.host, added.cname.value)
+        """
+        return decode(TrackingDomain, await self._transport.send(_create_call(host)))
+
+    async def list(self) -> TrackingDomainList:
+        """Every tracking domain of the account.
+
+        Returns:
+            The tracking domains.
+
+        Example:
+            >>> listed = await account.tracking_domains.list()
+            >>> print(len(listed.tracking_domains))
+        """
+        return decode(TrackingDomainList, await self._transport.send(_LIST))
+
+    async def get(self, tracking_domain_id: str) -> TrackingDomain:
+        """One tracking domain by its id, with what the last check found.
+
+        Args:
+            tracking_domain_id: The tracking domain's id.
+
+        Returns:
+            The tracking domain.
+
+        Raises:
+            NotFoundError: The account has no tracking domain with the id.
+
+        Example:
+            >>> domain = await account.tracking_domains.get(tracking_domain_id)
+        """
+        call = _get_call(tracking_domain_id)
+        return decode(TrackingDomain, await self._transport.send(call))
+
+    async def verify(self, tracking_domain_id: str) -> TrackingDomain:
+        """Looks the CNAME and the CAA records up now.
+
+        A ``dns_error`` changes nothing.
+
+        Args:
+            tracking_domain_id: The tracking domain's id.
+
+        Returns:
+            The tracking domain as it stands.
+
+        Raises:
+            NotFoundError: The account has no tracking domain with the id.
+
+        Example:
+            >>> checked = await account.tracking_domains.verify(tracking_domain_id)
+            >>> print(checked.state, checked.cname.check, checked.caa.check)
+        """
+        call = _verify_call(tracking_domain_id)
+        return decode(TrackingDomain, await self._transport.send(call))
+
+    async def delete(self, tracking_domain_id: str) -> None:
+        """Removes the tracking domain; new mail stops using it at once.
+
+        Links in sent mail keep working while the CNAME record points at
+        Sendora. A delete repeated after a lost answer whose first attempt
+        took effect raises ``not_found``.
+
+        Args:
+            tracking_domain_id: The tracking domain's id.
+
+        Raises:
+            NotFoundError: The account has no tracking domain with the id.
+
+        Example:
+            >>> await account.tracking_domains.delete(tracking_domain_id)
+        """
+        await self._transport.send(_delete_call(tracking_domain_id))
+
+
+_LIST = Call("GET", "/v1/tracking-domains", idempotent=True)
+
+
+def _create_call(host: str) -> Call:
+    return Call("POST", "/v1/tracking-domains", idempotent=False, body={"host": host})
+
+
+def _get_call(tracking_domain_id: str) -> Call:
+    return Call("GET", _path(tracking_domain_id), idempotent=True)
+
+
+def _verify_call(tracking_domain_id: str) -> Call:
+    return Call("POST", f"{_path(tracking_domain_id)}/verify", idempotent=True)
+
+
+def _delete_call(tracking_domain_id: str) -> Call:
+    return Call("DELETE", _path(tracking_domain_id), idempotent=True, expect="none")
+
+
+def _path(tracking_domain_id: str) -> str:
+    return f"/v1/tracking-domains/{quote(tracking_domain_id, safe='')}"

{sendora-2.0.2 → sendora-2.2.0}/src/sendora/skills/sendora/SKILL.md

@@ -16,8 +16,8 @@ and every event is in it.
   `Sendora()`: `email`, `broadcasts`, `messages`, `inbound`,
   `inbound_domains`, `server`, `streams`, `suppressions`, `tokens`,
   `webhooks`, everything inside one server. An account key (`ak_…`)
-  drives `SendoraAccount()`: `servers`, `servers.tokens` and `domains`,
-  and it never sends. A key of the wrong kind raises `wrong_token_kind`.
+  drives `SendoraAccount()`: `servers`, `servers.tokens`, `domains` and
+  `tracking_domains`, and it never sends. A key of the wrong kind raises `wrong_token_kind`.
   `AsyncSendora` and `AsyncSendoraAccount` are the same clients for
   asyncio; use them in async code and never call the regular ones there.
 - Every key is a secret. Leave `token` out and the clients read

{sendora-2.0.2 → 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,6 +126,21 @@ __all__ = [
     "SuppressionReason",
     "Token",
     "TokenList",
+    "TrackedLink",
+    "TrackingAgent",
+    "TrackingAutomated",
+    "TrackingCaaCheck",
+    "TrackingCaaCheckResult",
+    "TrackingCaaRecord",
+    "TrackingClient",
+    "TrackingCnameCheck",
+    "TrackingCnameRecord",
+    "TrackingDevice",
+    "TrackingDomain",
+    "TrackingDomainList",
+    "TrackingDomainState",
+    "TrackingReason",
+    "TrackingSkipped",
     "TxtRecord",
     "UnknownEvent",
     "UnsubscribedDetails",
@@ -175,6 +194,11 @@ SendoraErrorCode = Literal[
     "domain_exists",
     "domain_reserved",
     "inbound_domain_exists",
+    "tracking_domain_exists",
+    "tracking_domain_limit",
+    "tracking_host_is_sending_domain",
+    "tracking_host_not_verified",
+    "tracking_host_taken",
     "webhook_exists",
     "stream_exists",
     "inbound_stream_exists",
@@ -459,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
@@ -473,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
@@ -529,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.
@@ -542,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
@@ -550,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
@@ -557,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]
 
@@ -738,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.
@@ -1574,6 +1769,121 @@ class DomainList(Answer):
     domains: list[SendingDomain]
 
 
+TrackingDomainState = Literal[
+    "pending",
+    "waiting_for_certificate",
+    "ready",
+    "failing",
+    "stopped",
+    "sending_domain_lost",
+]
+TrackingCnameCheck = Literal["ok", "missing", "mismatch", "proxied", "dns_error"]
+TrackingCaaCheck = Literal[
+    "ok", "no_lets_encrypt", "other_account", "no_http_01", "dns_error"
+]
+
+
+@model
+class TrackingCnameRecord(Answer):
+    """The CNAME record a tracking domain needs, and what the last check found.
+
+    Attributes:
+        type: ``CNAME``.
+        host: The name to create it under.
+        value: The value it must hold.
+        check: What the last check found; ``None`` before the first.
+            ``mismatch`` is a record that points elsewhere, an A record
+            included. ``proxied`` is a proxy in front of the name.
+            ``dns_error`` is a resolver failure and changes nothing.
+    """
+
+    type: Literal["CNAME"]
+    host: str
+    value: str
+    check: TrackingCnameCheck | None
+
+
+@model
+class TrackingCaaRecord(Answer):
+    """The CAA record that lets a tracking domain's certificate be issued.
+
+    Attributes:
+        type: ``CAA``.
+        host: The name that holds the CAA records in the way.
+        value: The record to add beside them.
+    """
+
+    type: Literal["CAA"]
+    host: str
+    value: str
+
+
+@model
+class TrackingCaaCheckResult(Answer):
+    """Whether CAA records let Let's Encrypt issue the certificate.
+
+    Attributes:
+        check: What the last check found; ``None`` before the first.
+            ``dns_error`` is a resolver failure and changes nothing.
+        record: What lets the certificate be issued; ``None`` unless the
+            check found a problem.
+    """
+
+    check: TrackingCaaCheck | None
+    record: TrackingCaaRecord | None
+
+
+@model
+class TrackingDomain(Answer):
+    """A tracking domain, the record it needs and what the last check found.
+
+    Attributes:
+        tracking_domain_id: The tracking domain's id.
+        host: The host, lower-cased and IDNA-encoded.
+        sending_domain_id: The sending domain whose new mail will use the
+            host; ``None`` once that domain is deleted.
+        state: ``pending``: the records have not been right yet.
+            ``waiting_for_certificate``: the records are right. ``ready``:
+            new mail from the sending domain uses the host. ``failing``: a
+            check found the records wrong, and new mail keeps using a host
+            that was ready until 24 hours after ``failing_since``.
+            ``stopped``: those 24 hours have passed.
+            ``sending_domain_lost``: the sending domain is deleted or has
+            lost its verification.
+        created_at: When it was added.
+        last_checked_at: When the records were last looked up.
+        certificate_ready_at: When the certificate was proved to work.
+        failing_since: When a check first found the records wrong on a host
+            whose records have been right.
+        expires_at: When a host whose records have never been right goes.
+        cname: The CNAME record to add.
+        caa: Whether CAA records let Let's Encrypt issue the certificate.
+    """
+
+    tracking_domain_id: str
+    host: str
+    sending_domain_id: str | None
+    state: TrackingDomainState
+    created_at: datetime
+    last_checked_at: datetime | None
+    certificate_ready_at: datetime | None
+    failing_since: datetime | None
+    expires_at: datetime | None
+    cname: TrackingCnameRecord
+    caa: TrackingCaaCheckResult
+
+
+@model
+class TrackingDomainList(Answer):
+    """Every tracking domain of the account.
+
+    Attributes:
+        tracking_domains: The tracking domains.
+    """
+
+    tracking_domains: list[TrackingDomain]
+
+
 ErasureStatus = Literal["pending", "done"]