millionsend 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9260a596d597a0aad944da04656fb5c99606374b48b9e235f3e883917ef2bc6
-  data.tar.gz: 677e347b5604bd68edf198df96802d652470d3e4aef679460fdb24bce3563993
+  metadata.gz: b7af1c0b498dd1ff772b222aac67dce73ea3c1f4c71a7d2a9d4d3e427ef8a141
+  data.tar.gz: 8f019e8f091187618102b125d58bfe0233be20f838cb61059ef5e6ed979d1e09
 SHA512:
-  metadata.gz: fb4c0031b1c2b22911ebba5b0f5d45c05b613196b2e665c11212d5146c5e7102c4cdbba343245acf814bffc6e8394d603c2c124d325a25c4c70fc1a49ac21789
-  data.tar.gz: bae43393a0387f459f882638a9eb6a7961cdc6d9b94b602d914cd199c071ce7e403706610e89e1426273e347cb1a3d6393518cf7d9f91d567352692c8765f2fe
+  metadata.gz: b382ae969cd92102bb62a9108d64f7bf39b159c98c660ad03b2726a58573e81dde023ee474c2194e744d5c34775e8a1fb667bf9e64c52058850ddc4c9b19d9e6
+  data.tar.gz: 1666f792e81b7eaab5cc93fb314e11a80e90e92dec25a6a0c12ef0c090ddf4d03a48f982d7059f952e254af7878dfc62c6680e28d7a47a199e6989b5fbe9daf3

data/README.md

@@ -123,12 +123,20 @@ Millionsend::Contacts.get("ada@acme.dev") # by id or email; also resend-ruby's g
 Millionsend::Contacts.update(id: contact[:id], unsubscribed: true, first_name: nil) # nil clears
 Millionsend::Contacts.remove("ada@acme.dev")
 Millionsend::Contacts.list(limit: 50)
+# Bulk read (MillionSend extension): carry the property map and the topic subscriptions on every
+# item, so an audience reads in one request per 100 contacts instead of one per contact
+Millionsend::Contacts.list(limit: 100, include: ["properties", "topics"]) # ?include=properties,topics
 
 # Topic subscriptions (granular unsubscribe) — PATCH /contacts/:id/topics
 Millionsend::Contacts::Topics.update(email: "ada@acme.dev", topics: [{ id: topic_id, subscription: "opt_out" }]) # resend-ruby shape
 Millionsend::Contacts.topics_update("ada@acme.dev", [{ id: topic_id, subscription: "opt_out" }])                 # positional
 Millionsend::Contacts::Topics.list(email: "ada@acme.dev") # GET /contacts/:id/topics — every topic with its effective
-                                                          # subscription; explicit: false when it is the topic's default
+                                                          # subscription (explicit: false when it is the topic's default)
+                                                          # and its visibility ("public" | "private")
+
+# Preference-center link (MillionSend extension) — POST /contacts/:id/preferences-link
+link = Millionsend::Contacts.preferences_link("ada@acme.dev") # by id or email; also preferences_link(id: ...) / (email: ...)
+link[:url] # the contact's hosted preference page; no expiry, so show it only to that contact
 
 # Segment membership — POST / DELETE /contacts/:id/segments/:segment_id
 Millionsend::Contacts::Segments.add("ada@acme.dev", segment_id)
