broadcast-ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 798e8750d07fb38ea8ab9b79b3bdbcf9f3c267a09943d2aa49fc87d03b18eacb
-  data.tar.gz: 7113b7abf01a71d1715c10e1b4170e9267426e12b304fff4c61c8ce15a6d457c
+  metadata.gz: 8f76251ad3cf3d351bd4b197ccc5b4035af1eea66290380050c6f5108ec48b6a
+  data.tar.gz: 85c3e88178863291ab1da149797f71ea36a7eeaf3418bb72bdcf95ab92dfcf7e
 SHA512:
-  metadata.gz: d92a6f509c322da7e7af7b538c583dffc11eb6cda4abe424da7e0c10a4bad842149416b036f728568e7f2c92815620ed929894e4cbd765b06402d14ef4cfec53
-  data.tar.gz: a543c779489d537034c52dd5f73db4482fea1268fe250858a601ee7aefa6f4829d330f593a1e8134314de7511d5b283def5fea229d366f7d0ef9435935f65261
+  metadata.gz: 5d71f0add4f5ae7b00705753069c6eee46831c2a1a9b7af36f7dc7cd27d522100d471923a3450a2cd5bab6897b567ace37c127d8e9df16e7e9cef57f53f5a55e
+  data.tar.gz: f31f85327c7c231c42d5134961387b5da21d2cc6a9080ca8d31061d5be540a4c38f6e4a9641a4c66427767a2ba24129d746f5ba0ebcebf5a4f320b0d12ea29ca

data/Gemfile

@@ -4,6 +4,8 @@ source 'https://rubygems.org'
 
 gemspec
 
+gem 'actionmailer', '>= 6.0'
+gem 'mail', '~> 2.8'
 gem 'minitest', '~> 5.0'
 gem 'rake', '~> 13.0'
 gem 'rubocop', '~> 1.0'

data/Gemfile.lock

@@ -7,24 +7,96 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    actionmailer (8.1.2)
+      actionpack (= 8.1.2)
+      actionview (= 8.1.2)
+      activejob (= 8.1.2)
+      activesupport (= 8.1.2)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.1.2)
+      actionview (= 8.1.2)
+      activesupport (= 8.1.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actionview (8.1.2)
+      activesupport (= 8.1.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.1.2)
+      activesupport (= 8.1.2)
+      globalid (>= 0.3.6)
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     addressable (2.8.9)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
     bigdecimal (4.0.1)
+    builder (3.3.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
     crack (1.0.1)
       bigdecimal
       rexml
+    crass (1.0.6)
+    date (3.5.1)
+    drb (2.2.3)
+    erubi (1.13.1)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
     hashdiff (1.2.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
     json (2.19.1)
     json-schema (6.2.0)
       addressable (~> 2.8)
       bigdecimal (>= 3.1, < 5)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.25.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.9.0)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
     mcp (0.8.0)
       json-schema (>= 4.1)
+    mini_mime (1.1.5)
     minitest (5.27.0)
+    net-imap (0.6.3)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nokogiri (1.19.1-arm64-darwin)
+      racc (~> 1.4)
     parallel (1.27.0)
     parser (3.3.10.2)
       ast (~> 2.4.1)
@@ -32,6 +104,19 @@ GEM
     prism (1.9.0)
     public_suffix (7.0.5)
     racc (1.8.1)
+    rack (3.2.5)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
     rainbow (3.1.1)
     rake (13.3.1)
     regexp_parser (2.11.3)
@@ -52,9 +137,15 @@ GEM
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    timeout (0.6.1)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
+    uri (1.1.1)
+    useragent (0.16.11)
     webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -62,34 +153,63 @@ GEM
 
 PLATFORMS
   arm64-darwin-24
-  ruby
 
 DEPENDENCIES
+  actionmailer (>= 6.0)
   broadcast-ruby!
+  mail (~> 2.8)
   minitest (~> 5.0)
   rake (~> 13.0)
   rubocop (~> 1.0)
   webmock (~> 3.0)
 
 CHECKSUMS
+  actionmailer (8.1.2) sha256=f4c1d2060f653bfe908aa7fdc5a61c0e5279670de992146582f2e36f8b9175e9
+  actionpack (8.1.2) sha256=ced74147a1f0daafaa4bab7f677513fd4d3add574c7839958f7b4f1de44f8423
+  actionview (8.1.2) sha256=80455b2588911c9b72cec22d240edacb7c150e800ef2234821269b2b2c3e2e5b
+  activejob (8.1.2) sha256=908dab3713b101859536375819f4156b07bdf4c232cc645e7538adb9e302f825
+  activesupport (8.1.2) sha256=88842578ccd0d40f658289b0e8c842acfe9af751afee2e0744a7873f50b6fdae
   addressable (2.8.9) sha256=cc154fcbe689711808a43601dee7b980238ce54368d23e127421753e46895485
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
   broadcast-ruby (0.1.0)
+  builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
   crack (1.0.1) sha256=ff4a10390cd31d66440b7524eb1841874db86201d5b70032028553130b6d4c7e
+  crass (1.0.6) sha256=dc516022a56e7b3b156099abc81b6d2b08ea1ed12676ac7a5657617f012bd45d
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
+  globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
+  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   json (2.19.1) sha256=dd94fdc59e48bff85913829a32350b3148156bc4fd2a95a2568a78b11344082d
   json-schema (6.2.0) sha256=e8bff46ed845a22c1ab2bd0d7eccf831c01fe23bb3920caa4c74db4306813666
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  loofah (2.25.1) sha256=d436c73dbd0c1147b16c4a41db097942d217303e1f7728704b37e4df9f6d2e04
+  mail (2.9.0) sha256=6fa6673ecd71c60c2d996260f9ee3dd387d4673b8169b502134659ece6d34941
   mcp (0.8.0) sha256=ae8bd146bb8e168852866fd26f805f52744f6326afb3211e073f78a95e0c34fb
+  mini_mime (1.1.5) sha256=8681b7e2e4215f2a159f9400b5816d85e9d8c6c6b491e96a12797e798f8bccef
   minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
+  net-imap (0.6.3) sha256=9bab75f876596d09ee7bf911a291da478e0cd6badc54dfb82874855ccc82f2ad
+  net-pop (0.1.2) sha256=848b4e982013c15b2f0382792268763b748cce91c9e91e36b0f27ed26420dff3
+  net-protocol (0.2.2) sha256=aa73e0cba6a125369de9837b8d8ef82a61849360eba0521900e2c3713aa162a8
+  net-smtp (0.5.1) sha256=ed96a0af63c524fceb4b29b0d352195c30d82dd916a42f03c62a3a70e5b70736
+  nokogiri (1.19.1-arm64-darwin) sha256=dfe2d337e6700eac47290407c289d56bcf85805d128c1b5a6434ddb79731cb9e
   parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
   parser (3.3.10.2) sha256=6f60c84aa4bdcedb6d1a2434b738fe8a8136807b6adc8f7f53b97da9bc4e9357
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rack (3.2.5) sha256=4cbd0974c0b79f7a139b4812004a62e4c60b145cba76422e288ee670601ed6d3
+  rack-session (2.1.1) sha256=0b6dc07dea7e4b583f58a48e8b806d4c9f1c6c9214ebc202ec94562cbea2e4e9
+  rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
+  rails-dom-testing (2.3.0) sha256=8acc7953a7b911ca44588bf08737bc16719f431a1cc3091a292bca7317925c1d
+  rails-html-sanitizer (1.7.0) sha256=28b145cceaf9cc214a9874feaa183c3acba036c9592b19886e0e45efc62b1e89
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
   rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
   regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
@@ -97,8 +217,13 @@ CHECKSUMS
   rubocop (1.85.1) sha256=3dbcf9e961baa4c376eeeb2a03913dca5e3987033b04d38fa538aa1e7406cc77
   rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  timeout (0.6.1) sha256=78f57368a7e7bbadec56971f78a3f5ecbcfb59b7fcbb0a3ed6ddc08a5094accb
+  tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+  useragent (0.16.11) sha256=700e6413ad4bb954bb63547fa098dddf7b0ebe75b40cc6f93b8d54255b173844
   webmock (3.26.1) sha256=4f696fb57c90a827c20aadb2d4f9058bbff10f7f043bd0d4c3f58791143b1cd7
 
 BUNDLED WITH

data/README.md

@@ -6,13 +6,35 @@ Works with [sendbroadcast.com](https://sendbroadcast.com) or any self-hosted Bro
 
 ## Installation
 
+Add to your Gemfile:
+
 ```ruby
 gem 'broadcast-ruby'
 ```
 
+For plain Ruby scripts (non-Rails):
+
+```ruby
+require 'broadcast'
+```
+
+## Getting Your API Token
+
+1. Log in to your Broadcast dashboard
+2. Go to **Settings > API Keys**
+3. Click **New API Key**
+4. Name it, select the permissions you need (see [Permissions](#api-token-permissions) below), and save
+5. Copy the token
+
 ## Quick Start
 
+**In a Rails app?** Jump to [Rails ActionMailer Integration](#rails-actionmailer-integration) -- you don't need to use the client directly.
+
+**In a plain Ruby script or non-Rails app?** Use the client:
+
 ```ruby
+require 'broadcast'
+
 client = Broadcast::Client.new(
   api_token: 'your-token',
   host: 'https://sendbroadcast.com'  # or your self-hosted URL
@@ -44,11 +66,91 @@ All methods return parsed JSON as Ruby Hashes with string keys.
 
 ---
 
+## Rails ActionMailer Integration
+
+In a Rails app, the gem auto-registers a `:broadcast` delivery method. Your existing mailers work unchanged.
+
+First, store your API token in Rails credentials:
+
+```bash
+bin/rails credentials:edit
+```
+
+Add:
+
+```yaml
+broadcast:
+  api_token: your-token-here
+```
+
+Then configure production to use Broadcast:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :broadcast
+config.action_mailer.broadcast_settings = {
+  api_token: Rails.application.credentials.dig(:broadcast, :api_token),
+  host: 'https://sendbroadcast.com'
+}
+```
+
+All your mailers just work:
+
+```ruby
+UserMailer.welcome(user).deliver_later
+PasswordsMailer.reset(user).deliver_now
+```
+
+The delivery method extracts the HTML body (falling back to text), subject, recipient, and reply-to from the rendered email and sends it via Broadcast's transactional API. Delivery errors raise `Broadcast::DeliveryError`, which lets Active Job (Solid Queue, Sidekiq, etc.) retry automatically.
+
+Development and test environments are unaffected:
+
+```ruby
+# config/environments/development.rb
+config.action_mailer.delivery_method = :letter_opener
+
+# config/environments/test.rb
+config.action_mailer.delivery_method = :test
+```
+
+### Migrating from Postmark
+
+Replace in your Gemfile:
+
+```diff
+- gem 'postmark-rails'
++ gem 'broadcast-ruby'
+```
+
+Replace in `config/environments/production.rb`:
+
+```diff
+- config.action_mailer.delivery_method = :postmark
+- config.action_mailer.postmark_settings = {
+-   api_token: Rails.application.credentials.dig(:postmark, :api_token)
+- }
++ config.action_mailer.delivery_method = :broadcast
++ config.action_mailer.broadcast_settings = {
++   api_token: Rails.application.credentials.dig(:broadcast, :api_token),
++   host: 'https://sendbroadcast.com'
++ }
+```
+
+Your mailer classes, views, and tests stay exactly the same.
+
+### Migrating from SendGrid / Mailgun
+
+Same pattern -- swap the gem and the delivery config. No changes to mailers.
+
+---
+
 ## Transactional Email
 
 Send one-off emails triggered by application events. Transactional emails bypass unsubscribe status (for password resets, receipts, order confirmations, etc.).
 
-The sender address is configured at the channel level in your Broadcast instance — there is no `from` parameter.
+The sender address is configured at the channel level in your Broadcast instance -- there is no `from` parameter.
+
+**Required permissions:** `transactionals_read`, `transactionals_write`
 
 ```ruby
 # Send an email
@@ -86,6 +188,8 @@ email['queue_at']   # => '2026-03-17T07:59:58Z'
 
 Manage your contact list. Subscribers can have tags and custom data fields for segmentation and personalization.
 
+**Required permissions:** `subscribers_read`, `subscribers_write`
+
 ```ruby
 # List subscribers (paginated, 250 per page)
 result = client.subscribers.list(page: 1)
@@ -154,7 +258,7 @@ client.subscribers.unsubscribe('jane@example.com')
 # Resubscribe (clears unsubscribed status AND activates)
 client.subscribers.resubscribe('jane@example.com')
 
-# Redact — GDPR "right to be forgotten" (irreversible)
+# Redact -- GDPR "right to be forgotten" (irreversible)
 # Removes PII but preserves aggregate campaign statistics
 client.subscribers.redact('jane@example.com')
 ```
@@ -165,6 +269,8 @@ client.subscribers.redact('jane@example.com')
 
 Automated drip campaigns. Add subscribers to a sequence and they flow through the steps automatically.
 
+**Required permissions:** `sequences_read`, `sequences_write` (also `subscribers_read`, `subscribers_write` for enrollment)
+
 ```ruby
 # List all sequences
 result = client.sequences.list
@@ -230,7 +336,7 @@ client.sequences.list_steps(sequence_id)
 # Get a single step
 step = client.sequences.get_step(sequence_id, step_id)
 
-# Create steps — each step needs an action, label, and parent_id
+# Create steps -- each step needs an action, label, and parent_id
 # The parent_id links steps into a tree (entry point is the sequence's root step)
 
 # Delay step (seconds)
@@ -279,6 +385,8 @@ client.sequences.delete_step(sequence_id, step_id)
 
 One-time email campaigns sent to your subscriber list or targeted segments.
 
+**Required permissions:** `broadcasts_read`, `broadcasts_write`
+
 ```ruby
 # List broadcasts
 result = client.broadcasts.list(limit: 10, offset: 0)
@@ -350,6 +458,8 @@ client.broadcasts.statistics_links(1, sort: 'clicks', order: 'desc')
 
 Define subscriber groups using rules for targeted broadcasts and sequence enrollment.
 
+**Required permissions:** `segments_read`, `segments_write`
+
 ```ruby
 # List segments
 result = client.segments.list
@@ -401,6 +511,8 @@ client.segments.delete(1)
 
 Reusable email templates with [Liquid](https://shopify.github.io/liquid/) variable support for personalization (e.g. `{{first_name}}`, `{{email}}`).
 
+**Required permissions:** `templates_read`, `templates_write`
+
 ```ruby
 # List all templates
 result = client.templates.list
@@ -435,6 +547,8 @@ client.templates.delete(1)
 
 Receive real-time notifications when events occur (email delivered, subscriber created, sequence completed, etc.).
 
+**Required permissions:** `webhook_endpoints_read`, `webhook_endpoints_write`
+
 ```ruby
 # List endpoints
 result = client.webhook_endpoints.list
@@ -453,10 +567,10 @@ result = client.webhook_endpoints.create(
   ],
   retries_to_attempt: 6
 )
-# IMPORTANT: Save the secret from the response — it is only shown once
+# IMPORTANT: Save the secret from the response -- it is only shown once
 secret = result['secret']
 
-# Update (url and secret cannot be changed — create a new endpoint instead)
+# Update (url and secret cannot be changed -- create a new endpoint instead)
 client.webhook_endpoints.update(1, active: false)
 client.webhook_endpoints.update(1, event_types: ['email.delivered', 'email.opened'])
 
@@ -483,16 +597,35 @@ result['data']  # => [{'id' => 1, 'event_type' => 'email.sent', 'response_status
 
 ### Webhook Signature Verification
 
-All incoming webhooks are signed with HMAC-SHA256. Verify them in your controller:
+All incoming webhooks are signed with HMAC-SHA256. Here's a complete Rails controller:
 
 ```ruby
-Broadcast::Webhook.verify(
-  request.raw_post,                                    # raw request body
-  request.headers['broadcast-webhook-signature'],      # v1,<base64 signature>
-  request.headers['broadcast-webhook-timestamp'],      # unix timestamp
-  secret: ENV['BROADCAST_WEBHOOK_SECRET']
-)
-# => true or false
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    payload = request.raw_post
+    signature = request.headers['broadcast-webhook-signature']
+    timestamp = request.headers['broadcast-webhook-timestamp']
+
+    unless Broadcast::Webhook.verify(payload, signature, timestamp,
+                                     secret: ENV['BROADCAST_WEBHOOK_SECRET'])
+      head :unauthorized
+      return
+    end
+
+    event = JSON.parse(payload)
+
+    case event['type']
+    when 'email.delivered'
+      # handle delivery
+    when 'subscriber.unsubscribed'
+      # handle unsubscribe
+    end
+
+    head :ok
+  end
+end
 ```
 
 The signature is computed as `HMAC-SHA256(timestamp + "." + payload, secret)`. Timestamps older than 5 minutes are rejected to prevent replay attacks.
@@ -501,21 +634,74 @@ The signature is computed as `HMAC-SHA256(timestamp + "." + payload, secret)`. T
 
 ## Error Handling
 
-All API errors inherit from `Broadcast::Error`:
+All API errors inherit from `Broadcast::Error`. Put specific errors before general ones:
 
 ```ruby
 begin
   client.send_email(to: 'user@example.com', subject: 'Hi', body: 'Hello')
-rescue Broadcast::AuthenticationError  # 401 — invalid or expired API token
-rescue Broadcast::NotFoundError        # 404 — resource does not exist
-rescue Broadcast::ValidationError      # 422 — missing or invalid parameters
-rescue Broadcast::RateLimitError       # 429 — exceeded 120 requests/minute
+rescue Broadcast::AuthenticationError  # 401 -- invalid or expired API token
+rescue Broadcast::NotFoundError        # 404 -- resource does not exist
+rescue Broadcast::ValidationError      # 422 -- missing or invalid parameters
+rescue Broadcast::RateLimitError       # 429 -- exceeded 120 requests/minute
 rescue Broadcast::TimeoutError         # connection or read timeout
 rescue Broadcast::APIError             # 5xx or unexpected status codes
+rescue Broadcast::DeliveryError        # ActionMailer wrapper (wraps any of the above)
 end
 ```
 
-Server errors (5xx) and timeouts are automatically retried with linear backoff. Client errors (401, 404, 422, 429) are raised immediately.
+Server errors (5xx) and timeouts are automatically retried with linear backoff. Client errors (401, 404, 422, 429) are raised immediately. `DeliveryError` is only raised from the ActionMailer delivery method -- it wraps the underlying API error.
+
+---
+
+## API Token Permissions
+
+Each token can be scoped to specific resources. The ActionMailer delivery method only needs transactional permissions. Use the minimum permissions your integration requires.
+
+| Resource | Read permission | Write permission |
+|----------|----------------|------------------|
+| Transactional Emails | `transactionals_read` -- get delivery status | `transactionals_write` -- send emails |
+| Subscribers | `subscribers_read` -- list, find | `subscribers_write` -- create, update, tag, deactivate, unsubscribe, redact |
+| Sequences | `sequences_read` -- list, get, list steps | `sequences_write` -- create, update, delete, manage steps, enroll subscribers |
+| 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 |
+| Webhook Endpoints | `webhook_endpoints_read` -- list, get, deliveries | `webhook_endpoints_write` -- create, update, delete, test |
+
+---
+
+## Troubleshooting
+
+### `Broadcast::AuthenticationError` (401)
+
+- **Wrong token:** Double-check you copied the full token from your Broadcast dashboard.
+- **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::ValidationError` (422)
+
+- **Missing required fields:** Check the parameters table for the method you're calling.
+- **Duplicate subscriber:** Creating a subscriber with an email that already exists returns 422. Use `find` first or handle the error.
+- **Duplicate template label:** Template labels must be unique within a channel.
+
+### `Broadcast::NotFoundError` (404)
+
+- **Wrong ID:** The resource ID doesn't exist or belongs to a different channel.
+- **Subscriber not found:** `subscribers.find(email: '...')` raises 404 if no subscriber matches.
+
+### `Broadcast::TimeoutError`
+
+- **Slow network:** Increase `timeout` and `open_timeout` in client options.
+- **Large response:** Template list responses can be large if templates contain full HTML bodies.
+
+### `Broadcast::RateLimitError` (429)
+
+- **Rate limit:** Broadcast allows 120 requests per minute per token. The gem does not auto-retry on 429 -- back off and retry in your application code.
+
+### ActionMailer emails not sending
+
+- **Check delivery method:** Ensure `config.action_mailer.delivery_method = :broadcast` is set in the right environment file (not development or test).
+- **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.
 
 ## License
 

data/lib/broadcast/delivery_method.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Broadcast
+  class DeliveryMethod
+    def initialize(settings = {})
+      @client = Client.new(**settings)
+    end
+
+    def deliver!(mail)
+      @client.send_email(
+        to: mail.to&.first,
+        subject: mail.subject,
+        body: extract_body(mail),
+        reply_to: mail.reply_to&.first
+      )
+    rescue Broadcast::Error => e
+      raise DeliveryError, "Failed to deliver email: #{e.message}"
+    end
+
+    private
+
+    def extract_body(mail)
+      if mail.html_part
+        mail.html_part.body.to_s
+      elsif mail.text_part
+        mail.text_part.body.to_s
+      else
+        mail.body.to_s
+      end
+    end
+  end
+end

data/lib/broadcast/errors.rb

@@ -16,4 +16,6 @@ module Broadcast
   class ValidationError < Error; end
 
   class TimeoutError < Error; end
+
+  class DeliveryError < Error; end
 end

data/lib/broadcast/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'delivery_method'
+
+module Broadcast
+  class Railtie < Rails::Railtie
+    initializer 'broadcast.add_delivery_method' do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.add_delivery_method :broadcast, Broadcast::DeliveryMethod
+      end
+    end
+  end
+end

data/lib/broadcast/version.rb

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

data/lib/broadcast.rb

@@ -13,5 +13,11 @@ require_relative 'broadcast/resources/segments'
 require_relative 'broadcast/resources/templates'
 require_relative 'broadcast/resources/webhook_endpoints'
 
+# ActionMailer integration — only loaded when Rails is present
+if defined?(Rails::Railtie)
+  require_relative 'broadcast/delivery_method'
+  require_relative 'broadcast/railtie'
+end
+
 module Broadcast
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: broadcast-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Simon Chiu
@@ -40,7 +40,9 @@ files:
 - lib/broadcast.rb
 - lib/broadcast/client.rb
 - lib/broadcast/configuration.rb
+- lib/broadcast/delivery_method.rb
 - lib/broadcast/errors.rb
+- lib/broadcast/railtie.rb
 - lib/broadcast/resources/base.rb
 - lib/broadcast/resources/broadcasts.rb
 - lib/broadcast/resources/segments.rb