sendly 3.26.0 → 3.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6daab4e1812cb359de80d59229c8895c8b4542abd2b6d6fbbaafe2b495bef9a
-  data.tar.gz: f200cbebe0bd5bc5ed70b23c691f6061fa98790aee74c4d1f84487d52540e1ba
+  metadata.gz: c41be641303c996be30a1408b25aa49607676c0b6a8511ced4a5275e439602d9
+  data.tar.gz: 6228171a120073a65d7fe6b52500906785022d4c2d185e2b678b28a2ffc7e9b3
 SHA512:
-  metadata.gz: f2dd68745cee4033698c2f0bcf13da03fc08b47956b35c700920afa3b75dd53d133ccd0b5c46796bf117298f2848f67ab088393fd3ca82563278034e050ebdc0
-  data.tar.gz: 385b82af9aa6d59fdca06faa84b87f77bf3822d57a177a41b1c8f18bfc00402f53e97c5c9067f9a8921cab1752bb3648a99cef43a31317ab2e9ef28c653d139a
+  metadata.gz: 7c9239c487bf91a790e2b639a724d2fea57b15032524ab4738de185604ca242100416ec43096f7308f820b42ae0eb8134121f597a12052b4fb232e6b5e325b6d
+  data.tar.gz: 80ef1fc95098ab7a4ca6bff2afe4e08d82007bae9979a49ce59e4f0fb222ab6353958fd2a7e561cbd4d37323cbafc2781cfab72064633e12da4f967f3f65d163

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # sendly (Ruby)
 
+## 3.29.0
+
+### Minor Changes
+
+- `contacts.bulk_mark_valid(ids: ..., list_id: ...)`: clear the invalid flag on many contacts at once (up to 10,000 per call). Escape hatch for when auto-mark misclassifies at scale.
+- Four new list-health webhook event constants in `Sendly::Webhooks`: `EVENT_CONTACT_AUTO_FLAGGED`, `EVENT_CONTACT_MARKED_VALID`, `EVENT_CONTACTS_LOOKUP_COMPLETED`, `EVENT_CONTACTS_BULK_MARKED_VALID`.
+- New `Sendly::Webhooks::ListHealthEventSource` module with frozen constants (`SEND_FAILURE | CARRIER_LOOKUP | USER_ACTION | BULK_MARK_VALID`) for the `source` field on auto-flag and mark-valid webhooks.
+- `Contact` gains `user_marked_valid_at` — when a user manually cleared an auto-flag. Carrier re-checks respect this timestamp and leave the contact clean.
+
+## 3.28.0
+
+### Minor Changes
+
+- `contacts.mark_valid(id)`: clear the auto-exclusion flag on a contact.
+- `contacts.check_numbers(list_id: nil, force: false)`: trigger a background carrier lookup.
+- `Contact` gains `line_type`, `carrier_name`, `line_type_checked_at`, `invalid_reason`, `invalidated_at` plus `invalid?` helper.
+
 ## 3.18.1
 
 ### Patch Changes

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    sendly (3.26.0)
+    sendly (3.29.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.9)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     bigdecimal (3.3.1)

data/lib/sendly/client.rb

@@ -121,6 +121,13 @@ module Sendly
       @drafts ||= DraftsResource.new(self)
     end
 
+    # Access the Rules resource
+    #
+    # @return [Sendly::RulesResource]
+    def rules
+      @rules ||= RulesResource.new(self)
+    end
+
     # Access the Enterprise resource
     #
     # @return [Sendly::EnterpriseResource]

data/lib/sendly/contacts_resource.rb

@@ -3,6 +3,8 @@
 module Sendly
   class Contact
     attr_reader :id, :phone_number, :name, :email, :metadata, :opted_out,
+                :line_type, :carrier_name, :line_type_checked_at,
+                :invalid_reason, :invalidated_at, :user_marked_valid_at,
                 :created_at, :updated_at, :lists
 
     def initialize(data)
@@ -12,6 +14,12 @@ module Sendly
       @email = data["email"]
       @metadata = data["metadata"] || {}
       @opted_out = data["opted_out"] || data["optedOut"] || false
