RubyGems - broadcast-ruby - Versions diffs - 0.3.0 → 0.4.0 - Mend

broadcast-ruby 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +59 -0
data/Gemfile.lock +2 -2
data/README.md +171 -14
data/SDK-COVERAGE.md +60 -13
data/lib/broadcast/client.rb +29 -2
data/lib/broadcast/delivery_method.rb +17 -2
data/lib/broadcast/resources/global_suppressions.rb +43 -0
data/lib/broadcast/resources/suppressions.rb +56 -0
data/lib/broadcast/version.rb +1 -1
data/lib/broadcast.rb +2 -0
metadata +4 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fec10ff364f7b63e728e1da143f2e0ff4445e2466f8a9e1a307370142d4c8666
-  data.tar.gz: efce695852b7774e6e40f1f91a93ee2487e8d635a579ab0fe20505a9fe4a9efe
+  metadata.gz: 7866007085ed5d19620669069bdfeb9e7babaad5d08b2198d76e19620ce68bde
+  data.tar.gz: '082d0663d0a5a2501f445f0f7152e6b6a56467d1e0a61d0ae96e45b3137380d0'
 SHA512:
-  metadata.gz: b72667f6f90ecb99ec60d0d9c905f529fbf0f78e30386e78ca93aeb1ac783e2a923750b76a41b73f2da771be67b3bfca012749066614a2ddb99c6cebb093924c
-  data.tar.gz: ff0b6ba2de7606b7dbc1fab2c552f6947158cd69ad28ae328d3b23f1d52b8878700802a08d108841e7453b5495398258c70e2e287bbc5ac76e1a908baedab1c1
+  metadata.gz: bd9d8c35c4bdcea360c59609be5e366bcd066084328db6380e7f3995cc49e7121937b053c6e09c36d94262d54cfc4d4bb978dcae93a58410407a3da78a6d9182
+  data.tar.gz: c4d0c47df97790a337dc35b882fea9254c1ae8f41d19784f71bebecb253c6b00740356be0cb5b1b7edf2d2c9965f84556f1fcc31fc350dd1e6214adda167fc63

data/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,65 @@
 All notable changes to this project will be documented in this file.
+## [Unreleased]
+## [0.4.0] - 2026-08-14
+### Fixed — ActionMailer delivery
+Both reproduced from a real delivered message, and both traced to the same
+ceiling: `Client#send_email` accepted only `to`/`subject`/`body`/`reply_to`, so
+`DeliveryMethod` had no way to describe what it was sending.
+- **HTML mail arrived as two nested HTML documents.** `deliver!` sent an HTML
+  body without flagging it as HTML, so Broadcast recorded the send as plain text
+  and wrapped the payload in its own `<html><body>` shell. `deliver!` now sends
+  `html_body: true` when the mail has an `html_part`.
+- **Transactional mail carried a one-click unsubscribe.** A password reset
+  arrived with `List-Unsubscribe` and `List-Unsubscribe-Post: One-Click`,
+  because `deliver!` could not say the send was transactional and the channel's
+  unsubscribe setting applied to it. Clicking it marks the recipient
+  unsubscribed, silently dropping them from every sequence and broadcast — from
+  a click on a security email. `deliver!` now sends
+  `include_unsubscribe_link: false` by default; set
+  `include_unsubscribe_link: true` in `broadcast_settings` to opt back in. The
+  option is consumed by `DeliveryMethod` rather than forwarded, since
+  `Configuration` has no such attribute.
+`Client#send_email` gained matching optional `html_body:` and
+`include_unsubscribe_link:` keywords. Both are omitted from the payload when nil,
+so direct callers of `send_email` are unaffected.
+**Upgrade note.** ActionMailer deliveries change shape, not just API surface.
+Mail that previously went out flagged as plain text is now flagged as HTML, and
+mail that previously carried `List-Unsubscribe` no longer does. Both are the
+point of the fix, but an app that relied on the unsubscribe footer appearing on
+ActionMailer sends should set `include_unsubscribe_link: true` in
+`broadcast_settings` to keep it.
+### Documentation
+The entries below are documentation only; the behaviour changes in this release
+are the ActionMailer fixes above.
+- **Autopilot is documented in the README.** 0.3.0 shipped the `Autopilots`
+  resource with ten endpoints and no README section, so the only user-facing
+  description of it was the source. Adds lifecycle, runs, the write-only
+  `openrouter_api_key` guard, and the `autopilot_read` / `autopilot_write` row
+  in the permissions table.
+- **`SDK-COVERAGE.md` contradicted itself on Autopilot** — listed at 10/10 in
+  the endpoint map and simultaneously under "Not in the API at all" with "zero
+  autopilot routes". The latter was true when written and is now removed; the
+  section explains what closed it, and records that autopilot sources and tone
+  samples remain web-only.
+- Corrected the API version header (2.19.0 → **2.20.0**) and the spec size in
+  `SDK-TODO.md` (68 paths / 94 operations → **75 / 104**).
+- Marked `openapi:check` in CI as done — it has been running in the self-hosted
+  matrix leg but was still listed as pending.
+- Documented how a **demo instance** answers: the migration API returns 403 for
+  every request including valid tokens, and transactional sends are accepted
+  but never delivered.
 ## [0.3.0] - 2026-07-26
 Catches the gem up to the Broadcast v2.19 API. The API gained a response-warnings

