sendly 3.27.1 → 3.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68163da427953fe0e6323698c1f535ff209375de0d3ef39636a6baa058ec2e73
-  data.tar.gz: 51e7b707e397c788fa7d93360ff20970df48bd9c89510c3acc8c55ecf68e3f9a
+  metadata.gz: 0aa8097776c931f504cc3f006783ed8232691fc48c35c93b8930437c9f5480b5
+  data.tar.gz: 74cfe38cea2edefae5a4173dbbae2ff4df2a3364e69de2329191ef95fd26195b
 SHA512:
-  metadata.gz: 4885dadab414fb8f67f61eb2bd333294081ccb7c2db7c26be3d6e2ebfa283c6318fae433e23d1de126d87108bc1d0970c680607df6d025ef4fa473eb64a463e8
-  data.tar.gz: 992233c97e17dcb0af07df5caf61e4031fb1bf378fb653e6dba158ea831e4d5ed18917a4429683daf77cda6783893e78486b01fde6dd7d51303d8feaa8d79951
+  metadata.gz: 40d6bb9e8df8757fa585253b39b49e85973f7959f1278b8354c803b293047bb0dbf279dafd5c5550e61d4b6a26ed78ada5295ab686a312dc32f026d46ff7203f
+  data.tar.gz: b4ee727e07b7fc3fa75326e36ae073c62d50e6d3c98b5905c745444c80d6dd358ab19a5ed36c0853af3c07eba7fbba50d6db7389f469c3555abf15d6960b5742

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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (3.27.1)
+    sendly (3.30.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 

data/README.md

@@ -354,7 +354,7 @@ message.pending?     # => true/false
 
 | Tier | Countries | Credits per SMS |
 |------|-----------|-----------------|
-| Domestic | US, CA | 1 |
+| Domestic | US, CA | 2 |
 | Tier 1 | GB, PL, IN, etc. | 8 |
 | Tier 2 | FR, JP, AU, etc. | 12 |
 | Tier 3 | DE, IT, MX, etc. | 16 |

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/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.27.0"
+  VERSION = "3.30.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.
       #

data/lib/sendly/webhooks_resource.rb

@@ -110,6 +110,56 @@ module Sendly
       @client.post("/webhooks/#{webhook_id}/reset-circuit")
     end
 
+    # Replay failed or cancelled webhook deliveries from the audit log.
+    #
+    # Use after a customer endpoint has recovered from an outage to re-fire
+    # deliveries we recorded but couldn't deliver. Each replay creates a new
+    # delivery row preserving the original event_id so customers can dedupe.
+    # Rejects with HTTP 409 if the circuit is currently open — call
+    # {#reset_circuit} first.
+    #
+    # @param webhook_id [String] Webhook ID
+    # @param since [String, nil] ISO-8601, default now − 24h
+    # @param until_ [String, nil] ISO-8601, default now
+    # @param event_types [Array<String>, nil] Filter by event type
+    # @param statuses [Array<String>, nil] Default ["failed", "cancelled"]
+    # @param limit [Integer, nil] Max deliveries to requeue (default 1000, max 10000)
+    # @return [Hash] Counts of requeued deliveries plus delivery IDs
+    def redeliver(webhook_id, since: nil, until_: nil, event_types: nil, statuses: nil, limit: nil)
+      validate_webhook_id!(webhook_id)
+      body = {}
+      body[:since] = since unless since.nil?
+      body[:until] = until_ unless until_.nil?
+      body[:event_types] = event_types unless event_types.nil?
+      body[:statuses] = statuses unless statuses.nil?
+      body[:limit] = limit unless limit.nil?
+      @client.post("/webhooks/#{webhook_id}/redeliver", body)
+    end
+
+    # Backfill missed webhook events from the underlying message log.
+    #
+    # Use when a circuit-breaker outage left events with no audit row (the
+    # case {#redeliver} cannot recover). Synthesized events have fresh IDs;
+    # clients should dedupe by event.data.object.id (the message ID).
+    # Rejects with HTTP 409 if the circuit is currently open — call
+    # {#reset_circuit} first.
+    #
+    # @param webhook_id [String] Webhook ID
+    # @param since [String, nil] ISO-8601, default now − 24h
+    # @param until_ [String, nil] ISO-8601, default now
+    # @param event_types [Array<String>, nil] Filter by event type
+    # @param limit [Integer, nil] Max events to synthesize (default 1000, max 10000)
+    # @return [Hash] Counts grouped by event type plus delivery IDs
+    def backfill(webhook_id, since: nil, until_: nil, event_types: nil, limit: nil)
+      validate_webhook_id!(webhook_id)
+      body = {}
+      body[:since] = since unless since.nil?
+      body[:until] = until_ unless until_.nil?
+      body[:event_types] = event_types unless event_types.nil?
+      body[:limit] = limit unless limit.nil?
+      @client.post("/webhooks/#{webhook_id}/backfill", body)
+    end
+
     # Rotate the webhook signing secret
     #
     # @param webhook_id [String] Webhook ID

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 3.27.1
+  version: 3.30.0
 platform: ruby
 authors:
 - Sendly
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-04-06 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday