sendara 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4dc1a93353c4f74c9858a5c0456819cf09d8822bfc2d85e52380310800ab361
-  data.tar.gz: 01b26945825759c360b80e0fa82be866b76daeb75632a2aae4800b79eb7024a4
+  metadata.gz: 93eb9f0dc2bd668914efca68d65e72f614c23ea0d194f376a77aac5ed7327520
+  data.tar.gz: 826da708e6ea0519d6f48827315465261c39382d613008a31f5797f9d6e7d2c4
 SHA512:
-  metadata.gz: d2ff26bc76b493d4f12dabfeba8aecf5bee14192bc2bae40fc31ba7e85f6c4116b89b1d5293912869f8278588c3729e7ceecbc6e431bb7b5ef4793a835059b93
-  data.tar.gz: 1792963bb32043679409cc010483e1fb7a0cb9fa9af8019656cce503370ec1b8e6b8130dc47ed7d27f99c1b3c91d1d45026d6281fa9bb630a1742f3c93759f55
+  metadata.gz: c117085ea0d5d9d82f4da39ca466080e04253b1c1ac2c25584b5841fa61951129c5f4d104f95586443b05592a26e3fe53e05cb040f5993a0559042b635342623
+  data.tar.gz: f8c4394b30342443ba05adf6505e03e8b42014561795319bf156f6e7243c3252ac59d34a4ef63ec384ed9ed775a49b932f6c1fe0b8df8dfd6d753b1f02d7ef4b

data/README.md

@@ -1,6 +1,6 @@
 # Sendara Ruby
 
-Email-first Ruby client for the [Sendara](https://sendara.dev) API: transactional email, broadcasts, contacts, templates, domains, and signed webhooks. Pure stdlib HTTP, zero runtime dependencies.
+Email-first Ruby client for the [Sendara](https://sendara.dev) API: transactional email, broadcasts, contacts, templates, domains, and signed webhooks. It uses Ruby's standard HTTP stack and declares the `base64` default gem for Ruby 3.4+ compatibility.
 
 Requires Ruby >= 3.0.
 
@@ -55,7 +55,7 @@ The client automatically attaches an `Idempotency-Key` to every write and retrie
 
 ### Sending email
 
-`emails.send` is keyword-based. `from`, `to`, and `subject` are the essentials; provide `html`, `text`, or both:
+`emails.send` is keyword-based. `to` is always required; `from` is required after domain verification, and inline sends need a subject plus `html`, `text`, or both. Stored templates can provide their own content:
 
 ```ruby
 client.emails.send(
@@ -65,7 +65,9 @@ client.emails.send(
   html: "<p>Thanks for your order.</p>",
   text: "Thanks for your order.",
   message_type: "transactional",
-  metadata: { "order_id" => "ord_123" }
+  metadata: { "order_id" => "ord_123" },
+  scheduled_at: "2027-01-15T09:00:00Z",
+  validate_recipient: true
 )
 ```
 
@@ -122,6 +124,19 @@ broadcast = client.broadcasts.create(
 client.broadcasts.send(broadcast["id"])
 ```
 
+Pass `list_ids:` to send to several contact lists at once, and `exclude_list_ids:`
+to subtract a list from that audience:
+
+```ruby
+client.broadcasts.create(
+  from_email: "you@yourdomain.com",
+  subject: "What's new in June",
+  body_html: "<h1>June</h1>",
+  list_ids: %w[list_123 list_456],
+  exclude_list_ids: %w[list_789]
+)
+```
+
 Schedule for later, or send immediately on create with `send_now: true`:
 
 ```ruby
@@ -130,8 +145,8 @@ client.broadcasts.create(
   name: "Launch",
   subject: "We're live",
   body_html: "<p>We launched.</p>",
-  recipients: ["a@example.com", "b@example.com"],
-  scheduled_at: "2026-07-01T09:00:00Z"
+  recipients: [{ "email" => "a@example.com" }, { "email" => "b@example.com" }],
+  scheduled_at: "2027-01-15T09:00:00Z"
 )
 ```
 
@@ -144,24 +159,25 @@ client.broadcasts.cancel("bcast_123")
 client.broadcasts.delete("bcast_123")
 ```
 
-To create-and-send an audience in a single request, use `bulk_send` (same arguments as `create`):
+To create and immediately send an audience in one request, use `bulk_send`.
+It accepts the same content and audience arguments as `create`, but not
+`scheduled_at` or `send_now` because this endpoint always fans out immediately:
 
 ```ruby
 client.broadcasts.bulk_send(
   from_email: "you@yourdomain.com",
   subject: "Flash sale",
   body_html: "<p>24 hours only.</p>",
-  audience_list_id: "list_123",
-  send_now: true
+  audience_list_id: "list_123"
 )
 ```
 
 ## Messages & pagination
 
-Fetch a single page with `messages.page`, which returns a `Sendara::MessagePage`:
+Fetch a single page with `messages.page` (aliased as `messages.list`), which returns a `Sendara::MessagePage`:
 
 ```ruby
-page = client.messages.page(status: "delivered", limit: 50)
+page = client.messages.list(status: "delivered", limit: 50)
 
 page.messages.each { |message| puts message["id"] }
 page.has_more?   # => true / false
@@ -182,10 +198,27 @@ Called without a block it returns an `Enumerator`, so the full `Enumerable` API
 recent = client.messages.each(channel: "email", limit: 100).first(10)
 ```
 
-Filters: `channel`, `status`, `from`, `to`, `limit`, `cursor`. Fetch one message by id:
+Filters: `channel`, `status`, `search`, `from`, `to`, `limit`, `cursor`. Fetch one message with its full event timeline, by id or by the idempotency key from the original send:
 
 ```ruby
 client.messages.get("msg_123")
+client.messages.get(idempotency_key: "order-42")
+```
+
+## Billing checkout
+
+Checkout accepts `starter`, `pro`, `growth`, or `scale`, with a `month` or
+`year` billing period. It returns a `Sendara::CheckoutResult` for a new hosted
+checkout or an in-place subscription change:
+
+```ruby
+checkout = client.billing.checkout(plan: :growth, period: :year)
+
+if checkout.updated?
+  puts "Subscription changed to #{checkout.plan}"
+else
+  redirect_to checkout.url
+end
 ```
 
 ## Webhook verification
@@ -201,7 +234,7 @@ event = Sendara::Webhooks.verify(
   ENV.fetch("SENDARA_WEBHOOK_SECRET")
 )
 
-event["type"] # => "email.delivered"
+event["event_type"] # => "delivered"
 ```
 
 `verify` checks the `Sendara-Signature` HMAC and rejects requests whose `Sendara-Timestamp` is outside the tolerance window (default 300 seconds). Adjust it if needed:
@@ -296,9 +329,9 @@ class SendaraWebhooksController < ActionController::API
       Rails.application.credentials.sendara_webhook_secret
     )
 
-    case event["type"]
-    when "email.delivered" then handle_delivered(event)
-    when "email.bounced"   then handle_bounced(event)
+    case event["event_type"]
+    when "delivered" then handle_delivered(event)
+    when "bounced"   then handle_bounced(event)
     end
 
     head :ok

data/lib/sendara/checkout_result.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Sendara
+  # Result of POST /v1/billing/checkout. A new subscription has a URL to
+  # redirect to; an existing subscription reports the plan changed in place.
+  class CheckoutResult
+    PLANS = %w[starter pro growth scale].freeze
+
+    attr_reader :url, :plan
+
+    def self.from_response(response)
+      url = response["url"]
+      return new(url: url, updated: false) if url.is_a?(String) && !url.empty?
+
+      plan = response["plan"]
+      if response["updated"] == true && PLANS.include?(plan)
+        return new(updated: true, plan: plan)
+      end
+
+      raise Error, "Billing checkout returned neither a checkout URL nor an updated plan"
+    end
+
+    def initialize(url: nil, updated:, plan: nil)
+      @url = url
+      @updated = updated
+      @plan = plan
+      freeze
+    end
+
+    def updated?
+      @updated
+    end
+
+    def redirect?
+      !@url.nil?
+    end
+  end
+end

data/lib/sendara/client.rb

@@ -36,7 +36,8 @@ module Sendara
 
       headers = {
         "Authorization" => "Bearer #{@api_key}",
-        "Accept" => "application/json"
+        "Accept" => "application/json",
+        "User-Agent" => "sendara-ruby/#{VERSION}"
       }
 
       raw_body = nil

data/lib/sendara/resources/billing.rb

@@ -3,14 +3,22 @@
 module Sendara
   module Resources
     class Billing < Resource
+      PLANS = %w[starter pro growth scale].freeze
+      PERIODS = %w[month year].freeze
+
       def get
         request(:get, "/v1/billing") || {}
       end
 
       def checkout(plan: nil, period: nil)
+        plan = plan.to_s unless plan.nil?
+        period = period.to_s unless period.nil?
+        raise ArgumentError, "plan must be starter, pro, growth, or scale" if plan && !PLANS.include?(plan)
+        raise ArgumentError, "period must be month or year" if period && !PERIODS.include?(period)
+
         body = compact_params("plan" => plan, "period" => period)
         response = request(:post, "/v1/billing/checkout", body: body) || {}
-        response["url"].to_s
+        CheckoutResult.from_response(response)
       end
 
       def portal

data/lib/sendara/resources/broadcasts.rb

@@ -16,11 +16,13 @@ module Sendara
 
       def create(from_email:, name: nil, subject: nil, body_html: nil, body_text: nil,
                  template_id: nil, message_type: nil, audience_list_id: nil,
+                 list_ids: nil, exclude_list_ids: nil,
                  recipients: nil, scheduled_at: nil, send_now: nil)
         request(:post, "/v1/broadcasts", body: broadcast_body(
           from_email: from_email, name: name, subject: subject, body_html: body_html,
           body_text: body_text, template_id: template_id, message_type: message_type,
-          audience_list_id: audience_list_id, recipients: recipients,
+          audience_list_id: audience_list_id, list_ids: list_ids,
+          exclude_list_ids: exclude_list_ids, recipients: recipients,
           scheduled_at: scheduled_at, send_now: send_now
         )) || {}
       end
@@ -40,19 +42,21 @@ module Sendara
 
       def bulk_send(from_email:, name: nil, subject: nil, body_html: nil, body_text: nil,
                     template_id: nil, message_type: nil, audience_list_id: nil,
-                    recipients: nil, scheduled_at: nil, send_now: nil)
+                    list_ids: nil, exclude_list_ids: nil, recipients: nil)
         request(:post, "/v1/send/bulk", body: broadcast_body(
           from_email: from_email, name: name, subject: subject, body_html: body_html,
           body_text: body_text, template_id: template_id, message_type: message_type,
-          audience_list_id: audience_list_id, recipients: recipients,
-          scheduled_at: scheduled_at, send_now: send_now
+          audience_list_id: audience_list_id, list_ids: list_ids,
+          exclude_list_ids: exclude_list_ids, recipients: recipients,
+          scheduled_at: nil, send_now: nil
         )) || {}
       end
 
       private
 
       def broadcast_body(from_email:, name:, subject:, body_html:, body_text:, template_id:,
-                         message_type:, audience_list_id:, recipients:, scheduled_at:, send_now:)
+                         message_type:, audience_list_id:, list_ids:, exclude_list_ids:,
+                         recipients:, scheduled_at:, send_now:)
         compact_params(
           "name" => name,
           "from_email" => from_email,
@@ -62,6 +66,8 @@ module Sendara
           "template_id" => template_id,
           "message_type" => message_type,
           "audience_list_id" => audience_list_id,
+          "list_ids" => list_ids,
+          "exclude_list_ids" => exclude_list_ids,
           "recipients" => recipients,
           "scheduled_at" => scheduled_at,
           "send_now" => send_now

data/lib/sendara/resources/emails.rb

@@ -5,27 +5,37 @@ module Sendara
     class Emails < Resource
       def send(to:, from: nil, subject: nil, html: nil, text: nil, message_type: nil,
                template_id: nil, template_vars: nil, metadata: nil, store_payload: nil,
-               test_send: nil, idempotency_key: nil)
+               test_send: nil, scheduled_at: nil, validate_recipient: nil, idempotency_key: nil)
+        raise ArgumentError, "to is required" if to.nil? || to.to_s.empty?
+
         meta = metadata.nil? ? {} : metadata.dup
         meta["from_email"] = from unless from.nil?
 
         body = {
           "channel" => "email",
           "idempotency_key" => idempotency_key || Client.generate_idempotency_key,
-          "destination" => { "email" => to },
-          "payload" => {
-            "subject" => subject,
-            "body_html" => html,
-            "body_text" => text
-          },
-          "metadata" => meta
+          "destination" => { "email" => to }
         }
+        body["metadata"] = meta unless meta.empty?
+
+        # Only the fields the caller supplied go on the wire, and "payload" is
+        # dropped outright when none were: a template-only send would otherwise
+        # ship nulls the server discards when it renders the template over them.
+        # Shared by all five SDKs.
+        payload = compact_params(
+          "subject" => subject,
+          "body_html" => html,
+          "body_text" => text
+        ).reject { |_key, value| value.to_s.empty? }
+        body["payload"] = payload unless payload.empty?
 
         body["message_type"] = message_type unless message_type.nil?
         body["template_id"] = template_id unless template_id.nil?
         body["template_vars"] = template_vars unless template_vars.nil?
         body["store_payload"] = store_payload unless store_payload.nil?
         body["test_send"] = test_send unless test_send.nil?
+        body["scheduled_at"] = scheduled_at unless scheduled_at.nil?
+        body["validate_recipient"] = validate_recipient unless validate_recipient.nil?
 
         send_raw(body)
       end

data/lib/sendara/resources/messages.rb

@@ -5,10 +5,11 @@ module Sendara
     class Messages < Resource
       include Enumerable
 
-      def page(channel: nil, status: nil, from: nil, to: nil, limit: nil, cursor: nil)
+      def page(channel: nil, status: nil, search: nil, from: nil, to: nil, limit: nil, cursor: nil)
         query = compact_params(
           "channel" => channel,
           "status" => status,
+          "search" => search,
           "from" => from,
           "to" => to,
           "limit" => limit,
@@ -18,15 +19,17 @@ module Sendara
         MessagePage.from_response(response)
       end
 
-      def each(channel: nil, status: nil, from: nil, to: nil, limit: nil, cursor: nil, &block)
+      alias list page
+
+      def each(channel: nil, status: nil, search: nil, from: nil, to: nil, limit: nil, cursor: nil, &block)
         unless block_given?
-          return enum_for(:each, channel: channel, status: status, from: from,
-                                  to: to, limit: limit, cursor: cursor)
+          return enum_for(:each, channel: channel, status: status, search: search,
+                                  from: from, to: to, limit: limit, cursor: cursor)
         end
 
         loop do
-          current = page(channel: channel, status: status, from: from,
-                         to: to, limit: limit, cursor: cursor)
+          current = page(channel: channel, status: status, search: search,
+                         from: from, to: to, limit: limit, cursor: cursor)
           current.messages.each(&block)
           break if current.next_cursor.nil?
 
@@ -34,7 +37,13 @@ module Sendara
         end
       end
 
-      def get(id)
+      def get(id = nil, idempotency_key: nil)
+        if idempotency_key
+          return request(:get, "/v1/messages", query: { "idempotency_key" => idempotency_key }) || {}
+        end
+
+        raise ArgumentError, "get requires an id or idempotency_key" if id.nil?
+
         request(:get, "/v1/messages/#{encode(id)}") || {}
       end
     end

data/lib/sendara/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sendara
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/sendara.rb

@@ -3,6 +3,7 @@
 require_relative "sendara/version"
 require_relative "sendara/errors"
 require_relative "sendara/message_page"
+require_relative "sendara/checkout_result"
 require_relative "sendara/resource"
 require_relative "sendara/resources/emails"
 require_relative "sendara/resources/broadcasts"

data/sendara.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Sendara — email & marketing API client for Ruby."
   spec.description = "Email-first Ruby client for the Sendara API: transactional email, " \
                      "broadcasts, contacts, templates, domains, and signed webhooks. " \
-                     "Pure stdlib HTTP, zero runtime dependencies."
+                     "Pure stdlib HTTP with the Ruby base64 default gem."
   spec.homepage = "https://sendara.dev"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.0"
@@ -26,5 +26,6 @@ Gem::Specification.new do |spec|
   spec.files = Dir.glob("lib/**/*.rb") + %w[README.md LICENSE sendara.gemspec].select { |f| File.exist?(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "base64", ">= 0.1"
   spec.add_development_dependency "rspec", "~> 3"
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: sendara
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sendara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -25,8 +39,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3'
 description: 'Email-first Ruby client for the Sendara API: transactional email, broadcasts,
-  contacts, templates, domains, and signed webhooks. Pure stdlib HTTP, zero runtime
-  dependencies.'
+  contacts, templates, domains, and signed webhooks. Pure stdlib HTTP with the Ruby
+  base64 default gem.'
 email:
 - support@sendara.dev
 executables: []
@@ -35,6 +49,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/sendara.rb
+- lib/sendara/checkout_result.rb
 - lib/sendara/client.rb
 - lib/sendara/errors.rb
 - lib/sendara/generators/install_generator.rb