data/Gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    broadcast-ruby (0.3.0)
+    broadcast-ruby (0.4.0)
       base64
 GEM
@@ -177,7 +177,7 @@ CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
-  broadcast-ruby (0.3.0)
+  broadcast-ruby (0.4.0)
   builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a

data/README.md CHANGED Viewed

@@ -1,8 +1,12 @@
 # broadcast-ruby
-Ruby client for the [Broadcast](https://sendbroadcast.net) email platform.
+Official Ruby client for [Broadcast](https://sendbroadcast.net), the self-hosted email marketing platform.
-Works with any Broadcast instance — self-hosted or SaaS.
+Works with any Broadcast instance — self-hosted or SaaS. Covers **104/104 API operations**, verified against the API's generated OpenAPI document.
+📖 **[Ruby SDK documentation](https://sendbroadcast.net/docs/ruby-sdk)** · [API reference](https://sendbroadcast.net/docs/api-authentication) · [All docs](https://sendbroadcast.net/docs)
+Also available: [PHP](https://github.com/send-broadcast/broadcast-php) · [Node/TypeScript](https://github.com/send-broadcast/broadcast-node) · [Python](https://github.com/send-broadcast/broadcast-python)
 ## Installation
@@ -60,7 +64,7 @@ export BROADCAST_API_TOKEN=your-token
 client = Broadcast::Client.new  # picks both up from ENV
 ```
-### Options
+## Configuration
 | Option | Default | Description |
 |--------|---------|-------------|
@@ -71,21 +75,37 @@ client = Broadcast::Client.new  # picks both up from ENV
 | `retry_attempts` | `3` | Max total attempts (1 initial + 2 retries). Server errors (5xx), timeouts, and rate limits (429) are retried; other client errors (4xx) are not |
 | `retry_delay` | `1` | Base delay between retries in seconds (multiplied by attempt number) |
 | `max_retry_delay` | `30` | Ceiling for a server-supplied `Retry-After`, so a long rate-limit window can't stall the caller |
-| `warnings_mode` | `:log` | How to handle API warnings — `:log`, `:raise`, or `:ignore`. See [API Warnings](#api-warnings) |
+| `warnings_mode` | `:log` | How to handle API warnings — `:log`, `:raise`, or `:ignore`. See [Warnings](#warnings) |
 | `debug` | `false` | Log request/response details (credentials are redacted) |
 | `logger` | `nil` | Logger instance for debug output (e.g. `Rails.logger`) |
 | `broadcast_channel_id` | `nil` | Auto-included on every request when set. Required when using an admin/system token (regular tokens are channel-scoped already). Can be overridden per-call or via `client.with_channel(id) { ... }` |
-All methods return parsed JSON as Ruby Hashes with string keys. The returned
-object is a `Broadcast::Response` — a Hash subclass that also carries response
-metadata (`#warnings`, `#rate_limit`, `#status`, `#idempotent_replay?`).
-Anything that worked against a plain Hash still works.
 > **Note on module naming:** This gem defines a top-level `Broadcast` module. If your application already has a `Broadcast` class or module (e.g. an ActiveRecord model), you may encounter a namespace collision.
 ---
-## API Warnings
+## Responses
+Every call returns parsed JSON as a Ruby Hash with string keys, so `result['id']`
+works as you would expect. The returned object is a `Broadcast::Response` — a Hash
+subclass that also carries the transport metadata:
+```ruby
+result = client.subscribers.create(email: 'ada@example.com')
+result['id']                   # the response body
+result.status                  # 201
+result.warnings                # parsed warnings, if any
+result.rate_limit&.remaining   # requests left in the window
+result.idempotent_replay?      # true if the API replayed a stored response
+```
+Anything that worked against a plain Hash still works — `dig`, `is_a?(Hash)`,
+equality against a literal Hash, splatting.
+---
+## Warnings
 Broadcast accepts a write and then tells you what it ignored. A misspelled
 attribute, a parameter that only applies in another mode, a value the server
@@ -942,7 +962,38 @@ admin_client.email_servers.copy_to_channel(99, target_channel_id: 7)
 ---
-## Channel Scoping (Admin/System Tokens)
+## Suppressions
+A suppressed address is one Broadcast will not email. Each channel has its own list, and the installation has a global one; `client.suppressions` manages the current channel's list:
+```ruby
+client.suppressions.check('ada@example.com')     # will this address receive mail?
+client.suppressions.list(page: 1, email: 'example.com')
+client.suppressions.add('bounced@example.com')
+client.suppressions.remove('bounced@example.com')
+client.suppressions.bulk_add(['a@example.com', 'b@example.com'])   # up to 10,000
+client.suppressions.bulk_remove(['a@example.com'])
+```
+`check` reads across both the channel's list and the global list, so it answers the question integrations actually ask: will this address receive mail? The response's `scope` says which list matched. Adding an already-suppressed address is a success (200 rather than 201), so there is no need to check first.
+Bulk adds are idempotent -- a retried batch cannot duplicate -- and return `added`, `already_suppressed`, and `invalid` counts. `remove` returns `removed: false` (not an error) when the address was not on the list, and never touches the global list.
+The global list is a separate resource and **requires an admin/system token**:
+```ruby
+client.global_suppressions.list
+client.global_suppressions.add('spamtrap@example.com')
+client.global_suppressions.remove('spamtrap@example.com')
+client.global_suppressions.bulk_add([...])
+client.global_suppressions.bulk_remove([...])
+```
+Removing an address globally does not unblock it in channels that suppressed it on their own account. There is no `check` on the global resource: checking is a per-channel question, so it lives on `client.suppressions`.
+---
+## Channel Scoping
 Regular API tokens are scoped to a single broadcast channel automatically. Admin/system tokens are not -- they require `broadcast_channel_id` on every request to indicate which channel they're acting on.
@@ -976,7 +1027,7 @@ end
 ---
-## Webhook Endpoints
+## Webhooks
 Receive real-time notifications when events occur (email delivered, subscriber created, sequence completed, etc.).
@@ -1079,6 +1130,91 @@ The signature is computed as `HMAC-SHA256(timestamp + "." + payload, secret)`. T
 ---
+## Autopilot
+AI-generated newsletters. An autopilot reads your configured sources on a
+schedule, drafts copy in the tone you describe, and produces broadcast drafts
+for review. Requires `autopilot_read` / `autopilot_write`.
+```ruby
+client.autopilots.list
+client.autopilots.get_autopilot(id)
+autopilot = client.autopilots.create(
+  name: 'Weekly Roundup',
+  openrouter_api_key: ENV['OPENROUTER_API_KEY'],
+  ai_model: 'openai/gpt-4o',
+  schedule_frequency: 'weekly',
+  schedule_day_of_week: 1,
+  schedule_time: '09:00',
+  schedule_timezone: 'America/New_York',
+  copies_to_generate: 3,
+  tone_description: 'Direct and technical. No hype.',
+  content_instructions: 'Lead with the most consequential change.',
+  segment_ids: [ 12 ]
+)
+client.autopilots.update(autopilot['id'], copies_to_generate: 5)
+client.autopilots.delete(autopilot['id'])
+```
+### Lifecycle
+```ruby
+client.autopilots.activate(id)     # start running on schedule
+client.autopilots.pause(id)        # keep config, stop generating
+client.autopilots.deactivate(id)
+```
+`activate` requires **at least one active source, an API key, and a model**. If
+any is missing it raises `Broadcast::ValidationError` naming the prerequisites:
+```ruby
+begin
+  client.autopilots.activate(id)
+rescue Broadcast::ValidationError => e
+  # All missing prerequisites, comma-joined:
+  e.message # => "At least one active source is required, AI model is required"
+end
+```
+Sources and tone samples have **no API endpoints yet** — they are configured in
+the web UI. Since `activate` needs an active source, a brand-new autopilot
+created over the API cannot be activated until a source is added there.
+### Runs
+`trigger_run` queues generation immediately and returns `202` — the work is
+asynchronous, so poll rather than expecting finished copy back:
+```ruby
+run = client.autopilots.trigger_run(id)
+run['status']   # => "pending"
+client.autopilots.runs(id, limit: 10)   # most recent first
+```
+### API key handling
+`openrouter_api_key` is write-only. It is encrypted at rest and never returned —
+reads expose only `api_key_configured`. The API renders a configured key
+bullet-masked, and writing that mask back would replace a working credential
+with bullets, so `update` strips it and warns:
+```ruby
+current = client.autopilots.get_autopilot(id)
+current['api_key_configured']   # => true
+current['openrouter_api_key']   # => nil — never returned
+# Safe: the masked value is dropped, the stored key survives
+client.autopilots.update(id, openrouter_api_key: '••••••••', ai_model: 'openai/gpt-4o')
+```
+Pass the real key to rotate it, or omit the field entirely. This is the same
+guard as [Email Servers](#credential-redaction).
+---
 ## Discovery
 Ask the instance what this token can do and whether the channel is ready to
@@ -1114,7 +1250,7 @@ raise 'channel not ready to send' unless client.status.dig('readiness', 'broadca
 ---
-## Export & Migration (admin tokens only)
+## Export & Migration
 Read-only endpoints under `/api/migration/v1` for backups and moving a channel
 between instances. Two constraints differ from the rest of the API:
@@ -1179,7 +1315,7 @@ File.binwrite('logo.png', bytes)
 ---
-## Error Handling
+## Errors
 All API errors inherit from `Broadcast::Error`. Put specific errors before general ones:
@@ -1225,6 +1361,8 @@ Each token can be scoped to specific resources. The ActionMailer delivery method
 | Opt-In Forms | `opt_in_forms_read` -- list, get, analytics | `opt_in_forms_write` -- create, update, delete, create_variant, duplicate |
 | Email Servers | `email_servers_read` -- list, get | `email_servers_write` -- create, update, delete, test_connection, copy_to_channel (admin) |
 | Webhook Endpoints | `webhook_endpoints_read` -- list, get, deliveries | `webhook_endpoints_write` -- create, update, delete, test |
+| Autopilot | `autopilot_read` -- list, get, runs | `autopilot_write` -- create, update, delete, activate, pause, deactivate, trigger_run |
+| Suppressions | `suppressions_read` -- list, check | `suppressions_write` -- add, remove, bulk add/remove |
 ---
@@ -1268,6 +1406,25 @@ Each token can be scoped to specific resources. The ActionMailer delivery method
 - **Check credentials:** Run `bin/rails credentials:show` and verify `broadcast.api_token` is set.
 - **Check logs:** Set `debug: true` in `broadcast_settings` to see request/response details.
+## Documentation
+- **[Ruby SDK guide](https://sendbroadcast.net/docs/ruby-sdk)** — the same material as this README, on the docs site
+- **[API reference](https://sendbroadcast.net/docs/api-authentication)** — endpoints, parameters, and permissions
+- **[API response warnings](https://sendbroadcast.net/docs/api-response-warnings)** — why a 2xx can still tell you something went wrong
+- **[Webhook endpoints](https://sendbroadcast.net/docs/api-webhook-endpoints)** — signature format and event types
+- **[Agents CLI](https://sendbroadcast.net/docs/agents-cli)** — the same credentials, from a terminal
+### Other SDKs
+| Language | Package | Repository |
+|---|---|---|
+| Ruby | [broadcast-ruby](https://rubygems.org/gems/broadcast-ruby) | this repository |
+| PHP | broadcast/broadcast-php | [broadcast-php](https://github.com/send-broadcast/broadcast-php) |
+| Node / TypeScript | @send-broadcast/sdk | [broadcast-node](https://github.com/send-broadcast/broadcast-node) |
+| Python | broadcast-python | [broadcast-python](https://github.com/send-broadcast/broadcast-python) |
+All four cover the same 115 operations and behave the same way on the wire — the transport contract (warnings, idempotency, rate-limit handling, redirect safety, credential redaction) is identical across languages.
 ## License
 MIT License. See [LICENSE.txt](LICENSE.txt).

data/SDK-COVERAGE.md CHANGED Viewed

@@ -3,6 +3,13 @@
 What this gem covers, what it deliberately doesn't, and what the Broadcast
 application can do that no client can reach.
+> **This file describes the Ruby gem specifically.** Since 2026-07-27 there are
+> three sibling SDKs — `broadcast-node`, `broadcast-python`, `broadcast-php` —
+> all at 104/104 against the same spec. The endpoint map below applies to all
+> of them (the paths are identical); only the method names differ. Per-language
+> status, including the caveat that PHP's suite has never been run, is in
+> [SDK-TODO.md](SDK-TODO.md#status--2026-07-27).
 **Headline: 104/104 API operations (100%).**
 That number is narrower than it sounds, and [Limits of the 100%](#limits-of-the-100)
@@ -10,7 +17,7 @@ explains exactly what it does not measure. Read that section before quoting the
 figure.
 - Gem version: **0.3.0**
-- API version: **2.19.0** (75 paths, 104 operations)
+- API version: **2.20.0** (75 paths, 104 operations)
 - Generated by: `bin/rails "openapi:coverage[../broadcast-ruby]"` in the
   `broadcast` repo
 - Verified: self-hosted and SaaS mode (the `/api` surface is identical in both)
@@ -24,7 +31,8 @@ figure.
 3. [Transport coverage](#transport-coverage) — the protocol, not the endpoints
 4. [Webhook coverage](#webhook-coverage) — inbound
 5. [Not in the API at all](#not-in-the-api-at-all) — app features no client can reach
-6. [Limits of the 100%](#limits-of-the-100)
+6. [Demo instances answer differently](#demo-instances-answer-differently)
+7. [Limits of the 100%](#limits-of-the-100)
 ---
@@ -339,7 +347,6 @@ this is an API gap, not a gem gap, and nothing here is actionable in this repo.
 | Feature | Where it lives | Notes |
 |---|---|---|
-| **Autopilot** (AI newsletter generation) | Web UI | Sources, tone samples, runs, scheduling. See below — this one is different. |
 | **Ask AI** | Web UI | Conversations, messages, tool-call approval |
 | **Subscriber imports** | Web UI | CSV/TSV upload, mapping, processing |
 | **CSV exports** | Web UI | Subscribers, broadcasts, activity. `GET /subscribers/export` is a web route |
@@ -353,17 +360,44 @@ this is an API gap, not a gem gap, and nothing here is actionable in this repo.
 | **Admin / platform** | Web UI | Admin API tokens, SaaS platform admin |
 | **Confirmation templates & pages** | Partly API | Configurable as template attributes; no dedicated endpoints |
-### Autopilot is worth a separate note
+### Autopilot: this section used to be wrong, and how
+Autopilot was listed here as web-UI-only. The reasoning was that `Token`
+defined `permission_to_autopilot_read` / `_write` while no `api/v1/autopilots`
+controller existed — inert flags. That was true when written, and the entry
+predicted it would be the first thing to go stale. It was.
+Autopilot **is** in the API as of app v2.20.0 and is covered
+[above](#autopilot--1010). The build also closed the permission gap the flags
+had exposed: `user_broadcast_channel_permissions` had no autopilot columns, so
+the feature was silently sudo-only in the UI and its policy scopes raised
+`NoMethodError` for any user holding a channel-permission record. Migration
+`20260726180000` added them; `UserManagementPolicy` now derives assignable
+attributes from the schema rather than a hand-written list.
+Sub-resources are still web-only: autopilot **sources** and **tone samples**
+have no v1 endpoints. `create`/`update` set the generator itself, and
+`activate` requires an active source — so a source must exist before the API
+can activate anything. That is the next gap in this resource.
+---
+## Demo instances answer differently
-The `Token` model already defines **`permission_to_autopilot_read`** and
-**`permission_to_autopilot_write`** — but there is no `api/v1/autopilots`
-controller and zero autopilot routes under `/api`. The permission flags exist
-with nothing behind them.
+Nothing here is a gem concern, but a client pointed at a demo instance
+(`DEMO_MODE` set) sees behaviour no error class distinguishes:
-So an operator can grant an API token "Autopilot" access today and that grant
-does nothing. That is worth either building the endpoints or hiding the
-permission — and it is the most likely next addition to the API surface, which
-makes it the first thing to check when this document goes stale.
+- **The migration API is off entirely.** Every `/api/migration/v1` route
+  returns `403` with `{"error": "The migration API is disabled in demo mode."}`,
+  raised *before* token verification — so a valid and an invalid admin token
+  get identical answers, deliberately, to stop the demo being used as a token
+  oracle. In the gem this surfaces as `Broadcast::AuthorizationError`.
+- **Transactional sends are accepted but never delivered.** The request
+  succeeds and a record is created; the mailer returns early. `2xx` does not
+  mean an email left the building.
+- **`/api/v1` itself is unguarded.** It honours any valid token — but tokens
+  cannot be minted in demo mode, so in practice the only usable credential is
+  the "Default transactional email" token each channel auto-provisions.
 ---
@@ -417,6 +451,19 @@ bin/rails openapi:generate
 bin/rails "openapi:coverage[../broadcast-ruby]"
 ```
-If `openapi:check` fails in CI, the API changed and this document is stale.
+`openapi:check` now runs in CI, so a changed API surface fails the build rather
+than silently ageing this file. Note what that guard does **not** cover: it
+compares the spec to the router, not this document to the spec. Both stale
+entries found in the 2.20.0 pass — the version header, and Autopilot appearing
+as both covered and absent — would have survived a green CI run indefinitely.
+So on every API bump, re-check the three hand-maintained claims by hand:
+1. **The version header** at the top — it does not come from anywhere.
+2. **[Not in the API at all](#not-in-the-api-at-all)** — a new endpoint means a
+   row leaves that table. This is where the contradiction hid.
+3. **Prose in the endpoint map** — counts regenerate, the sentences under them
+   do not.
 Cross-language plans live in [SDK-TODO.md](SDK-TODO.md); the v0.3.0 work log is
 in [TODO.md](TODO.md).

data/lib/broadcast/client.rb CHANGED Viewed

@@ -36,8 +36,23 @@ module Broadcast
     # Thin convenience wrapper around `transactionals.create`. Use
     # `client.transactionals.create` directly for template_id, double_opt_in,
     # preheader, idempotency_key, and other advanced options.
-    def send_email(to:, subject: nil, body: nil, reply_to: nil)
-      transactionals.create(to: to, subject: subject, body: body, reply_to: reply_to)
+    # `html_body` tells Broadcast the body is already HTML. Without it the send
+    # is recorded as plain text and the payload is wrapped in Broadcast's own
+    # <html><body> shell, so an HTML mail arrives as two nested documents.
+    #
+    # `include_unsubscribe_link` lets the caller suppress the unsubscribe
+    # footer and List-Unsubscribe header. Transactional mail wants that off: a
+    # one-click unsubscribe on a password reset marks the person unsubscribed
+    # and silently drops them from every sequence and broadcast.
+    # rubocop:disable Metrics/ParameterLists -- mirrors the API's flat param surface
+    def send_email(to:, subject: nil, body: nil, reply_to: nil,
+                   html_body: nil, include_unsubscribe_link: nil)
+      # rubocop:enable Metrics/ParameterLists
+      opts = { to: to, subject: subject, body: body, reply_to: reply_to }
+      opts[:html_body] = html_body unless html_body.nil?
+      opts[:include_unsubscribe_link] = include_unsubscribe_link unless include_unsubscribe_link.nil?
+      transactionals.create(**opts)
     end
     def get_email(id)
@@ -108,6 +123,18 @@ module Broadcast
       @discovery ||= Resources::Discovery.new(self)
     end
+    # The current channel's suppression list (plus `check`, which reads the
+    # global list too).
+    def suppressions
+      @suppressions ||= Resources::Suppressions.new(self)
+    end
+    # The installation-wide suppression list. Requires an admin (system) API
+    # token.
+    def global_suppressions
+      @global_suppressions ||= Resources::GlobalSuppressions.new(self)
+    end
     # Read-only export endpoints under /api/migration/v1. Requires an admin
     # (system) API token.
     def migration

data/lib/broadcast/delivery_method.rb CHANGED Viewed

@@ -2,8 +2,21 @@
 module Broadcast
   class DeliveryMethod
+    # ActionMailer delivers transactional mail, so the unsubscribe link is off
+    # unless the host app opts back in via broadcast_settings. The option is
+    # consumed here rather than forwarded: Configuration would reject it.
+    DEFAULT_INCLUDE_UNSUBSCRIBE_LINK = false
     def initialize(settings = {})
-      @client = Client.new(**settings)
+      opts = settings.to_h.dup
+      @include_unsubscribe_link =
+        if opts.key?(:include_unsubscribe_link)
+          opts.delete(:include_unsubscribe_link)
+        else
+          DEFAULT_INCLUDE_UNSUBSCRIBE_LINK
+        end
+      @client = Client.new(**opts)
     end
     def deliver!(mail)
@@ -11,7 +24,9 @@ module Broadcast
         to: mail.to&.first,
         subject: mail.subject,
         body: extract_body(mail),
-        reply_to: mail.reply_to&.first
+        reply_to: mail.reply_to&.first,
+        html_body: (true if mail.html_part),
+        include_unsubscribe_link: @include_unsubscribe_link
       )
     rescue Broadcast::WarningError
       # The send succeeded — warnings_mode: :raise is about surfacing ignored

data/lib/broadcast/resources/global_suppressions.rb ADDED Viewed

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+module Broadcast
+  module Resources
+    # The installation-wide suppression list. Addresses on it never receive
+    # mail from any channel. All operations require an admin (system) API
+    # token — a channel token gets a 401.
+    #
+    # There is deliberately no `check` here: checking is a per-channel
+    # question (it reads the channel list too), so it lives on Suppressions.
+    class GlobalSuppressions < Base
+      # List global suppressions (250 per page, with `pagination` metadata;
+      # pass `page:`). Optional `email:` filters by partial match.
+      def list(**params)
+        get('/api/v1/global_suppressions.json', params)
+      end
+      # Add an address to the global list. Already-suppressed is a success
+      # (200 instead of 201).
+      def add(email)
+        post('/api/v1/global_suppressions.json', { email: email })
+      end
+      # Remove an address from the global list only. Channels that suppressed
+      # the same address on their own account keep their block.
+      def remove(email)
+        @client.request(:delete, '/api/v1/global_suppressions.json', { email: email })
+      end
+      # Add up to 10,000 addresses at once. Idempotent. Returns `added`,
+      # `already_suppressed`, and `invalid` counts.
+      def bulk_add(emails)
+        post('/api/v1/global_suppressions/bulk.json', { emails: emails })
+      end
+      # Remove up to 10,000 addresses at once. Returns `removed` and
+      # `not_found` counts.
+      def bulk_remove(emails)
+        @client.request(:delete, '/api/v1/global_suppressions/bulk.json', { emails: emails })
+      end
+    end
+  end
+end

data/lib/broadcast/resources/suppressions.rb ADDED Viewed

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+module Broadcast
+  module Resources
+    # The current channel's suppression list. Addresses on it never receive
+    # broadcasts, sequences, or transactionals from this channel.
+    #
+    # The installation-wide list is a separate resource — see
+    # GlobalSuppressions — but `check` reads across both on purpose: it
+    # answers the question an integration actually asks, "will this address
+    # receive mail?".
+    class Suppressions < Base
+      # List the channel's suppressions (250 per page, with `pagination`
+      # metadata; pass `page:`). Optional `email:` filters by partial,
+      # case-insensitive match.
+      def list(**params)
+        get('/api/v1/suppressions.json', params)
+      end
+      # Add an address to the channel's suppression list.
+      #
+      # Adding an address that is already suppressed is a success (the server
+      # answers 200 instead of 201), so callers do not have to check first.
+      def add(email)
+        post('/api/v1/suppressions.json', { email: email })
+      end
+      # Remove an address from the channel's suppression list. Returns
+      # `removed: false` (not an error) when the address was not on it.
+      # Does not touch the global list.
+      def remove(email)
+        @client.request(:delete, '/api/v1/suppressions.json', { email: email })
+      end
+      # Add up to 10,000 addresses at once. Idempotent: a retried batch cannot
+      # duplicate. Returns `added`, `already_suppressed`, and `invalid` counts.
+      def bulk_add(emails)
+        post('/api/v1/suppressions/bulk.json', { emails: emails })
+      end
+      # Remove up to 10,000 addresses at once. Returns `removed` and
+      # `not_found` counts.
+      def bulk_remove(emails)
+        @client.request(:delete, '/api/v1/suppressions/bulk.json', { emails: emails })
+      end
+      # Will this address receive mail? Reads across both the global and the
+      # channel list — a globally blocked address reports `suppressed: true`
+      # here even though it is absent from the channel's own list. The
+      # response's `scope` says which list matched.
+      def check(email)
+        get('/api/v1/suppressions/check.json', { email: email })
+      end
+    end
+  end
+end

data/lib/broadcast/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module Broadcast
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/broadcast.rb CHANGED Viewed

@@ -20,6 +20,8 @@ require_relative 'broadcast/resources/opt_in_forms'
 require_relative 'broadcast/resources/email_servers'
 require_relative 'broadcast/resources/autopilots'
 require_relative 'broadcast/resources/discovery'
+require_relative 'broadcast/resources/suppressions'
+require_relative 'broadcast/resources/global_suppressions'
 require_relative 'broadcast/resources/migration'
 # ActionMailer integration — only loaded when Rails is present

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: broadcast-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Simon Chiu
@@ -52,11 +52,13 @@ files:
 - lib/broadcast/resources/broadcasts.rb
 - lib/broadcast/resources/discovery.rb
 - lib/broadcast/resources/email_servers.rb
+- lib/broadcast/resources/global_suppressions.rb
 - lib/broadcast/resources/migration.rb
 - lib/broadcast/resources/opt_in_forms.rb
 - lib/broadcast/resources/segments.rb
 - lib/broadcast/resources/sequences.rb
 - lib/broadcast/resources/subscribers.rb
+- lib/broadcast/resources/suppressions.rb
 - lib/broadcast/resources/templates.rb
 - lib/broadcast/resources/transactionals.rb
 - lib/broadcast/resources/webhook_endpoints.rb
@@ -86,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Ruby client for the Broadcast email platform
 test_files: []