+      @line_type = data["line_type"] || data["lineType"]
+      @carrier_name = data["carrier_name"] || data["carrierName"]
+      @line_type_checked_at = parse_time(data["line_type_checked_at"] || data["lineTypeCheckedAt"])
+      @invalid_reason = data["invalid_reason"] || data["invalidReason"]
+      @invalidated_at = parse_time(data["invalidated_at"] || data["invalidatedAt"])
+      @user_marked_valid_at = parse_time(data["user_marked_valid_at"] || data["userMarkedValidAt"])
       @created_at = parse_time(data["created_at"] || data["createdAt"])
       @updated_at = parse_time(data["updated_at"] || data["updatedAt"])
       @lists = data["lists"]&.map { |l| { id: l["id"], name: l["name"] } }
@@ -21,10 +29,19 @@ module Sendly
       opted_out
     end
 
+    def invalid?
+      !invalid_reason.nil?
+    end
+
     def to_h
       {
         id: id, phone_number: phone_number, name: name, email: email,
         metadata: metadata, opted_out: opted_out,
+        line_type: line_type, carrier_name: carrier_name,
+        line_type_checked_at: line_type_checked_at&.iso8601,
+        invalid_reason: invalid_reason,
+        invalidated_at: invalidated_at&.iso8601,
+        user_marked_valid_at: user_marked_valid_at&.iso8601,
         created_at: created_at&.iso8601, updated_at: updated_at&.iso8601,
         lists: lists
       }.compact
@@ -186,6 +203,45 @@ module Sendly
       @client.delete("/contacts/#{id}")
     end
 
+    # Clear the invalid flag on a contact so future campaigns include it again.
+    # Contacts get auto-flagged when a send fails with a terminal bad-number
+    # error (landline, invalid number) or when a carrier lookup reports they
+    # can't receive SMS.
+    def mark_valid(id)
+      response = @client.post("/contacts/#{id}/mark-valid", {})
+      Contact.new(response)
+    end
+
+    # Clear the invalid flag on many contacts at once — the escape hatch for
+    # when auto-flag misclassifies at scale. Pass either an explicit id array
+    # (up to 10,000 per call) OR a list_id, not both. Foreign ids silently
+    # no-op via the per-organization filter.
+    #
+    # @param ids [Array<String>, nil] Explicit contact ids to clear
+    # @param list_id [String, nil] Clear every flagged member of this list
+    # @return [Hash] `{ cleared: Integer }` — number of contacts whose flag was
+    #   actually cleared. Already-clean contacts and foreign ids don't count.
+    def bulk_mark_valid(ids: nil, list_id: nil)
+      if ids.nil? && list_id.nil?
+        raise ArgumentError, "bulk_mark_valid requires either :ids or :list_id"
+      end
+      if ids && list_id
+        raise ArgumentError, "bulk_mark_valid accepts :ids OR :list_id, not both"
+      end
+
+      body = ids ? { ids: ids } : { listId: list_id }
+      response = @client.post("/contacts/bulk-mark-valid", body)
+      { cleared: response["cleared"] || 0 }
+    end
+
+    # Trigger a background carrier lookup across your contacts. Landlines
+    # and other non-SMS-capable numbers are auto-excluded from future
+    # campaigns. The lookup runs asynchronously (1-5 minutes).
+    # Options: list_id (scope to a single list), force (re-check already-looked-up)
+    def check_numbers(list_id: nil, force: false)
+      @client.post("/contacts/lookup", { listId: list_id, force: force })
+    end
+
     def import_contacts(contacts, list_id: nil, opted_in_at: nil)
       body = {
         contacts: contacts.map { |c|

data/lib/sendly/conversations_resource.rb

@@ -96,6 +96,17 @@ module Sendly
       @client.delete("/conversations/#{encoded_id}/labels/#{encoded_label_id}")
     end
 
+    def get_context(id, max_messages: nil)
+      raise ValidationError, "Conversation ID is required" if id.nil? || id.empty?
+
+      params = {}
+      params[:max_messages] = max_messages if max_messages
+
+      encoded_id = URI.encode_www_form_component(id)
+      response = @client.get("/conversations/#{encoded_id}/context", params.compact)
+      ConversationContext.new(response)
+    end
+
     def each(status: nil, batch_size: 100, &block)
       return enum_for(:each, status: status, batch_size: batch_size) unless block_given?
 

data/lib/sendly/rules_resource.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Sendly
+  class RulesResource
+    def initialize(client)
+      @client = client
+    end
+
+    def list
+      response = @client.get("/rules")
+      (response["data"] || []).map { |r| Rule.new(r) }
+    end
+
+    def create(name:, conditions:, actions:, priority: nil)
+      body = { name: name, conditions: conditions, actions: actions }
+      body[:priority] = priority if priority
+
+      response = @client.post("/rules", body)
+      Rule.new(response)
+    end
+
+    def update(id, name: nil, conditions: nil, actions: nil, priority: nil)
+      raise ValidationError, "Rule ID is required" if id.nil? || id.empty?
+
+      body = {}
+      body[:name] = name if name
+      body[:conditions] = conditions if conditions
+      body[:actions] = actions if actions
+      body[:priority] = priority if priority
+
+      response = @client.patch("/rules/#{URI.encode_www_form_component(id)}", body)
+      Rule.new(response)
+    end
+
+    def delete(id)
+      raise ValidationError, "Rule ID is required" if id.nil? || id.empty?
+
+      @client.delete("/rules/#{URI.encode_www_form_component(id)}")
+    end
+  end
+end

data/lib/sendly/templates_resource.rb

@@ -111,5 +111,12 @@ module Sendly
       response = @client.post("/templates/#{id}/clone", body)
       Template.new(response)
     end
+
+    def generate(description:, category: nil)
+      body = { description: description }
+      body[:category] = category if category
+      response = @client.post("/templates/generate", body)
+      GeneratedTemplate.new(response)
+    end
   end
 end

data/lib/sendly/types.rb

@@ -746,4 +746,96 @@ module Sendly
       end
     end
   end
+
+  # ============================================================================
+  # Conversation Context
+  # ============================================================================
+
+  class ConversationContext
+    attr_reader :context, :conversation, :token_estimate, :business
+
+    def initialize(data)
+      @context = data["context"]
+      @conversation = {
+        id: data.dig("conversation", "id"),
+        phone_number: data.dig("conversation", "phoneNumber") || data.dig("conversation", "phone_number"),
+        status: data.dig("conversation", "status"),
+        message_count: data.dig("conversation", "messageCount") || data.dig("conversation", "message_count") || 0,
+        unread_count: data.dig("conversation", "unreadCount") || data.dig("conversation", "unread_count") || 0
+      }
+      @token_estimate = data["tokenEstimate"] || data["token_estimate"] || 0
+      if data["business"]
+        @business = {
+          name: data.dig("business", "name"),
+          use_case: data.dig("business", "useCase") || data.dig("business", "use_case")
+        }
+      end
+    end
+
+    def to_h
+      result = {
+        context: context,
+        conversation: conversation,
+        token_estimate: token_estimate
+      }
+      result[:business] = business if business
+      result
+    end
+  end
+
+  # ============================================================================
+  # Rules
+  # ============================================================================
+
+  class Rule
+    attr_reader :id, :name, :conditions, :actions, :priority, :created_at, :updated_at
+
+    def initialize(data)
+      @id = data["id"]
+      @name = data["name"]
+      @conditions = data["conditions"] || {}
+      @actions = data["actions"] || {}
+      @priority = data["priority"]
+      @created_at = parse_time(data["createdAt"] || data["created_at"])
+      @updated_at = parse_time(data["updatedAt"] || data["updated_at"])
+    end
+
+    def to_h
+      {
+        id: id, name: name, conditions: conditions, actions: actions,
+        priority: priority, created_at: created_at&.iso8601,
+        updated_at: updated_at&.iso8601
+      }.compact
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+      Time.parse(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # ============================================================================
+  # Generated Template
+  # ============================================================================
+
+  class GeneratedTemplate
+    attr_reader :name, :text, :variables, :category
+
+    def initialize(data)
+      @name = data["name"]
+      @text = data["text"]
+      @variables = data["variables"] || []
+      @category = data["category"]
+    end
+
+    def to_h
+      {
+        name: name, text: text, variables: variables, category: category
+      }.compact
+    end
+  end
 end

data/lib/sendly/verify.rb

@@ -3,28 +3,25 @@
 module Sendly
   class Verification
     attr_reader :id, :status, :phone, :delivery_status, :attempts, :max_attempts,
-                :channel, :expires_at, :verified_at, :created_at, :sandbox,
-                :app_name, :template_id, :profile_id, :metadata
+                :expires_at, :verified_at, :created_at, :sandbox,
+                :app_name, :template_id, :profile_id
 
     STATUSES = %w[pending verified expired failed].freeze
-    CHANNELS = %w[sms whatsapp email].freeze
 
     def initialize(data)
       @id = data["id"]
       @status = data["status"]
       @phone = data["phone"]
-      @delivery_status = data["deliveryStatus"] || data["delivery_status"]
+      @delivery_status = data["delivery_status"]
       @attempts = data["attempts"] || 0
-      @max_attempts = data["maxAttempts"] || data["max_attempts"] || 3
-      @channel = data["channel"] || "sms"
-      @expires_at = parse_time(data["expiresAt"] || data["expires_at"])
-      @verified_at = parse_time(data["verifiedAt"] || data["verified_at"])
-      @created_at = parse_time(data["createdAt"] || data["created_at"])
+      @max_attempts = data["max_attempts"] || 3
+      @expires_at = parse_time(data["expires_at"])
+      @verified_at = parse_time(data["verified_at"])
+      @created_at = parse_time(data["created_at"])
       @sandbox = data["sandbox"] || false
-      @app_name = data["appName"] || data["app_name"]
-      @template_id = data["templateId"] || data["template_id"]
-      @profile_id = data["profileId"] || data["profile_id"]
-      @metadata = data["metadata"] || {}
+      @app_name = data["app_name"]
+      @template_id = data["template_id"]
+      @profile_id = data["profile_id"]
     end
 
     def pending?
@@ -46,10 +43,10 @@ module Sendly
     def to_h
       {
         id: id, status: status, phone: phone, delivery_status: delivery_status,
-        attempts: attempts, max_attempts: max_attempts, channel: channel,
+        attempts: attempts, max_attempts: max_attempts,
         expires_at: expires_at&.iso8601, verified_at: verified_at&.iso8601,
         created_at: created_at&.iso8601, sandbox: sandbox, app_name: app_name,
-        template_id: template_id, profile_id: profile_id, metadata: metadata
+        template_id: template_id, profile_id: profile_id
       }.compact
     end
 
@@ -64,25 +61,32 @@ module Sendly
   end
 
   class SendVerificationResponse
-    attr_reader :verification, :code
+    attr_reader :id, :status, :phone, :expires_at, :sandbox, :sandbox_code, :message
 
     def initialize(data)
-      @verification = Verification.new(data["verification"])
-      @code = data["code"]
+      @id = data["id"]
+      @status = data["status"]
+      @phone = data["phone"]
+      @expires_at = data["expires_at"]
+      @sandbox = data["sandbox"] || false
+      @sandbox_code = data["sandbox_code"]
+      @message = data["message"]
     end
   end
 
   class CheckVerificationResponse
-    attr_reader :valid, :status, :verification
+    attr_reader :id, :status, :phone, :verified_at, :remaining_attempts
 
     def initialize(data)
-      @valid = data["valid"]
+      @id = data["id"]
       @status = data["status"]
-      @verification = data["verification"] ? Verification.new(data["verification"]) : nil
+      @phone = data["phone"]
+      @verified_at = data["verified_at"]
+      @remaining_attempts = data["remaining_attempts"]
     end
 
-    def valid?
-      valid
+    def verified?
+      status == "verified"
     end
   end
 
@@ -163,18 +167,14 @@ module Sendly
       @sessions = SessionsResource.new(client)
     end
 
-    def send(phone:, channel: nil, code_length: nil, expires_in: nil, max_attempts: nil,
-             template_id: nil, profile_id: nil, app_name: nil, locale: nil, metadata: nil)
-      body = { to: phone }
-      body[:channel] = channel if channel
-      body[:codeLength] = code_length if code_length
-      body[:expiresIn] = expires_in if expires_in
-      body[:maxAttempts] = max_attempts if max_attempts
-      body[:templateId] = template_id if template_id
-      body[:profileId] = profile_id if profile_id
-      body[:appName] = app_name if app_name
-      body[:locale] = locale if locale
-      body[:metadata] = metadata if metadata
+    def send(to:, template_id: nil, profile_id: nil, app_name: nil,
+             timeout_secs: nil, code_length: nil)
+      body = { to: to }
+      body[:template_id] = template_id if template_id
+      body[:profile_id] = profile_id if profile_id
+      body[:app_name] = app_name if app_name
+      body[:timeout_secs] = timeout_secs if timeout_secs
+      body[:code_length] = code_length if code_length
 
       response = @client.post("/verify", body)
       SendVerificationResponse.new(response)
@@ -195,11 +195,10 @@ module Sendly
       Verification.new(response)
     end
 
-    def list(limit: nil, status: nil, phone: nil)
+    def list(limit: nil, status: nil)
       params = {}
       params[:limit] = limit if limit
       params[:status] = status if status
-      params[:phone] = phone if phone
 
       response = @client.get("/verify", params)
       verifications = (response["verifications"] || []).map { |v| Verification.new(v) }

data/lib/sendly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sendly
-  VERSION = "3.26.0"
+  VERSION = "3.29.0"
 end

data/lib/sendly/webhooks.rb

@@ -34,6 +34,40 @@ module Sendly
   module Webhooks
     SIGNATURE_TOLERANCE_SECONDS = 300
 
+    # Webhook event type string constants. Use these when subscribing
+    # instead of string literals so you catch typos at load time.
+    EVENT_MESSAGE_QUEUED                = "message.queued"
+    EVENT_MESSAGE_SENT                  = "message.sent"
+    EVENT_MESSAGE_DELIVERED             = "message.delivered"
+    EVENT_MESSAGE_FAILED                = "message.failed"
+    EVENT_MESSAGE_BOUNCED               = "message.bounced"
+    EVENT_MESSAGE_RETRYING              = "message.retrying"
+    EVENT_MESSAGE_RECEIVED              = "message.received"
+    EVENT_MESSAGE_OPT_OUT               = "message.opt_out"
+    EVENT_MESSAGE_OPT_IN                = "message.opt_in"
+    EVENT_VERIFICATION_CREATED          = "verification.created"
+    EVENT_VERIFICATION_DELIVERED        = "verification.delivered"
+    EVENT_VERIFICATION_VERIFIED         = "verification.verified"
+    EVENT_VERIFICATION_EXPIRED          = "verification.expired"
+    EVENT_VERIFICATION_FAILED           = "verification.failed"
+    EVENT_VERIFICATION_RESENT           = "verification.resent"
+    EVENT_VERIFICATION_DELIVERY_FAILED  = "verification.delivery_failed"
+    EVENT_CONTACT_AUTO_FLAGGED          = "contact.auto_flagged"
+    EVENT_CONTACT_MARKED_VALID          = "contact.marked_valid"
+    EVENT_CONTACTS_LOOKUP_COMPLETED     = "contacts.lookup_completed"
+    EVENT_CONTACTS_BULK_MARKED_VALID    = "contacts.bulk_marked_valid"
+
+    # Source of a list-health event. Frozen enum — new values will be
+    # added in minor SDK versions, never removed.
+    module ListHealthEventSource
+      SEND_FAILURE    = "send_failure"
+      CARRIER_LOOKUP  = "carrier_lookup"
+      USER_ACTION     = "user_action"
+      BULK_MARK_VALID = "bulk_mark_valid"
+
+      ALL = [SEND_FAILURE, CARRIER_LOOKUP, USER_ACTION, BULK_MARK_VALID].freeze
+    end
+
     class << self
       # Verify webhook signature from Sendly.
       #
@@ -146,7 +180,7 @@ module Sendly
     attr_reader :id, :status, :to, :from, :direction, :organization_id,
                 :text, :error, :error_code, :delivered_at, :failed_at,
                 :created_at, :segments, :credits_used, :message_format, :media_urls,
-                :retry_count, :metadata
+                :retry_count, :metadata, :batch_id
 
     def initialize(data)
       @id = data[:id] || data[:message_id] || ''
@@ -167,6 +201,7 @@ module Sendly
       @media_urls = data[:media_urls]
       @retry_count = data[:retry_count]
       @metadata = data[:metadata]
+      @batch_id = data[:batch_id]
     end
 
     def message_id
@@ -185,7 +220,8 @@ module Sendly
         delivered_at: @delivered_at,
         failed_at: @failed_at,
         segments: @segments,
-        credits_used: @credits_used
+        credits_used: @credits_used,
+        batch_id: @batch_id
       }.compact
     end
   end

data/lib/sendly.rb

@@ -19,6 +19,7 @@ require_relative "sendly/contacts_resource"
 require_relative "sendly/conversations_resource"
 require_relative "sendly/labels_resource"
 require_relative "sendly/drafts_resource"
+require_relative "sendly/rules_resource"
 require_relative "sendly/enterprise"
 
 # Sendly Ruby SDK

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 3.26.0
+  version: 3.29.0
 platform: ruby
 authors:
 - Sendly
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -135,6 +135,7 @@ files:
 - lib/sendly/labels_resource.rb
 - lib/sendly/media.rb
 - lib/sendly/messages.rb
+- lib/sendly/rules_resource.rb
 - lib/sendly/templates_resource.rb
 - lib/sendly/types.rb
 - lib/sendly/verify.rb