broadcast-ruby 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3bd138dfa8311b17c14ef537073cdf62406503d605b83f3d49b96659e28cda9
-  data.tar.gz: 6d7f2dccd5e01060b566bcd35a65a74349a078b9ed68348a4d510a98a8faf219
+  metadata.gz: 361d356c1fde238ba1734363607796b005a839f72b70885e52c2ed0eaa2b4209
+  data.tar.gz: 9a1d12cc2b3680689951e325be2100eb64ed9f2ca021c3d69421f336099dec6d
 SHA512:
-  metadata.gz: '0164853b6f09a1f00227adf8201e0cd53a6ff84ece799471f839994e8b2dae6cc65486e08bc3877b9640056eabf9bba8b9659fc2c8a2a4172117b5b1fbc482cf'
-  data.tar.gz: b31dfa8c5e5f6ebcf6cb3861e92e82fe3b13f66e60d163da7dfbdc5d80abbd669f3a066259aa6316aaa3a1a5017ade083f12a67d82acb84299e1cb271f87b680
+  metadata.gz: 128a65f8767c17b979e98b8516f7c31a99703449487f6fd7cefe93c9940a1c3cb5c4ae21a5144a7236769ec5f41072626694e169ec2eea041f3c1327265c834d
+  data.tar.gz: e54a4fa7d5f1e96f9fbc26a8932c05067a6eda7575ee21f3762cc261b0973d42219536ed1650872746ce2854fa449de9ebc3c0192445ab705ceec0933e36df1d

data/.rubocop.yml

@@ -24,6 +24,8 @@ Metrics/AbcSize:
 
 Metrics/ClassLength:
   Max: 200