@@ -143,6 +151,16 @@ result = Millionsend::Contacts::Batch.create(
 result[:data]   # [{ index:, id:, status: "created" | "updated" | "skipped" }]
 result[:counts] # { created:, updated:, skipped:, failed: }
 result[:errors] # permissive mode only: [{ index:, message: }]
+
+# Bulk lookup (MillionSend extension) — up to 1000 contacts by id or email in one request, in
+# request order; unknown entries are listed, not errors — one request against the rate limit
+found = Millionsend::Contacts::Batch.get([contact[:id], "b@acme.dev", { email: "c@acme.dev" }], include: ["topics"])
+found[:data]    # [{ object: "contact", id:, email:, first_name:, last_name:, created_at:, unsubscribed:, topics: }]
+found[:missing] # [{ index:, email: }] / [{ index:, id: }] — request entries that matched nobody
+
+# Bulk delete (MillionSend extension) — up to 1000 per call, exactly one of ids: / emails:
+Millionsend::Contacts::Batch.remove(emails: ["a@acme.dev", "b@acme.dev"]) # or ids: [...]
+# => { data: [{ object: "contact", contact: "<uuid>", deleted: true }, ...] } — only the rows actually deleted
 ```
 
 Contacts are addressable by id or email; when an `update` hash carries both, the email wins.
@@ -237,14 +255,26 @@ hook = Millionsend::Webhooks.create(
   signing_secret: "whsec_..." # optional: reuse an existing secret so the receiver keeps verifying
 )
 hook[:signing_secret]
-Millionsend::Webhooks.get(hook[:id]) # also returns signing_secret
+Millionsend::Webhooks.get(hook[:id]) # also returns signing_secret and previous_secret_expires_at
 Millionsend::Webhooks.list
 Millionsend::Webhooks.update(hook[:id], events: ["email.opened"], status: "disabled")
 Millionsend::Webhooks.remove(hook[:id])
+
+# Rotate the signing secret (MillionSend extension) — POST /webhooks/:id/rotate
+rotated = Millionsend::Webhooks.rotate(hook[:id])                                         # mints a new secret, 24h overlap
+rotated = Millionsend::Webhooks.rotate(hook[:id], signing_secret: "whsec_...", overlap_hours: 0) # bring your own, no overlap
+rotated[:signing_secret]              # the secret now signing deliveries
+rotated[:previous_secret_expires_at]  # ISO time until which the old secret also signs, or nil
 ```
 
+During the overlap window (`overlap_hours`, 0–72, default 24) every delivery carries both
+signatures, so a receiver holding either verifies; `Webhooks.get` reports the window's end
+as `previous_secret_expires_at` (`nil` when none is open).
+
 Events: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`,
-`email.complained`, `email.opened`, `email.clicked`, `deliverability.warning`,
+`email.complained`, `email.opened`, `email.clicked`, `contact.created`, `contact.updated`,
+`contact.deleted`, `contact.unsubscribed`, `contact.resubscribed`, `contact.topic_opt_in`,
+`contact.topic_opt_out`, `suppression.added`, `suppression.removed`, `deliverability.warning`,
 `deliverability.paused`, `quota.warning`, `quota.reached`, `quota.paused`.
 
 ### API keys
@@ -286,6 +316,7 @@ segment = Millionsend::Segments.create(
 Millionsend::Segments.get(segment[:id]) # includes a live contact_count
 Millionsend::Segments.list
 Millionsend::Segments.contacts(segment[:id], limit: 50) # the contacts currently matching
+Millionsend::Segments.contacts(segment[:id], include: ["properties", "topics"]) # with each contact's extras, as Contacts.list
 Millionsend::Segments.update(segment[:id], name: "Pro tier")
 Millionsend::Segments.remove(segment[:id])
 ```
@@ -368,8 +399,9 @@ works as in resend-ruby. Notes:
   Resend's audiences alias.
 - Not in the API (yet), so not here: broadcast recipients/clicked links, email sharing and
   metrics, contact imports, receiving, automations, logs, OAuth grants, webhook event replay.
-- MillionSend extensions with no Resend counterpart: `Segments`, `Contacts::Batch`, `Usage`,
-  `Deliverability`, `Emails.get_insights`, `Suppressions` `origin: "unsubscribe"`.
+- MillionSend extensions with no Resend counterpart: `Segments`, `Contacts::Batch`,
+  `Contacts.preferences_link`, `Webhooks.rotate`, `Usage`, `Deliverability`,
+  `Emails.get_insights`, `Suppressions` `origin: "unsubscribe"`.
 
 ## License
 

data/lib/millionsend/contacts.rb

@@ -29,11 +29,12 @@ module Millionsend
         Millionsend::Request.new(method: :delete, path: member_path(id_or_email)).perform
       end
 
-      # GET /contacts — accepts limit:/after:/before:.
+      # GET /contacts — accepts limit:/after:/before: and include:
+      # (["properties", "topics"]) to carry the property map and the topic
+      # subscriptions on every item, as Contacts.get and Topics.list return them.
       def list(options = {})
-        Millionsend::Request.new(
-          method: :get, path: "/contacts", query: Millionsend::Util.list_query(options)
-        ).perform
+        query = Millionsend::Util.list_query(options).merge(include: Millionsend::Util.include_query(options[:include]))
+        Millionsend::Request.new(method: :get, path: "/contacts", query: query).perform
       end
 
       # PATCH /contacts/:id_or_email/topics with a bare array of
@@ -42,11 +43,31 @@ module Millionsend
         Millionsend::Request.new(method: :patch, path: "#{member_path(id_or_email)}/topics", body: topics).perform
       end
 
+      # POST /contacts/:id_or_email/preferences-link — the contact's hosted
+      # preference page, { object: "preferences_link", contact:, url: }. The
+      # url is a contact-scoped capability with no expiry: hand it only to that
+      # contact. 422 when the instance cannot build hosted links.
+      def preferences_link(id_or_email)
+        Millionsend::Request.new(method: :post, path: "#{member_path(id_or_email)}/preferences-link").perform
+      end
+
       # Every member method also accepts resend-ruby's addressing hash
       # ({ id: } / { email: } / { contact_id: }) in place of the bare value.
       def member_path(id_or_email)
-        id_or_email = id_or_email[:email] || id_or_email[:id] || id_or_email[:contact_id] if id_or_email.is_a?(Hash)
-        "/contacts/#{Millionsend::Util.encode(id_or_email)}"
+        "/contacts/#{Millionsend::Util.encode(unwrap(id_or_email))}"
+      end
+
+      # One /contacts/batch/get entry. The wire wants { id: } and { email: }
+      # told apart, and only an email carries "@".
+      def address(id_or_email)
+        value = unwrap(id_or_email)
+        value.to_s.include?("@") ? { email: value } : { id: value }
+      end
+
+      private
+
+      def unwrap(id_or_email)
+        id_or_email.is_a?(Hash) ? id_or_email[:email] || id_or_email[:id] || id_or_email[:contact_id] : id_or_email
       end
     end
 
@@ -54,9 +75,10 @@ module Millionsend
     module Topics
       class << self
         # GET /contacts/:id_or_email/topics — { id: | email: } or a bare id/email.
-        # Every topic comes back with the contact's effective subscription;
-        # explicit: false means it is the topic's default, not a stored choice.
-        # Unpaginated, like Topics.list.
+        # Every topic comes back with the contact's effective subscription
+        # (explicit: false means it is the topic's default, not a stored
+        # choice) and its visibility ("public" | "private"). Unpaginated, like
+        # Topics.list.
         def list(params)
           Millionsend::Request.new(method: :get, path: "#{Millionsend::Contacts.member_path(params)}/topics").perform
         end
@@ -68,7 +90,8 @@ module Millionsend
       end
     end
 
-    # Bulk contact creation — a MillionSend extension (Resend imports via CSV).
+    # Bulk contact creation and deletion — MillionSend extensions (Resend
+    # imports via CSV and deletes one at a time).
     module Batch
       class << self
         # POST /contacts/batch with a bare array of up to 1000 create payloads.
@@ -85,6 +108,25 @@ module Millionsend
             **Millionsend::Util.request_options(options)
           ).perform
         end
