broadcast-python 0.3.0__tar.gz → 0.5.0__tar.gz

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-10
+
+### Added
+
+- `email.send_delayed` and `broadcast.batch_completed` in `EVENT_TYPES` (and in
+  `EMAIL_EVENTS` / `BROADCAST_EVENTS`), matching the server (Broadcast 2.43.0).
+  `email.send_delayed` fires when a transactional email waits for room under
+  its server's hourly limit.
+- `excluded_segment_ids` on broadcasts, sequences and autopilots: segments a
+  send never reaches. The server refuses a segment that is both sent to and
+  excluded with 422.
+- `subscribers.create(unsubscribed_at=...)`: creates a subscriber who has
+  already unsubscribed, in one request, with any token. Before, the server
+  ignored the field and a migration had to create, then unsubscribe.
+
+- `TRIGGER_FREQUENCIES`: the words `trigger_settings["frequency"]` accepts
+  (`always`, `every_visit`, `once_per_session`, `once_per_day`,
+  `once_per_week`, `once`).
+
+### Changed
+
+- Opt-in forms: the server now refuses an unknown `trigger_settings`
+  frequency word with 422 (`ValidationError`). Before, it saved any word, and
+  an unknown one showed the popup on every visit. The client still sends what
+  it is given.
+
+## [0.4.0] - 2026-10-06
+
+### Added
+
+- `client.topics` for `/api/v1/topics` (subscriber topics): `list`, `get`,
+  `create`, `update`, `delete`. Topics use the subscriber permissions.
+  Broadcasts and sequences accept `topic_id`.
+- `subscribers.update(email, custom_data_mode="merge", ...)`: change only the
+  custom_data keys sent; `None` deletes a key. The default stays replace.
+- `subscriber.preferences_updated` webhook event type, in `SUBSCRIBER_EVENTS`
+  and `EVENT_TYPES` (now 35).
+
 ## [0.3.0] - 2026-10-03
 
 ### Added

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: broadcast-python
-Version: 0.3.0
+Version: 0.5.0
 Summary: Python client for the Broadcast email platform. Subscribers, sequences, broadcasts, segments, templates, autopilot, webhooks, and transactional email.
 Project-URL: Homepage, https://sendbroadcast.net
 Project-URL: Repository, https://github.com/send-broadcast/broadcast-python
@@ -240,12 +240,46 @@ client.sequences.move_step(id, step_id, under_id)
 client.segments.create(name="VIPs")
 client.templates.create(label="Welcome", subject="Hi", body="...")
 client.opt_in_forms.analytics(id, start_date=date(2026, 1, 1))
+# How often the same visitor sees a popup: one of TRIGGER_FREQUENCIES, or ValidationError (422).
+client.opt_in_forms.update(id, trigger_settings={"frequency": "once_per_day"})
 client.opt_in_forms.create_variant(id, name="B", weight=50)
 client.opt_in_forms.duplicate(id, label="Copy")
 ```
 
 Reading a segment recounts its members server-side, so `segments.get` is not free.
 
+### Topics
+
+A topic is one kind of email subscribers opt in to or out of (webinars, offers).
+Its value lives in a top-level `custom_data` key (`True`, `False`, or no value)
+or in a tag. `unset_receives` decides, at send time, whether a subscriber with no
+value receives it; Broadcast never writes a default. Topics use the subscriber
+permissions.
+
+```python
+topic = client.topics.create(name="Webinars", custom_data_key="sub_webinars")
+client.topics.create(name="News", storage="tag", tag_name="news")
+client.topics.list()
+client.topics.update(topic["id"], unset_receives=False)
+client.topics.delete(topic["id"])  # 422 while a broadcast or sequence uses it
+
+# Send to a topic: (segments) AND topic
+client.broadcasts.create(subject="Webinar", body="...", segment_ids=[2], topic_id=topic["id"])
+
+# Send to everyone except a segment (also on sequences and autopilots)
+client.broadcasts.create(subject="Offer", body="...", excluded_segment_ids=[competitors["id"]])
+
+# Migrate someone who already unsubscribed, in one request
+client.subscribers.create(email="opted-out@example.com", unsubscribed_at="2025-03-14T09:30:00Z")
+
+# Change only the keys you send (None deletes a key); the default replaces custom_data
+client.subscribers.update("jane@example.com", custom_data={"sub_webinars": False}, custom_data_mode="merge")
+```
+
+The subscriber JSON has `topics`: each topic's stored value (`True`, `False`, or
+`None`). Topic changes fire `subscriber.preferences_updated` as well as
+`subscriber.updated`.
+
 ### Channel design (brand kit)
 
 ```python
@@ -413,7 +447,7 @@ every rejection rather than distinguishing them.
 Pass the **raw** request body. Re-serialising a parsed dict changes the bytes
 and verification will fail.
 
-`broadcast_python.EVENT_TYPES` lists all 34 event names. `SUBSCRIBER_EVENTS`
+`broadcast_python.EVENT_TYPES` lists all 37 event names. `SUBSCRIBER_EVENTS`
 includes `subscribers.purged` and `subscribers.purge_failed`: a purge of the
 whole list sends one of these instead of a `subscriber.deleted` per subscriber.
 

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/README.md

@@ -216,12 +216,46 @@ client.sequences.move_step(id, step_id, under_id)
 client.segments.create(name="VIPs")
 client.templates.create(label="Welcome", subject="Hi", body="...")
 client.opt_in_forms.analytics(id, start_date=date(2026, 1, 1))
+# How often the same visitor sees a popup: one of TRIGGER_FREQUENCIES, or ValidationError (422).
+client.opt_in_forms.update(id, trigger_settings={"frequency": "once_per_day"})
 client.opt_in_forms.create_variant(id, name="B", weight=50)
 client.opt_in_forms.duplicate(id, label="Copy")
 ```
 
 Reading a segment recounts its members server-side, so `segments.get` is not free.
 
+### Topics
+
+A topic is one kind of email subscribers opt in to or out of (webinars, offers).
+Its value lives in a top-level `custom_data` key (`True`, `False`, or no value)
+or in a tag. `unset_receives` decides, at send time, whether a subscriber with no
+value receives it; Broadcast never writes a default. Topics use the subscriber
+permissions.
+
+```python
+topic = client.topics.create(name="Webinars", custom_data_key="sub_webinars")
+client.topics.create(name="News", storage="tag", tag_name="news")
+client.topics.list()
+client.topics.update(topic["id"], unset_receives=False)
+client.topics.delete(topic["id"])  # 422 while a broadcast or sequence uses it
+
+# Send to a topic: (segments) AND topic
+client.broadcasts.create(subject="Webinar", body="...", segment_ids=[2], topic_id=topic["id"])
+
+# Send to everyone except a segment (also on sequences and autopilots)
+client.broadcasts.create(subject="Offer", body="...", excluded_segment_ids=[competitors["id"]])
+
+# Migrate someone who already unsubscribed, in one request
+client.subscribers.create(email="opted-out@example.com", unsubscribed_at="2025-03-14T09:30:00Z")
+
+# Change only the keys you send (None deletes a key); the default replaces custom_data
+client.subscribers.update("jane@example.com", custom_data={"sub_webinars": False}, custom_data_mode="merge")
+```
+
+The subscriber JSON has `topics`: each topic's stored value (`True`, `False`, or
+`None`). Topic changes fire `subscriber.preferences_updated` as well as
+`subscriber.updated`.
+
 ### Channel design (brand kit)
 
 ```python
@@ -389,7 +423,7 @@ every rejection rather than distinguishing them.
 Pass the **raw** request body. Re-serialising a parsed dict changes the bytes
 and verification will fail.
 
-`broadcast_python.EVENT_TYPES` lists all 34 event names. `SUBSCRIBER_EVENTS`
+`broadcast_python.EVENT_TYPES` lists all 37 event names. `SUBSCRIBER_EVENTS`
 includes `subscribers.purged` and `subscribers.purge_failed`: a purge of the
 whole list sends one of these instead of a `subscriber.deleted` per subscriber.
 

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "broadcast-python"
-version = "0.3.0"
+version = "0.5.0"
 description = "Python client for the Broadcast email platform. Subscribers, sequences, broadcasts, segments, templates, autopilot, webhooks, and transactional email."
 readme = "README.md"
 requires-python = ">=3.9"

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/src/broadcast_python/__init__.py

@@ -28,6 +28,7 @@ from .errors import (
 )
 from .resources.email_servers import REDACTED_FIELDS
 from .resources.migration import COLLECTIONS
+from .resources.opt_in_forms import TRIGGER_FREQUENCIES
 from .resources.transactionals import MAX_IDEMPOTENCY_KEY_LENGTH
 from .response import RateLimit, Response, Warning_
 from .version import VERSION
@@ -42,6 +43,7 @@ __all__ = [
     "EVENT_TYPES",
     "MAX_IDEMPOTENCY_KEY_LENGTH",
     "REDACTED_FIELDS",
+    "TRIGGER_FREQUENCIES",
     "VERSION",
     "WARNINGS_MODES",
     "APIError",

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/src/broadcast_python/client.py

@@ -16,6 +16,7 @@ from .resources.sequences import Sequences
 from .resources.subscribers import Subscribers
 from .resources.suppressions import Suppressions
 from .resources.templates import Templates
+from .resources.topics import Topics
 from .resources.transactionals import Transactionals
 from .resources.users import Users
 from .resources.webhook_endpoints import WebhookEndpoints
@@ -40,6 +41,7 @@ class Broadcast:
         self.sequences = Sequences(self)
         self.broadcasts = Broadcasts(self)
         self.segments = Segments(self)
+        self.topics = Topics(self)
         self.templates = Templates(self)
         #: The channel's brand kit (Settings -> Design). Read-only.
         self.channel_design = ChannelDesign(self)

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/src/broadcast_python/resources/autopilots.py

@@ -36,7 +36,8 @@ class Autopilots(BaseResource):
         write-only. Scheduling takes ``schedule_frequency`` (daily, weekly,
         biweekly, monthly), ``schedule_day_of_week``, ``schedule_day_of_month``,
         ``schedule_time``, ``schedule_timezone``. ``segment_ids`` restricts the
-        newsletter's audience.
+        newsletter's audience; ``excluded_segment_ids`` lists segments its
+        drafts never reach.
         """
         return self._post("/api/v1/autopilots", {"autopilot": attrs})
 

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/src/broadcast_python/resources/opt_in_forms.py

@@ -5,6 +5,12 @@ from .base import BaseResource, compact
 
 Id = Union[str, int]
 
+#: The words ``trigger_settings["frequency"]`` accepts: how often the same
+#: visitor sees a popup. ``always`` and ``every_visit`` mean the same. The server
+#: refuses any other word with 422 (:class:`ValidationError`); the client does
+#: not check, so an older server is never refused a word it would take.
+TRIGGER_FREQUENCIES = ("always", "every_visit", "once_per_session", "once_per_day", "once_per_week", "once")
+
 
 class OptInForms(BaseResource):
     def list(self, **params: Any) -> Any:
@@ -23,6 +29,9 @@ class OptInForms(BaseResource):
         Nested settings dicts (``theme_settings``, ``automation_settings``,
         ``security_settings``, ``trigger_settings``, ``widget_settings``) and
         the block arrays are passed through verbatim.
+        ``trigger_settings["frequency"]`` must be one of
+        :data:`TRIGGER_FREQUENCIES`; any other word raises
+        :class:`ValidationError` (422).
         """
         return self._post("/api/v1/opt_in_forms", {"opt_in_form": attrs})
 

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/src/broadcast_python/resources/subscribers.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 from .base import BaseResource
 
@@ -33,7 +33,11 @@ class Subscribers(BaseResource):
         timestamp when migrating an already-confirmed list off another provider.
         It is ignored (with a warning) on update.
 
-        ``unsubscribed_at`` is never settable here; use :meth:`unsubscribe`.
+        ``unsubscribed_at`` (any token, create only, ISO 8601) stores the
+        subscriber as unsubscribed in the same request, for migrating a list
+        with its opt-outs intact: no confirmation email, 422 if it is in the
+        future or sent with ``is_active=True``. To unsubscribe an existing
+        subscriber, use :meth:`unsubscribe`.
         """
         double_opt_in = attrs.pop("double_opt_in", None)
         confirmation_template_id = attrs.pop("confirmation_template_id", None)
@@ -46,8 +50,13 @@ class Subscribers(BaseResource):
 
         return self._post("/api/v1/subscribers.json", payload)
 
-    def update(self, email: str, **attrs: Any) -> Any:
-        return self._patch("/api/v1/subscribers.json", {"email": email, "subscriber": attrs})
+    def update(self, email: str, custom_data_mode: Optional[str] = None, **attrs: Any) -> Any:
+        """custom_data_mode: "replace" (the API default) stores custom_data as sent;
+        "merge" changes only the keys sent, and a None value deletes that key."""
+        payload: Dict[str, Any] = {"email": email, "subscriber": attrs}
+        if custom_data_mode:
+            payload["custom_data_mode"] = custom_data_mode
+        return self._patch("/api/v1/subscribers.json", payload)
 
     def add_tags(self, email: str, tags: List[str]) -> Any:
         return self._post("/api/v1/subscribers/add_tag.json", {"email": email, "tags": tags})

broadcast_python-0.5.0/src/broadcast_python/resources/topics.py

@@ -0,0 +1,29 @@
+from typing import Any, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+
+class Topics(BaseResource):
+    """Subscriber topics: kinds of email subscribers opt in to or out of.
+
+    A topic reads a top-level custom_data key (true, false, or no value) or a
+    tag. Topics use the token's subscriber permissions.
+    """
+
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/topics.json", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/topics/{}.json".format(id), {})
+
+    def create(self, **attrs: Any) -> Any:
+        return self._post("/api/v1/topics", {"topic": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/topics/{}".format(id), {"topic": attrs})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        """Refused (422) while a broadcast or sequence uses the topic."""
+        return self._delete("/api/v1/topics/{}".format(id))

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/src/broadcast_python/version.py

@@ -1,3 +1,3 @@
 # Kept in sync with pyproject.toml by tests/test_package.py — a User-Agent that
 # lies about its version misattributes server-side client analytics.
-VERSION = "0.3.0"
+VERSION = "0.5.0"

{broadcast_python-0.3.0 → broadcast_python-0.5.0}/src/broadcast_python/webhook.py

@@ -15,6 +15,7 @@ EMAIL_EVENTS = (
     "email.sent",
     "email.delivered",
     "email.delivery_delayed",
+    "email.send_delayed",
     "email.complained",
     "email.bounced",
     "email.opened",
@@ -25,6 +26,7 @@ EMAIL_EVENTS = (
 SUBSCRIBER_EVENTS = (
     "subscriber.created",
     "subscriber.updated",
+    "subscriber.preferences_updated",
     "subscriber.deleted",
     "subscriber.subscribed",
     "subscriber.unsubscribed",
@@ -44,6 +46,7 @@ BROADCAST_EVENTS = (
     "broadcast.partial_failure",
     "broadcast.aborted",
     "broadcast.paused",
+    "broadcast.batch_completed",
 )
 
 SEQUENCE_EVENTS = (