+  Exclude:
+    - test/**/*
 
 Metrics/CyclomaticComplexity:
   Max: 15

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2026-04-28
+
+### Added
+- `client.opt_in_forms` resource: list, get, create, update, delete, analytics, create_variant, duplicate
+- `client.email_servers` resource: list, get, create, update, delete, test_connection, copy_to_channel
+- `client.transactionals` resource with full create surface (`template_id`, `preheader`, `include_unsubscribe_link`, `subscriber:` attrs); `client.send_email` and `client.get_email` are now thin shims that delegate
+- Double opt-in support: pass `double_opt_in: true` (or a hash with `reply_to:` / `confirmation_template_id:` / `include_unsubscribe_link:`) to `transactionals.create` and `subscribers.create`. Optional top-level `confirmation_template_id:` is also accepted
+- `Configuration#broadcast_channel_id` plus `client.with_channel(id) { ... }` block API for admin/system tokens — auto-includes the channel on every request inside the block (or globally when set on config), without overriding callers that pass it explicitly
+- `Broadcast::AuthorizationError` for 403 responses (previously fell through to a generic `APIError`)
+- Credential redaction scrubber on `email_servers.update`: values matching the API's bullet-redaction shape on known credential fields are stripped from the payload (with a logger warning) so callers can't accidentally round-trip a redacted response back into the model
+
+### Notes
+- `opt_in_forms.list` returns up to 250 results per page with `pagination` metadata; only main forms are returned (variants are excluded)
+- `opt_in_forms` `index`/`show` JSON shape (rendered via JBuilder views) differs slightly from `create`/`update` (rendered via the controller's inline serializer)
+- `email_servers.copy_to_channel` requires an admin token and is account-scoped in SaaS mode
+
+## [0.1.4] - 2026-03-18
+
+### Fixed
+- Register delivery method at class load time instead of in an initializer. ActionMailer's railtie applies config settings (including `broadcast_settings`) inside `on_load(:action_mailer)`, which ran before our initializer-based registration. This caused `undefined method broadcast_settings=` on boot in Rails 8.1.
+
+## [0.1.3] - 2026-03-18
+
+### Fixed
+- Attempted fix for Railtie timing: use `before: :load_config_initializers`. Did not fully resolve the issue — superseded by 0.1.4.
+
 ## [0.1.2] - 2026-03-18
 
 ### Added

data/Gemfile.lock

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

data/README.md

@@ -59,6 +59,7 @@ client.send_email(
 | `retry_delay` | `1` | Base delay between retries in seconds (multiplied by attempt number) |
 | `debug` | `false` | Log request/response details |
 | `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.
 
@@ -182,6 +183,75 @@ email['queue_at']   # => '2026-03-17T07:59:58Z'
 | `body` | yes | Email content (HTML or plain text) |
 | `reply_to` | no | Reply-to address |
 
+`send_email` is a thin convenience wrapper. For template-based sends, double opt-in, preheaders, and other advanced options, use `client.transactionals.create`:
+
+```ruby
+# Send via a saved Template (resolves subject/body/preheader server-side)
+client.transactionals.create(
+  to: 'user@example.com',
+  template_id: 42,
+  reply_to: 'support@yourapp.com',
+  include_unsubscribe_link: true
+)
+
+# Override individual fields while still using a template
+client.transactionals.create(
+  to: 'user@example.com',
+  template_id: 42,
+  subject: 'Custom subject for this send'
+)
+
+# Set first/last name on a brand-new subscriber created by this send
+client.transactionals.create(
+  to: 'new@example.com',
+  subject: 'Welcome!',
+  body: '<p>Hi {{first_name}}</p>',
+  subscriber: { first_name: 'Jane', last_name: 'Doe' }
+)
+
+# Get delivery status (alias of client.get_email)
+client.transactionals.get_transactional(42)
+```
+
+### Double Opt-In
+
+Pass `double_opt_in: true` to require email confirmation before delivery. The recipient receives a confirmation email; the actual transactional email is held until they confirm. If the recipient is already a confirmed subscriber, `double_opt_in` is ignored and the email sends normally.
+
+```ruby
+# Boolean form: uses the channel's default confirmation template
+result = client.transactionals.create(
+  to: 'new@example.com',
+  subject: 'Welcome!',
+  body: '<p>Confirmation email coming first...</p>',
+  double_opt_in: true
+)
+result['confirmation_status']  # => 'pending'
+result['confirmation_url']     # => 'https://...'
+
+# Hash form: customize the confirmation flow
+client.transactionals.create(
+  to: 'new@example.com',
+  subject: 'Welcome!',
+  body: '<p>...</p>',
+  double_opt_in: {
+    reply_to: 'support@yourapp.com',
+    confirmation_template_id: 7,
+    include_unsubscribe_link: true
+  }
+)
+
+# Equivalent shortcut for confirmation_template_id at the top level
+client.transactionals.create(
+  to: 'new@example.com',
+  subject: 'Welcome!',
+  body: '<p>...</p>',
+  double_opt_in: true,
+  confirmation_template_id: 7
+)
+```
+
+A transactional email server must be configured for the channel and a confirmation template (or default) must exist, otherwise the request returns 422.
+
 ---
 
 ## Subscribers
@@ -263,6 +333,42 @@ client.subscribers.resubscribe('jane@example.com')
 client.subscribers.redact('jane@example.com')
 ```
 
+### Double Opt-In
+
+Pass `double_opt_in: true` (or a hash) to create the subscriber in unconfirmed state and queue a confirmation email. If the subscriber already exists and is confirmed, `double_opt_in` is ignored and the existing record is returned.
+
+```ruby
+# Boolean form (uses the channel's default confirmation template)
+result = client.subscribers.create(
+  email: 'new@example.com',
+  first_name: 'Jane',
+  double_opt_in: true
+)
+result['confirmation_status']  # => 'pending'
+result['confirmation_url']     # => '...'
+
+# Hash form -- customize reply-to, template, and unsubscribe link
+client.subscribers.create(
+  email: 'new@example.com',
+  double_opt_in: {
+    reply_to: 'support@yourapp.com',
+    confirmation_template_id: 7,
+    include_unsubscribe_link: true
+  }
+)
+
+# `confirmation_template_id` is also accepted at the top level
+client.subscribers.create(
+  email: 'new@example.com',
+  double_opt_in: true,
+  confirmation_template_id: 7
+)
+```
+
+`double_opt_in` and `confirmation_template_id` are top-level options -- they do **not** go inside the `subscriber:` envelope on the wire (the gem extracts them automatically).
+
+The channel must have an active transactional email server and a confirmation template (default or `confirmation_template_id`), otherwise the request returns 422.
+
 ---
 
 ## Sequences
@@ -543,6 +649,201 @@ client.templates.delete(1)
 
 ---
 
+## Opt-In Forms
+
+Embeddable subscription forms with theming, A/B variants, and analytics.
+
+**Required permissions:** `opt_in_forms_read`, `opt_in_forms_write`
+
+```ruby
+# List forms (paginated, up to 250 per page; only main forms -- variants are excluded)
+result = client.opt_in_forms.list
+result['opt_in_forms']            # => [{'id' => 1, 'label' => 'Newsletter', ...}, ...]
+result['pagination']['current']   # => 1
+result['pagination']['total']     # => 12
+
+# Filter
+client.opt_in_forms.list(filter: 'newsletter', widget_type: 'inline', enabled: 'true')
+
+# Get a single form (full payload incl. blocks and settings)
+form = client.opt_in_forms.get_opt_in_form(1)
+
+# Create a form
+result = client.opt_in_forms.create(
+  label: 'Newsletter Signup',
+  form_type: 'inline',
+  widget_type: 'inline',
+  enabled: true,
+  theme_settings: {
+    colors: { primary: '#3b82f6', background: '#ffffff', text: '#111827', border: '#d1d5db' }
+  },
+  automation_settings: {
+    tag_list: 'newsletter',
+    send_welcome_email: true,
+    double_opt_in: true,
+    sequence_ids: [3]
+  }
+)
+
+# Update (deeply nested settings hashes pass through verbatim)
+client.opt_in_forms.update(1, enabled: false)
+
+# Delete
+client.opt_in_forms.delete(1)
+```
+
+### Analytics
+
+```ruby
+# Last 30 days by default
+client.opt_in_forms.analytics(1)
+
+# Custom date range -- accepts Date, Time, or ISO-8601 strings
+client.opt_in_forms.analytics(1,
+  start_date: Date.new(2026, 1, 1),
+  end_date: Date.new(2026, 1, 31)
+)
+# Returns: { totals: { views, unique_views, submissions, conversion_rate },
+#            daily: [...], variants: [...] }
+```
+
+### A/B Variants
+
+```ruby
+# Create a variant of a form (defaults to "Variant N" / weight 50)
+client.opt_in_forms.create_variant(1, name: 'B', weight: 50)
+
+# Duplicate a form into a new top-level form (counts toward your plan limit)
+client.opt_in_forms.duplicate(1, label: 'Newsletter Signup (Copy)')
+```
+
+> **Note:** `index`/`show` and `create`/`update` return slightly different JSON shapes (the index/show responses go through JBuilder views; create/update use a richer inline serializer with analytics counts and embed URL). Don't depend on field-level parity between these paths.
+
+---
+
+## Email Servers
+
+Configure outbound email providers for a channel (SMTP, AWS SES, Postmark, Inboxroad, SMTP.com, etc.).
+
+**Required permissions:** `email_servers_read`, `email_servers_write`
+
+```ruby
+# List email servers
+result = client.email_servers.list
+result['data']   # => [{'id' => 1, 'label' => 'Primary SES', 'vendor' => 'aws_ses', ...}, ...]
+result['total']  # => 3
+
+# Pagination
+client.email_servers.list(limit: 10, offset: 0)
+
+# Get a single email server
+es = client.email_servers.get_email_server(1)
+
+# Create -- example: AWS SES
+client.email_servers.create(
+  label: 'Primary SES',
+  vendor: 'aws_ses',
+  delivery_method: 'aws_ses',
+  active: true,
+  aws_region: 'us-east-1',
+  aws_access_key_id: 'AKIA...',
+  aws_secret_access_key: 'secret...',
+  use_for_broadcasts: true,
+  use_for_sequences: true,
+  use_for_transactionals: true
+)
+
+# Create -- example: SMTP
+client.email_servers.create(
+  label: 'Backup SMTP',
+  vendor: 'smtp',
+  delivery_method: 'smtp',
+  smtp_address: 'smtp.example.com',
+  smtp_port: 587,
+  smtp_username: 'user',
+  smtp_password: 'pass',
+  smtp_authentication: 'plain',
+  smtp_enable_starttls_auto: true,
+  emails_per_hour: 10000
+)
+
+# Update -- pass only the fields you want to change
+client.email_servers.update(1, label: 'Primary SES (updated)', emails_per_hour: 50000)
+
+# Test the connection (toggles `active` based on result)
+result = client.email_servers.test_connection(1)
+result['success']  # => true / false
+result['message']  # => 'Connection successful' / 'Connection failed'
+
+# Delete
+client.email_servers.delete(1)
+```
+
+### Credential Redaction
+
+API responses redact credential fields with bullet characters (e.g. `smtp_password: "abcd••••••wxyz"`). **Never round-trip a fetched response back into `update`** -- the gem detects redacted-shape values on known credential fields (`smtp_password`, `aws_*`, `postmark_api_token`, `inboxroad_api_token`, `smtp_com_api_key`) and silently strips them from the payload (with a warning) so they don't overwrite the real value:
+
+```ruby
+# Safe -- only the fields you actually want to change
+client.email_servers.update(1, label: 'New label', emails_per_hour: 25000)
+
+# This would corrupt credentials WITHOUT the gem's scrubber:
+es = client.email_servers.get_email_server(1)
+client.email_servers.update(1, **es)  # bullets get scrubbed, label still updates
+
+# To rotate a credential, pass the real new value
+client.email_servers.update(1, smtp_password: 'new-real-secret')
+```
+
+### Cross-Channel Copy (admin tokens only)
+
+`copy_to_channel` clones an email server (with all settings and headers) into another channel. **Requires an admin/system token** with `email_servers_write` permission. Regular per-channel tokens get `Broadcast::AuthorizationError`. In SaaS mode, the target channel must be in the admin token creator's account.
+
+```ruby
+admin_client = Broadcast::Client.new(
+  api_token: ENV['BROADCAST_ADMIN_TOKEN'],
+  broadcast_channel_id: 1   # the source server's channel
+)
+
+admin_client.email_servers.copy_to_channel(99, target_channel_id: 7)
+```
+
+---
+
+## Channel Scoping (Admin/System Tokens)
+
+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.
+
+The gem auto-includes `broadcast_channel_id` from your `Configuration` on every request:
+
+```ruby
+# Set globally
+client = Broadcast::Client.new(
+  api_token: ENV['BROADCAST_ADMIN_TOKEN'],
+  broadcast_channel_id: 1
+)
+client.email_servers.list  # broadcast_channel_id=1 is appended automatically
+```
+
+For multi-channel scripts, use `with_channel` to scope a block of calls to a specific channel:
+
+```ruby
+client = Broadcast::Client.new(api_token: ENV['BROADCAST_ADMIN_TOKEN'])
+
+client.with_channel(1) do
+  client.email_servers.list
+  client.opt_in_forms.list
+end
+
+client.with_channel(2) do
+  client.subscribers.list
+end
+```
+
+`with_channel` overrides the config-level value inside the block. Per-call `broadcast_channel_id:` always wins over both. The override is thread-local, so it's safe to share a `Client` instance across threads.
+
+---
+
 ## Webhook Endpoints
 
 Receive real-time notifications when events occur (email delivered, subscriber created, sequence completed, etc.).
@@ -640,6 +941,7 @@ All API errors inherit from `Broadcast::Error`. Put specific errors before gener
 begin
   client.send_email(to: 'user@example.com', subject: 'Hi', body: 'Hello')
 rescue Broadcast::AuthenticationError  # 401 -- invalid or expired API token
+rescue Broadcast::AuthorizationError   # 403 -- token lacks the required permission, or admin-only endpoint
 rescue Broadcast::NotFoundError        # 404 -- resource does not exist
 rescue Broadcast::ValidationError      # 422 -- missing or invalid parameters
 rescue Broadcast::RateLimitError       # 429 -- exceeded 120 requests/minute
@@ -665,6 +967,8 @@ Each token can be scoped to specific resources. The ActionMailer delivery method
 | Broadcasts | `broadcasts_read` -- list, get, statistics | `broadcasts_write` -- create, update, delete, send, schedule |
 | Segments | `segments_read` -- list, get | `segments_write` -- create, update, delete |
 | Templates | `templates_read` -- list, get | `templates_write` -- create, update, delete |
+| 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 |
 
 ---
@@ -677,6 +981,12 @@ Each token can be scoped to specific resources. The ActionMailer delivery method
 - **Wrong host:** If you're self-hosting, make sure `host` points to your Broadcast instance, not `sendbroadcast.com`.
 - **Missing permissions:** Your token may not have the required permissions for the resource you're accessing. Check the [permissions table](#api-token-permissions).
 
+### `Broadcast::AuthorizationError` (403)
+
+- **Missing permission:** Your token doesn't have the read or write permission for the resource (e.g. calling `client.opt_in_forms.create` with a token that only has `opt_in_forms_read`).
+- **Admin-only endpoint:** `email_servers.copy_to_channel` requires an admin/system token. Regular per-channel tokens cannot perform cross-channel operations.
+- **Missing channel scope on admin token:** Admin tokens require `broadcast_channel_id` on every request. Set it on `Broadcast::Client.new(broadcast_channel_id: …)` or wrap calls with `client.with_channel(id) { … }`.
+
 ### `Broadcast::ValidationError` (422)
 
 - **Missing required fields:** Check the parameters table for the method you're calling.

data/lib/broadcast/client.rb

@@ -6,6 +6,8 @@ require 'uri'
 
 module Broadcast
   class Client
+    CHANNEL_OVERRIDE_KEY = :__broadcast_ruby_channel_override
+
     attr_reader :config
 
     def initialize(**settings)
@@ -14,16 +16,35 @@ module Broadcast
       @config.validate!
     end
 
-    # --- Transactional email ---
+    # --- Channel scoping (admin/system tokens) ---
 
-    def send_email(to:, subject:, body:, reply_to: nil)
-      payload = { to: to, subject: subject, body: body }
-      payload[:reply_to] = reply_to if reply_to
-      request(:post, '/api/v1/transactionals.json', payload)
+    # Run a block with a temporary broadcast_channel_id override that will be
+    # auto-included on every request inside the block. Useful for admin/system
+    # tokens that need to scope each call to a specific channel.
+    #
+    #   client.with_channel(123) do
+    #     client.email_servers.list
+    #   end
+    def with_channel(broadcast_channel_id)
+      key = channel_override_key
+      previous = Thread.current[key]
+      Thread.current[key] = broadcast_channel_id
+      yield self
+    ensure
+      Thread.current[key] = previous
+    end
+
+    # --- Transactional email (convenience shims) ---
+
+    # Thin convenience wrapper around `transactionals.create`. Use
+    # `client.transactionals.create` directly for template_id, double_opt_in,
+    # preheader, 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)
     end
 
     def get_email(id)
-      request(:get, "/api/v1/transactionals/#{id}.json")
+      transactionals.get_transactional(id)
     end
 
     # --- Resource sub-clients ---
@@ -52,35 +73,76 @@ module Broadcast
       @webhook_endpoints ||= Resources::WebhookEndpoints.new(self)
     end
 
-    # @api private
-    def request(method, path, body_or_params = nil)
-      uri = URI("#{@config.host}#{path}")
-
-      if method == :get && body_or_params.is_a?(Hash) && body_or_params.any?
-        uri.query = URI.encode_www_form(flatten_params(body_or_params))
-      end
+    def transactionals
+      @transactionals ||= Resources::Transactionals.new(self)
+    end
 
-      retry_with_backoff do
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = uri.scheme == 'https'
-        http.open_timeout = @config.open_timeout
-        http.read_timeout = @config.timeout
+    def opt_in_forms
+      @opt_in_forms ||= Resources::OptInForms.new(self)
+    end
 
-        req = build_request(method, uri)
-        req.body = body_or_params.to_json if method != :get && body_or_params.is_a?(Hash) && body_or_params.any?
+    def email_servers
+      @email_servers ||= Resources::EmailServers.new(self)
+    end
 
-        log_request(req, method == :get ? nil : body_or_params) if @config.debug
+    # @api private
+    def request(method, path, body_or_params = nil)
+      payload = inject_channel_scope(body_or_params)
+      uri = build_uri(path, method, payload)
 
-        response = http.request(req)
-        log_response(response) if @config.debug
-        handle_response(response)
-      end
+      retry_with_backoff { execute(method, uri, payload) }
     rescue Net::OpenTimeout, Net::ReadTimeout => e
       raise Broadcast::TimeoutError, "Request timeout: #{e.message}"
     end
 
     private
 
+    def channel_override_key
+      :"#{CHANNEL_OVERRIDE_KEY}_#{object_id}"
+    end
+
+    def active_channel_id
+      Thread.current[channel_override_key] || @config.broadcast_channel_id
+    end
+
+    # Auto-include broadcast_channel_id in request payload when configured (or
+    # set via with_channel) and not already specified by the caller.
+    def inject_channel_scope(body_or_params)
+      channel_id = active_channel_id
+      return body_or_params if channel_id.nil?
+
+      payload = body_or_params.is_a?(Hash) ? body_or_params.dup : {}
+      return payload if payload[:broadcast_channel_id] || payload['broadcast_channel_id']
+
+      payload[:broadcast_channel_id] = channel_id
+      payload
+    end
+
+    def build_uri(path, method, payload)
+      uri = URI("#{@config.host}#{path}")
+      uri.query = URI.encode_www_form(flatten_params(payload)) if method == :get && payload_present?(payload)
+      uri
+    end
+
+    def execute(method, uri, payload)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+
+      req = build_request(method, uri)
+      req.body = payload.to_json if method != :get && payload_present?(payload)
+
+      log_request(req, method == :get ? nil : payload) if @config.debug
+      response = http.request(req)
+      log_response(response) if @config.debug
+      handle_response(response)
+    end
+
+    def payload_present?(payload)
+      payload.is_a?(Hash) && payload.any?
+    end
+
     def build_request(method, uri)
       klass = case method
               when :get then Net::HTTP::Get
@@ -97,25 +159,34 @@ module Broadcast
       req
     end
 
+    ERROR_MAPPING = {
+      401 => [AuthenticationError, 'Authentication failed'],
+      403 => [AuthorizationError, 'Not authorized'],
+      404 => [NotFoundError, 'Resource not found'],
+      422 => [ValidationError, 'Validation failed'],
+      429 => [RateLimitError, 'Rate limit exceeded']
+    }.freeze
+    SERVER_ERROR_CODES = [500, 502, 503, 504].freeze
+    private_constant :ERROR_MAPPING, :SERVER_ERROR_CODES
+
     def handle_response(response)
-      case response.code.to_i
-      when 200, 201
-        return {} if response.body.nil? || response.body.strip.empty?
-
-        JSON.parse(response.body)
-      when 401
-        raise AuthenticationError, parse_error(response) || 'Authentication failed'
-      when 404
-        raise NotFoundError, parse_error(response) || 'Resource not found'
-      when 422
-        raise ValidationError, parse_error(response) || 'Validation failed'
-      when 429
-        raise RateLimitError, parse_error(response) || 'Rate limit exceeded'
-      when 500, 502, 503, 504
-        raise APIError, parse_error(response) || "Server error (#{response.code})"
-      else
-        raise APIError, parse_error(response) || "Unexpected response: #{response.code}"
+      code = response.code.to_i
+      return parse_success_body(response) if [200, 201].include?(code)
+
+      if (mapping = ERROR_MAPPING[code])
+        klass, default = mapping
+        raise klass, parse_error(response) || default
       end
+
+      raise APIError, parse_error(response) || "Server error (#{code})" if SERVER_ERROR_CODES.include?(code)
+
+      raise APIError, parse_error(response) || "Unexpected response: #{code}"
+    end
+
+    def parse_success_body(response)
+      return {} if response.body.nil? || response.body.strip.empty?
+
+      JSON.parse(response.body)
     end
 
     def parse_error(response)

data/lib/broadcast/configuration.rb

@@ -9,7 +9,8 @@ module Broadcast
                   :retry_attempts,
                   :retry_delay,
                   :logger,
-                  :debug
+                  :debug,
+                  :broadcast_channel_id
 
     def initialize
       @api_token = nil
@@ -20,6 +21,7 @@ module Broadcast
       @retry_delay = 1
       @logger = nil
       @debug = false
+      @broadcast_channel_id = nil
     end
 
     def validate!

data/lib/broadcast/errors.rb

@@ -9,6 +9,8 @@ module Broadcast
 
   class AuthenticationError < APIError; end
 
+  class AuthorizationError < APIError; end
+
   class NotFoundError < APIError; end
 
   class RateLimitError < APIError; end

data/lib/broadcast/resources/email_servers.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class EmailServers < Base
+      # Fields the API returns redacted (bullet-masked). When updating, never
+      # round-trip these values back from a fetch — the gem strips them out
+      # of the payload (with a logger warning) to prevent corrupting credentials.
+      REDACTED_FIELDS = %i[
+        smtp_password
+        aws_access_key_id
+        aws_secret_access_key
+        outbound_aws_access_key_id
+        outbound_aws_secret_access_key
+        postmark_api_token
+        inboxroad_api_token
+        smtp_com_api_key
+      ].freeze
+
+      # Matches the API's redaction shape: 8 bullets, OR 4-char prefix + bullets + 4-char suffix.
+      REDACTED_PATTERN = /\A(?:•{8}|.{0,4}•+.{0,4})\z/
+
+      def list(limit: nil, offset: nil)
+        params = {}
+        params[:limit] = limit unless limit.nil?
+        params[:offset] = offset unless offset.nil?
+        get('/api/v1/email_servers', params)
+      end
+
+      def get_email_server(id)
+        get("/api/v1/email_servers/#{id}")
+      end
+
+      def create(**attrs)
+        post('/api/v1/email_servers', { email_server: attrs })
+      end
+
+      # Update an email server. Attrs are wrapped under `email_server:` on the wire.
+      #
+      # CAUTION: API responses redact credential fields (e.g. `smtp_password`)
+      # with bullet characters. Never echo a fetched response back into update —
+      # this method scrubs values that match the redaction pattern, but you
+      # should pass only the fields you actually want to change.
+      def update(id, **attrs)
+        scrubbed = scrub_redacted(attrs)
+        patch("/api/v1/email_servers/#{id}", { email_server: scrubbed })
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/email_servers/#{id}")
+      end
+
+      def test_connection(id)
+        post("/api/v1/email_servers/#{id}/test_connection")
+      end
+
+      # Copy an email server to another channel. Requires an admin/system token.
+      # In SaaS mode, target_channel_id is scoped to the token creator's account.
+      def copy_to_channel(id, target_channel_id:)
+        post("/api/v1/email_servers/#{id}/copy_to_channel", { target_channel_id: target_channel_id })
+      end
+
+      private
+
+      def scrub_redacted(attrs)
+        scrubbed = {}
+        attrs.each do |key, value|
+          if REDACTED_FIELDS.include?(key.to_sym) && value.is_a?(String) && value.match?(REDACTED_PATTERN)
+            warn_redacted(key)
+            next
+          end
+          scrubbed[key] = value
+        end
+        scrubbed
+      end
+
+      def warn_redacted(field)
+        msg = "[broadcast-ruby] Dropped redacted #{field} from update payload — " \
+              'pass the real credential or omit the field'
+        if @client.config.logger
+          @client.config.logger.warn(msg)
+        else
+          Kernel.warn(msg)
+        end
+      end
+    end
+  end
+end

data/lib/broadcast/resources/opt_in_forms.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Broadcast
+  module Resources
+    class OptInForms < Base
+      # List opt-in forms.
+      #
+      # NOTE: returns up to 250 results per page along with `pagination`
+      # metadata. Variants are excluded (only main forms are returned).
+      # Pass `page:` to advance.
+      #
+      # Optional filters: filter: (label substring), widget_type:, enabled: 'true'
+      def list(**params)
+        get('/api/v1/opt_in_forms', params)
+      end
+
+      def get_opt_in_form(id)
+        get("/api/v1/opt_in_forms/#{id}")
+      end
+
+      # Create an opt-in form. Attrs are wrapped under `opt_in_form:` on the wire.
+      # Nested settings hashes (theme_settings, automation_settings, security_settings,
+      # trigger_settings, widget_settings) and arrays (opt_in_form_blocks_attributes,
+      # opt_in_post_submission_blocks_attributes) are passed through verbatim.
+      def create(**attrs)
+        post('/api/v1/opt_in_forms', { opt_in_form: attrs })
+      end
+
+      def update(id, **attrs)
+        patch("/api/v1/opt_in_forms/#{id}", { opt_in_form: attrs })
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/opt_in_forms/#{id}")
+      end
+
+      # Performance analytics for the form. start_date/end_date accept Date,
+      # Time, or ISO-8601 strings (default: last 30 days).
+      def analytics(id, start_date: nil, end_date: nil)
+        params = {}
+        params[:start_date] = coerce_date(start_date) if start_date
+        params[:end_date] = coerce_date(end_date) if end_date
+        get("/api/v1/opt_in_forms/#{id}/analytics", params)
+      end
+
+      def create_variant(id, name: nil, weight: nil)
+        body = {}
+        body[:name] = name unless name.nil?
+        body[:weight] = weight unless weight.nil?
+        post("/api/v1/opt_in_forms/#{id}/variants", body)
+      end
+
+      def duplicate(id, label: nil)
+        body = {}
+        body[:label] = label unless label.nil?
+        post("/api/v1/opt_in_forms/#{id}/duplicate", body)
+      end
+
+      private
+
+      def coerce_date(value)
+        case value
+        when Date, Time, DateTime then value.iso8601
+        else value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/broadcast/resources/subscribers.rb

@@ -11,8 +11,26 @@ module Broadcast
         get('/api/v1/subscribers/find.json', { email: email })
       end
 
+      # Create or upsert a subscriber.
+      #
+      # Subscriber attributes (wrapped under `subscriber:` on the wire):
+      #   email:, first_name:, last_name:, is_active:, source:,
+      #   subscribed_at:, ip_address:, tags: [...], custom_data: {...}
+      #
+      # Top-level options (NOT wrapped under `subscriber:`):
+      #   double_opt_in:               true | { reply_to:, confirmation_template_id:, include_unsubscribe_link: }
+      #                                When set, the subscriber is created in unconfirmed state
+      #                                and a confirmation email is queued.
+      #   confirmation_template_id:    custom confirmation template (used with double_opt_in: true)
       def create(**attrs)
-        post('/api/v1/subscribers.json', { subscriber: attrs })
+        double_opt_in = attrs.delete(:double_opt_in)
+        confirmation_template_id = attrs.delete(:confirmation_template_id)
+
+        payload = { subscriber: attrs }
+        payload[:double_opt_in] = double_opt_in unless double_opt_in.nil?
+        payload[:confirmation_template_id] = confirmation_template_id unless confirmation_template_id.nil?
+
+        post('/api/v1/subscribers.json', payload)
       end
 
       def update(email, **attrs)

data/lib/broadcast/resources/transactionals.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class Transactionals < Base
+      # Send a transactional email.
+      #
+      # Required:
+      #   to:      recipient email address
+      #
+      # One of subject/body or template_id is required (template_id resolves
+      # subject and body server-side; subject/body override the template).
+      #
+      # Optional:
+      #   subject:, body:, preheader:
+      #   reply_to:
+      #   template_id:                 resolve subject/body/preheader from a Template
+      #   include_unsubscribe_link:    boolean
+      #   double_opt_in:               true | { reply_to:, confirmation_template_id:, include_unsubscribe_link: }
+      #                                Holds the email until the recipient confirms.
+      #   confirmation_template_id:    custom confirmation template (used with double_opt_in: true)
+      #   subscriber:                  { first_name:, last_name: } — populates Subscriber on first send
+      # rubocop:disable Metrics/ParameterLists -- mirrors the API's flat param surface
+      def create(to:, subject: nil, body: nil, reply_to: nil, preheader: nil,
+                 template_id: nil, include_unsubscribe_link: nil,
+                 double_opt_in: nil, confirmation_template_id: nil,
+                 subscriber: nil, **extra)
+        # rubocop:enable Metrics/ParameterLists
+        payload = { to: to }
+        payload[:subject] = subject unless subject.nil?
+        payload[:body] = body unless body.nil?
+        payload[:preheader] = preheader unless preheader.nil?
+        payload[:reply_to] = reply_to unless reply_to.nil?
+        payload[:template_id] = template_id unless template_id.nil?
+        payload[:include_unsubscribe_link] = include_unsubscribe_link unless include_unsubscribe_link.nil?
+        payload[:double_opt_in] = double_opt_in unless double_opt_in.nil?
+        payload[:confirmation_template_id] = confirmation_template_id unless confirmation_template_id.nil?
+        payload[:subscriber] = subscriber unless subscriber.nil?
+        payload.merge!(extra) unless extra.empty?
+
+        post('/api/v1/transactionals.json', payload)
+      end
+
+      def get_transactional(id)
+        get("/api/v1/transactionals/#{id}.json")
+      end
+    end
+  end
+end

data/lib/broadcast/version.rb

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

data/lib/broadcast.rb

@@ -12,6 +12,9 @@ require_relative 'broadcast/resources/broadcasts'
 require_relative 'broadcast/resources/segments'
 require_relative 'broadcast/resources/templates'
 require_relative 'broadcast/resources/webhook_endpoints'
+require_relative 'broadcast/resources/transactionals'
+require_relative 'broadcast/resources/opt_in_forms'
+require_relative 'broadcast/resources/email_servers'
 
 # ActionMailer integration — only loaded when Rails is present
 if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: broadcast-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Simon Chiu
@@ -47,10 +47,13 @@ files:
 - lib/broadcast/railtie.rb
 - lib/broadcast/resources/base.rb
 - lib/broadcast/resources/broadcasts.rb
+- lib/broadcast/resources/email_servers.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/templates.rb
+- lib/broadcast/resources/transactionals.rb
 - lib/broadcast/resources/webhook_endpoints.rb
 - lib/broadcast/version.rb
 - lib/broadcast/webhook.rb