+
+        # POST /contacts/batch/get — up to 1000 contacts by id or email (bare
+        # values or addressing hashes, like Contacts.get) in one request, one
+        # call against the rate limit. Returns { data: [...] } in request order
+        # plus missing: [{ index:, id: | email: }] for the entries that matched
+        # nobody — those never fail the call. include: ["properties", "topics"]
+        # attaches the same extras as Contacts.list.
+        def get(addresses, options = {})
+          body = { contacts: addresses.map { |a| Millionsend::Contacts.address(a) }, include: options[:include] }
+          Millionsend::Request.new(method: :post, path: "/contacts/batch/get", body: body.compact).perform
+        end
+
+        # POST /contacts/batch/remove — { ids: [...] } or { emails: [...] }
+        # (exactly one, up to 1000). Returns { data: [{ object:, contact:,
+        # deleted: true }] } listing only the rows actually deleted; unknown
+        # ids or addresses are skipped.
+        def remove(params)
+          Millionsend::Request.new(method: :post, path: "/contacts/batch/remove", body: params).perform
+        end
       end
     end
 

data/lib/millionsend/segments.rb

@@ -23,11 +23,12 @@ module Millionsend
       end
 
       # GET /segments/:id/contacts — the contacts currently matching, paginated
-      # with limit:/after:/before:.
+      # with limit:/after:/before:; include: (["properties", "topics"]) as on
+      # Contacts.list.
       def contacts(id, options = {})
+        query = Millionsend::Util.list_query(options).merge(include: Millionsend::Util.include_query(options[:include]))
         Millionsend::Request.new(
-          method: :get, path: "/segments/#{Millionsend::Util.encode(id)}/contacts",
-          query: Millionsend::Util.list_query(options)
+          method: :get, path: "/segments/#{Millionsend::Util.encode(id)}/contacts", query: query
         ).perform
       end
 

data/lib/millionsend/util.rb

@@ -33,6 +33,13 @@ module Millionsend
       { limit: options[:limit], after: options[:after], before: options[:before] }
     end
 
+    # ?include= for the contact lists: the names comma-joined, or nil (dropped
+    # from the query) when none were given.
+    def include_query(include)
+      names = Array(include)
+      names.empty? ? nil : names.join(",")
+    end
+
     # Per-request options for the Request constructor. Both call shapes land in
     # the same trailing positional hash: the original `idempotency_key: "k"` and
     # resend-ruby's keyword form `options: { idempotency_key: "k" }`, so the

data/lib/millionsend/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Millionsend
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/millionsend/webhooks.rb

@@ -10,7 +10,8 @@ module Millionsend
         Millionsend::Request.new(method: :post, path: "/webhooks", body: params).perform
       end
 
-      # GET /webhooks/:id — includes signing_secret.
+      # GET /webhooks/:id — includes signing_secret and
+      # previous_secret_expires_at (nil unless a rotation's overlap window is open).
       def get(id)
         Millionsend::Request.new(method: :get, path: member_path(id)).perform
       end
@@ -30,6 +31,14 @@ module Millionsend
         Millionsend::Request.new(method: :delete, path: member_path(id)).perform
       end
 
+      # POST /webhooks/:id/rotate — signing_secret (optional whsec_ value to
+      # bring your own; omitted mints one) and overlap_hours (0..72, default
+      # 24) during which deliveries carry both signatures. Returns { object:,
+      # id:, signing_secret:, previous_secret_expires_at: }.
+      def rotate(id, params = {})
+        Millionsend::Request.new(method: :post, path: "#{member_path(id)}/rotate", body: params).perform
+      end
+
       private
 
       def member_path(id)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: millionsend
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - MillionSend
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake